Przeglądaj źródła

More API docs fixes.

Piotrek Koszuliński 9 lat temu
rodzic
commit
082de74fb7

+ 18 - 18
packages/ckeditor5-utils/src/collection.js

@@ -37,7 +37,7 @@ export default class Collection {
 		 * The internal list of items in the collection.
 		 *
 		 * @private
-		 * @type {Object[]}
+		 * @member {Object[]}
 		 */
 		this._items = [];
 
@@ -45,7 +45,7 @@ export default class Collection {
 		 * The internal map of items in the collection.
 		 *
 		 * @private
-		 * @type {Map}
+		 * @member {Map}
 		 */
 		this._itemMap = new Map();
 
@@ -53,7 +53,7 @@ export default class Collection {
 		 * The name of the property which is considered to identify an item.
 		 *
 		 * @private
-		 * @type {String}
+		 * @member {String}
 		 */
 		this._idProperty = options && options.idProperty || 'id';
 	}
@@ -61,7 +61,7 @@ export default class Collection {
 	/**
 	 * The number of items available in the collection.
 	 *
-	 * @property length
+	 * @member {Number} #length
 	 */
 	get length() {
 		return this._items.length;
@@ -258,20 +258,20 @@ export default class Collection {
 	[ Symbol.iterator ]() {
 		return this._items[ Symbol.iterator ]();
 	}
-}
 
-mix( Collection, EmitterMixin );
+	/**
+	 * Fired when an item is added to the collection.
+	 *
+	 * @event module:utils/collection~Collection#add
+	 * @param {Object} item The added item.
+	 */
 
-/**
- * Fired when an item is added to the collection.
- *
- * @event module:utils/collection~Collection#add
- * @param {Object} item The added item.
- */
+	/**
+	 * Fired when an item is removed from the collection.
+	 *
+	 * @event module:utils/collection~Collection#remove
+	 * @param {Object} item The removed item.
+	 */
+}
 
-/**
- * Fired when an item is removed from the collection.
- *
- * @event module:utils/collection~Collection#remove
- * @param {Object} item The removed item.
- */
+mix( Collection, EmitterMixin );

+ 2 - 2
packages/ckeditor5-utils/src/comparearrays.js

@@ -21,7 +21,7 @@
  *
  * @param {Array} a Array that is compared.
  * @param {Array} b Array to compare with.
- * @returns {module:utils/arrayrelation~ArrayRelation} How array `a` is related to `b`.
+ * @returns {module:utils/comparearrays~ArrayRelation} How array `a` is related to `b`.
  */
 export default function compareArrays( a, b ) {
 	const minLen = Math.min( a.length, b.length );
@@ -47,5 +47,5 @@ export default function compareArrays( a, b ) {
 }
 
 /**
- * @typedef {'extension'|'same'|'prefix'} module:utils/arrayrelation~ArrayRelation
+ * @typedef {'extension'|'same'|'prefix'} module:utils/comparearrays~ArrayRelation
  */

+ 2 - 2
packages/ckeditor5-utils/src/config.js

@@ -23,7 +23,7 @@ export default class Config {
 		 * Store for the whole configuration.
 		 *
 		 * @private
-		 * @member {Object} #_config
+		 * @member {Object}
 		 */
 		this._config = {};
 
@@ -196,7 +196,7 @@ export default class Config {
 	}
 
 	/**
-	 * Iterate through passed object and call {@link #_setToTarget} method with object key and value for each property.
+	 * Iterates through passed object and calls {@link #_setToTarget} method with object key and value for each property.
 	 *
 	 * @private
 	 * @param {Object} target Nested config object.

+ 0 - 1
packages/ckeditor5-utils/src/difftochanges.js

@@ -25,7 +25,6 @@
  *
  *		input.join( '' ) == output.join( '' ); // -> true
  *
- * @method diffToChanges
  * @param {Array.<'equal'|'insert'|'delete'>} diff Result of {@link module:utils/diff~diff}.
  * @param {String|Array} output The string or array which was passed as diff's output.
  * @returns {Array.<Object>} Set of changes (insert or delete) which need to be applied to the input

+ 1 - 2
packages/ckeditor5-utils/src/elementreplacer.js

@@ -17,7 +17,7 @@ export default class ElementReplacer {
 		 * The elements replaced by {@link #replace} and their replacements.
 		 *
 		 * @private
-		 * @member {Array.<Object>} ~ElementReplacer#_replacedElements
+		 * @member {Array.<Object>}
 		 */
 		this._replacedElements = [];
 	}
@@ -29,7 +29,6 @@ export default class ElementReplacer {
 	 *
 	 * @param {HTMLElement} element The element to replace.
 	 * @param {HTMLElement} [newElement] The replacement element. If not passed, then the `element` will just be hidden.
-
 	 */
 	replace( element, newElement ) {
 		this._replacedElements.push( { element, newElement } );

+ 8 - 9
packages/ckeditor5-utils/src/emittermixin.js

@@ -15,7 +15,7 @@ import priorities from './priorities.js';
  * Mixin that injects the events API into its host.
  *
  * @mixin EmitterMixin
- * @implements  module:utils/emittermixin~Emitter
+ * @implements module:utils/emittermixin~Emitter
  */
 const EmitterMixin = {
 	/**
@@ -28,15 +28,14 @@ const EmitterMixin = {
 	 *		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".
 	 *
+	 * @method #on
 	 * @param {String} event The name of the event.
 	 * @param {Function} callback The function to be called on event.
 	 * @param {Object} [options={}] Additional options.
 	 * @param {module:utils/priorities~PriorityString|Number} [options.priority='normal'] The priority of this event callback. The higher
 	 * the priority value the sooner the callback will be fired. Events having the same priority are called in the
 	 * order they were added.
-	 * -+
 	 * @param {Object} [options.context] The object that represents `this` in the callback. Defaults to the object firing the event.
-	 * @method #on
 	 */
 	on( event, callback, options = {} ) {
 		createEventNamespace( this, event );
@@ -74,6 +73,7 @@ const EmitterMixin = {
 	 * Registers a callback function to be executed on the next time the event is fired only. This is similar to
 	 * calling {@link #on} followed by {@link #off} in the callback.
 	 *
+	 * @method #once
 	 * @param {String} event The name of the event.
 	 * @param {Function} callback The function to be called on event.
 	 * @param {Object} [options={}] Additional options.
@@ -81,7 +81,6 @@ const EmitterMixin = {
 	 * the priority value the sooner the callback will be fired. Events having the same priority are called in the
 	 * order they were added.
 	 * @param {Object} [options.context] The object that represents `this` in the callback. Defaults to the object firing the event.
-	 * @method #once
 	 */
 	once( event, callback, options ) {
 		const onceCallback = function( event ) {
@@ -99,11 +98,11 @@ const EmitterMixin = {
 	/**
 	 * Stops executing the callback on the given event.
 	 *
+	 * @method #off
 	 * @param {String} event The name of the event.
 	 * @param {Function} callback The function to stop being called.
 	 * @param {Object} [context] The context object to be removed, pared with the given callback. To handle cases where
 	 * the same callback is used several times with different contexts.
-	 * @method #off
 	 */
 	off( event, callback, context ) {
 		const lists = getCallbacksListsForNamespace( this, event );
@@ -124,6 +123,7 @@ const EmitterMixin = {
 	/**
 	 * Registers a callback function to be executed when an event is fired in a specific (emitter) object.
 	 *
+	 * @method #listenTo
 	 * @param {module:utils/emittermixin~Emitter} emitter The object that fires the event.
 	 * @param {String} event The name of the event.
 	 * @param {Function} callback The function to be called on event.
@@ -132,7 +132,6 @@ const EmitterMixin = {
 	 * the priority value the sooner the callback will be fired. Events having the same priority are called in the
 	 * order they were added.
 	 * @param {Object} [options.context] The object that represents `this` in the callback. Defaults to the object firing the event.
-	 * @method #listenTo
 	 */
 	listenTo( emitter, event, callback, options ) {
 		let emitters, emitterId, emitterInfo, eventCallbacks;
@@ -184,12 +183,12 @@ const EmitterMixin = {
 	 * * To stop listening to all events fired by a specific object.
 	 * * To stop listening to all events fired by all object.
 	 *
+	 * @method #stopListening
 	 * @param {module:utils/emittermixin~Emitter} [emitter] The object to stop listening to. If omitted, stops it for all objects.
 	 * @param {String} [event] (Requires the `emitter`) The name of the event to stop listening to. If omitted, stops it
 	 * for all events from `emitter`.
 	 * @param {Function} [callback] (Requires the `event`) The function to be removed from the call list for the given
 	 * `event`.
-	 * @method #stopListening
 	 */
 	stopListening( emitter, event, callback ) {
 		let emitters = this._listeningTo;
@@ -235,9 +234,9 @@ const EmitterMixin = {
 	 * The first parameter passed to callbacks is an {@link module:utils/eventinfo~EventInfo} object,
 	 * followed by the optional `args` provided in the `fire()` method call.
 	 *
+	 * @method #fire
 	 * @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.
-	 * @method #fire
 	 */
 	fire( eventOrInfo, ...args ) {
 		const eventInfo = eventOrInfo instanceof EventInfo ? eventOrInfo : new EventInfo( this, eventOrInfo );
@@ -340,10 +339,10 @@ const EmitterMixin = {
 	 * * To stop delegating a specific event to all emitters.
 	 * * To stop delegating a specific event to a specific emitter.
 	 *
+	 * @method #stopDelegating
 	 * @param {String} [event] The name of the event to stop delegating. If omitted, stops it all delegations.
 	 * @param {module:utils/emittermixin~Emitter} [emitter] (requires `event`) The object to stop delegating a particular event to.
 	 * If omitted, stops delegation of `event` to all emitters.
-	 * @method #stopDelegating
 	 */
 	stopDelegating( event, emitter ) {
 		if ( !this._delegations ) {

+ 7 - 3
packages/ckeditor5-utils/src/env.js

@@ -13,20 +13,24 @@ const userAgent = navigator.userAgent.toLowerCase();
 
 /**
  * A namespace containing environment and browser information.
+ *
+ * @namespace
  */
-export default {
+const env = {
 	/**
 	 * Indicates that application is running on Macintosh.
 	 *
-	 * @member {Boolean}
+	 * @static
+	 * @member {Boolean} module:utils/env~env#mac
 	 */
 	mac: isMac( userAgent )
 };
 
+export default env;
+
 /**
  * Checks if User Agent represented by the string is running on Macintosh.
  *
- * @function isMac
  * @param {String} userAgent **Lowercase** `navigator.userAgent` string.
  * @returns {Boolean} Whether User Agent is running on Macintosh or not.
  */

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

@@ -14,25 +14,29 @@ import spy from './spy.js';
  * manipulate it.
  */
 export default class EventInfo {
+	/**
+	 * @param {Object} source The emitter.
+	 * @param {String} name The event name.
+	 */
 	constructor( source, name ) {
 		/**
 		 * The object that fired the event.
 		 *
-		 * @member #source
+		 * @member {Object}
 		 */
 		this.source = source;
 
 		/**
 		 * The event name.
 		 *
-		 * @member #name
+		 * @member {String}
 		 */
 		this.name = name;
 
 		/**
 		 * Path this event has followed. See {@link module:utils/emittermixin~EmitterMixin#delegate}.
 		 *
-		 * @member #path
+		 * @member {Array.<Object>}
 		 */
 		this.path = [];
 

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

@@ -8,6 +8,7 @@
 /**
  * @module utils/focustracker
  */
+
 import DomEmitterMixin from './dom/emittermixin.js';
 import ObservableMixin from './observablemixin.js';
 import CKEditorError from './ckeditorerror.js';
@@ -23,8 +24,8 @@ import mix from './mix.js';
  * which contain other `focusable` elements. But note that this wrapper element has to be focusable too
  * (have e.g. `tabindex="-1"`).
  *
- * @mixes module:utils/dom/emittermixin/~DOMEmitterMixin
- * @mixes module:utils/observablemixin/~ObservableMixin
+ * @mixes module:utils/dom/emittermixin~EmitterMixin
+ * @mixes module:utils/observablemixin~ObservableMixin
  */
 export default class FocusTracker {
 	constructor() {
@@ -41,7 +42,7 @@ export default class FocusTracker {
 		 * List of registered elements.
 		 *
 		 * @private
-		 * @member {Set<HTMLElement>} #_elements
+		 * @member {Set.<HTMLElement>}
 		 */
 		this._elements = new Set();
 
@@ -49,7 +50,7 @@ export default class FocusTracker {
 		 * Event loop timeout.
 		 *
 		 * @private
-		 * @member {Number} #_nextEventLoopTimeout
+		 * @member {Number}
 		 */
 		this._nextEventLoopTimeout = null;
 
@@ -57,7 +58,7 @@ export default class FocusTracker {
 		 * Currently focused element.
 		 *
 		 * @private
-		 * @member {HTMLElement} #_focusedElement
+		 * @member {HTMLElement}
 		 */
 		this._focusedElement = null;
 	}
@@ -107,11 +108,11 @@ export default class FocusTracker {
 	}
 
 	/**
-	 * Clears currently focused element and set {#isFocused} as `false`.
+	 * Clears currently focused element and set {@link #isFocused} as `false`.
 	 * This method uses `setTimeout` to change order of fires `blur` and `focus` events.
 	 *
 	 * @private
-	 * @fires #_blur
+	 * @fires #blur
 	 */
 	_blur() {
 		this._nextEventLoopTimeout = setTimeout( () => {
@@ -119,6 +120,14 @@ export default class FocusTracker {
 			this.isFocused = false;
 		}, 0 );
 	}
+
+	/**
+	 * @event #focus
+	 */
+
+	/**
+	 * @event #blur
+	 */
 }
 
 mix( FocusTracker, DomEmitterMixin );

+ 0 - 5
packages/ckeditor5-utils/src/keyboard.js

@@ -22,8 +22,6 @@ import env from './env.js';
  * * `arrow(left|up|right|bottom)`,
  * * `backspace`, `delete`, `enter`, `esc`, `tab`,
  * * `ctrl`, `cmd`, `shift`, `alt`.
- *
- * @constant {Object} module:utils/keyboard~keyCodes
  */
 export const keyCodes = generateKnownKeyCodes();
 
@@ -32,7 +30,6 @@ export const keyCodes = generateKnownKeyCodes();
  *
  * Note: Key names are matched with {@link module:utils/keyboard~keyCodes} in a case-insensitive way.
  *
- * @method module:utils/keyboard.getCode
  * @param {String|module:utils/keyboard~KeystrokeInfo} Key name (see {@link module:utils/keyboard~keyCodes})
  * or a keystroke data object.
  * @returns {Number} Key or keystroke code.
@@ -77,7 +74,6 @@ export function getCode( key ) {
  *
  * Note: Only keystrokes with a single non-modifier key are supported (e.g. `ctrl+A` is OK, but `ctrl+A+B` is not).
  *
- * @method module:utils/keyboard~parseKeystroke
  * @param {String|Array.<Number|String>} keystroke Keystroke definition.
  * @returns {Number} Keystroke code.
  */
@@ -95,7 +91,6 @@ export function parseKeystroke( keystroke ) {
  * It translates any keystroke string text like `"CTRL+A"` to an
  * environment–specific keystroke, i.e. `"⌘A"` on Mac OSX.
  *
- * @method module:utils/keyboard~getEnvKeystrokeText
  * @param {String} keystroke Keystroke text.
  * @returns {String} Keystroke text specific for the environment.
  */

+ 2 - 2
packages/ckeditor5-utils/src/locale.js

@@ -21,7 +21,7 @@ export default class Locale {
 		 * The language code in [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) format.
 		 *
 		 * @readonly
-		 * @member {String} ~Locale#lang
+		 * @member {String}
 		 */
 		this.lang = lang || 'en';
 
@@ -40,7 +40,7 @@ export default class Locale {
 		 *		const t = this.t;
 		 *		t( 'Label' );
 		 *
-		 * @method module:utils/locale~Locale#t
+		 * @method #t
 		 * @param {String} str The string to translate.
 		 * @param {String[]} values Values that should be used to interpolate the string.
 		 */

+ 2 - 2
packages/ckeditor5-utils/src/log.js

@@ -38,6 +38,8 @@
  * * Whenever an incorrect situation occurs, but the app may continue working (although perhaps incorrectly),
  * log an error.
  * * Whenever it's really bad and it does not make sense to continue working, throw a {@link module:utils/ckeditorerror~CKEditorError}.
+ *
+ * @namespace
  */
 const log = {
 	/**
@@ -49,7 +51,6 @@ const log = {
 	 * During the minification process the "Error message" part will be removed to limit the code size
 	 * and a link to this error documentation will be logged to the console.
 	 * @param {Object} [data] Additional data describing the error.
-	 * @method #error
 	 */
 	error( message, data ) {
 		console.error( message, data );
@@ -64,7 +65,6 @@ const log = {
 	 * During the minification process the "Warning message" part will be removed to limit the code size
 	 * and a link to this error documentation will be logged to the console.
 	 * @param {Object} [data] Additional data describing the warning.
-	 * @method #warn
 	 */
 	warn( message, data ) {
 		console.warn( message, data );

+ 5 - 4
packages/ckeditor5-utils/src/observablemixin.js

@@ -191,7 +191,7 @@ const ObservableMixin = {
 	 *		A.unbind( 'a' );
 	 *		A.unbind();
 	 *
-	 * @method ~ObservableMixin#unbind
+	 * @method #unbind
 	 * @param {...String} [unbindAttrs] Observable attributes to be unbound. All the bindings will
 	 * be released if no attributes provided.
 	 */
@@ -248,19 +248,20 @@ const ObservableMixin = {
 			boundAttributes.clear();
 		}
 	}
+
 	/**
 	 * @private
-	 * @method ~ObservableMixin#_boundAttributes
+	 * @member ~ObservableMixin#_boundAttributes
 	 */
 
 	/**
 	 * @private
-	 * @method ~ObservableMixin#_boundObservables
+	 * @member ~ObservableMixin#_boundObservables
 	 */
 
 	/**
 	 * @private
-	 * @method ~ObservableMixin#_bindTo
+	 * @member ~ObservableMixin#_bindTo
 	 */
 };
 

+ 1 - 1
packages/ckeditor5-utils/src/priorities.js

@@ -22,8 +22,8 @@ const priorities = {
 	/**
 	 * Converts a string with priority name to it's numeric value. If `Number` is given, it just returns it.
 	 *
-	 * @param {module:utils/priorities~PriorityString|Number} priority Priority to convert.
 	 * @static
+	 * @param {module:utils/priorities~PriorityString|Number} priority Priority to convert.
 	 * @returns {Number} Converted priority.
 	 */
 	get( priority ) {

+ 1 - 1
packages/ckeditor5-utils/src/tomap.js

@@ -4,7 +4,7 @@
  */
 
 /**
- * @module utils/toMap
+ * @module utils/tomap
  */
 
 import isPlainObject from './lib/lodash/isPlainObject.js';

+ 2 - 3
packages/ckeditor5-utils/src/uid.js

@@ -11,10 +11,9 @@
  * Returns a unique id. This id is a number (starting from 1) which will never get repeated on successive calls
  * to this method.
  *
- * @method uid
  * @returns {String} A number representing the id.
  */
-export default () => {
+export default function uid() {
 	let uuid = 'e'; // Make sure that id does not start with number.
 
 	for ( let i = 0; i < 8; i++ ) {
@@ -22,4 +21,4 @@ export default () => {
 	}
 
 	return uuid;
-};
+}