8
0
فهرست منبع

Improved API docs.

Piotrek Koszuliński 8 سال پیش
والد
کامیت
9f25c9330f
2فایلهای تغییر یافته به همراه19 افزوده شده و 10 حذف شده
  1. 16 7
      packages/ckeditor5-utils/src/emittermixin.js
  2. 3 3
      packages/ckeditor5-utils/src/eventinfo.js

+ 16 - 7
packages/ckeditor5-utils/src/emittermixin.js

@@ -22,14 +22,23 @@ const _emitterId = Symbol( 'emitterId' );
  */
  */
 const EmitterMixin = {
 const EmitterMixin = {
 	/**
 	/**
-	 * Registers a callback function to be executed when an event is fired. Events can be grouped in namespaces using `:`.
+	 * Registers a callback function to be executed when an event is fired.
+	 *
+	 * Events can be grouped in namespaces using `:`.
 	 * When namespaced event is fired, it additionaly fires all callbacks for that namespace.
 	 * When namespaced event is fired, it additionaly fires all callbacks for that namespace.
 	 *
 	 *
 	 *		myEmitter.on( 'myGroup', genericCallback );
 	 *		myEmitter.on( 'myGroup', genericCallback );
 	 *		myEmitter.on( 'myGroup:myEvent', specificCallback );
 	 *		myEmitter.on( 'myGroup:myEvent', specificCallback );
-	 *		myEmitter.fire( 'myGroup' ); // genericCallback is fired.
-	 *		myEmitter.fire( 'myGroup:myEvent' ); // both genericCallback and specificCallback are fired.
-	 *		myEmitter.fire( 'myGroup:foo' ); // genericCallback is fired even though there are no callbacks for "foo".
+	 *
+	 *		// genericCallback is fired.
+	 *		myEmitter.fire( 'myGroup' );
+	 *		// both genericCallback and specificCallback are fired.
+	 *		myEmitter.fire( 'myGroup:myEvent' );
+	 *		// genericCallback is fired even though there are no callbacks for "foo".
+	 *		myEmitter.fire( 'myGroup:foo' );
+	 *
+	 * An event callback can {@link module:utils/eventinfo~EventInfo#stop stop the event} and
+	 * set the {@link module:utils/eventinfo~EventInfo#return return value} of the {@link #fire} method.
 	 *
 	 *
 	 * @method #on
 	 * @method #on
 	 * @param {String} event The name of the event.
 	 * @param {String} event The name of the event.
@@ -135,9 +144,6 @@ const EmitterMixin = {
 	 * the priority value the sooner the callback will be fired. Events having the same priority are called in the
 	 * the priority value the sooner the callback will be fired. Events having the same priority are called in the
 	 * order they were added.
 	 * order they were added.
 	 * @param {Object} [options.context] The object that represents `this` in the callback. Defaults to the object firing the event.
 	 * @param {Object} [options.context] The object that represents `this` in the callback. Defaults to the object firing the event.
-	 * @returns By default the method returns `undefined`. However, the return value can be changed by listeners
-	 * through modification of the {@link module:utils/emitterinfo~EmitterInfo#return}'s value (the event info
-	 * is the first param of every callback).
 	 */
 	 */
 	listenTo( emitter, event, callback, options ) {
 	listenTo( emitter, event, callback, options ) {
 		let emitterInfo, eventCallbacks;
 		let emitterInfo, eventCallbacks;
@@ -247,6 +253,9 @@ const EmitterMixin = {
 	 * @method #fire
 	 * @method #fire
 	 * @param {String|module:utils/eventinfo~EventInfo} eventOrInfo The name of the event or `EventInfo` object if event is delegated.
 	 * @param {String|module:utils/eventinfo~EventInfo} eventOrInfo The name of the event or `EventInfo` object if event is delegated.
 	 * @param {...*} [args] Additional arguments to be passed to the callbacks.
 	 * @param {...*} [args] Additional arguments to be passed to the callbacks.
+	 * @returns {*} By default the method returns `undefined`. However, the return value can be changed by listeners
+	 * through modification of the {@link module:utils/eventinfo~EventInfo#return}'s value (the event info
+	 * is the first param of every callback).
 	 */
 	 */
 	fire( eventOrInfo, ...args ) {
 	fire( eventOrInfo, ...args ) {
 		const eventInfo = eventOrInfo instanceof EventInfo ? eventOrInfo : new EventInfo( this, eventOrInfo );
 		const eventInfo = eventOrInfo instanceof EventInfo ? eventOrInfo : new EventInfo( this, eventOrInfo );

+ 3 - 3
packages/ckeditor5-utils/src/eventinfo.js

@@ -64,10 +64,10 @@ export default class EventInfo {
 		 *
 		 *
 		 * It's `undefined` by default and can be changed by an event listener:
 		 * It's `undefined` by default and can be changed by an event listener:
 		 *
 		 *
-		 *		editor.data.on( 'getSelectedContent', ( evt ) => {
-		 *			// This listener will make `editor.data.getSelectedContent()`
+		 *		dataController.fire( 'getSelectedContent', ( evt ) => {
+		 *			// This listener will make `dataController.fire( 'getSelectedContent' )`
 		 *			// always return an empty DocumentFragment.
 		 *			// always return an empty DocumentFragment.
-		 *			evt.return = new DataFragment();
+		 *			evt.return = new DocumentFragment();
 		 *
 		 *
 		 *			// Make sure no other listeners are executed.
 		 *			// Make sure no other listeners are executed.
 		 *			evt.stop();
 		 *			evt.stop();