浏览代码

Merge pull request #104 from ckeditor/docs-fixes

Docs fixes.
Piotrek Koszuliński 9 年之前
父节点
当前提交
cc9c5d9c7c
共有 37 个文件被更改,包括 350 次插入216 次删除
  1. 10 7
      packages/ckeditor5-utils/src/ckeditorerror.js
  2. 25 22
      packages/ckeditor5-utils/src/collection.js
  3. 9 2
      packages/ckeditor5-utils/src/comparearrays.js
  4. 7 5
      packages/ckeditor5-utils/src/config.js
  5. 4 1
      packages/ckeditor5-utils/src/count.js
  6. 4 1
      packages/ckeditor5-utils/src/diff.js
  7. 5 2
      packages/ckeditor5-utils/src/difftochanges.js
  8. 4 1
      packages/ckeditor5-utils/src/dom/createelement.js
  9. 0 8
      packages/ckeditor5-utils/src/dom/dom.jsdoc
  10. 30 25
      packages/ckeditor5-utils/src/dom/emittermixin.js
  11. 4 0
      packages/ckeditor5-utils/src/dom/getancestors.js
  12. 4 0
      packages/ckeditor5-utils/src/dom/getcommonancestor.js
  13. 4 1
      packages/ckeditor5-utils/src/dom/getdatafromelement.js
  14. 4 1
      packages/ckeditor5-utils/src/dom/indexof.js
  15. 4 1
      packages/ckeditor5-utils/src/dom/insertat.js
  16. 4 1
      packages/ckeditor5-utils/src/dom/remove.js
  17. 4 1
      packages/ckeditor5-utils/src/dom/setdatainelement.js
  18. 6 3
      packages/ckeditor5-utils/src/dom/tounit.js
  19. 5 3
      packages/ckeditor5-utils/src/elementreplacer.js
  20. 42 31
      packages/ckeditor5-utils/src/emittermixin.js
  21. 10 4
      packages/ckeditor5-utils/src/env.js
  22. 14 8
      packages/ckeditor5-utils/src/eventinfo.js
  23. 22 11
      packages/ckeditor5-utils/src/focustracker.js
  24. 4 1
      packages/ckeditor5-utils/src/isiterable.js
  25. 16 21
      packages/ckeditor5-utils/src/keyboard.js
  26. 9 7
      packages/ckeditor5-utils/src/locale.js
  27. 8 6
      packages/ckeditor5-utils/src/log.js
  28. 4 1
      packages/ckeditor5-utils/src/mapsequal.js
  29. 4 1
      packages/ckeditor5-utils/src/mix.js
  30. 4 1
      packages/ckeditor5-utils/src/nth.js
  31. 4 1
      packages/ckeditor5-utils/src/objecttomap.js
  32. 45 26
      packages/ckeditor5-utils/src/observablemixin.js
  33. 8 3
      packages/ckeditor5-utils/src/priorities.js
  34. 7 2
      packages/ckeditor5-utils/src/spy.js
  35. 4 1
      packages/ckeditor5-utils/src/tomap.js
  36. 7 5
      packages/ckeditor5-utils/src/uid.js
  37. 1 1
      packages/ckeditor5-utils/src/unicode.js

+ 10 - 7
packages/ckeditor5-utils/src/ckeditorerror.js

@@ -4,27 +4,30 @@
  */
 
 /**
+ * @module utils/ckeditorerror
+ */
+
+/**
  * The CKEditor error class.
  *
  * All errors will be shortened during the minification process in order to reduce the code size.
- * Therefore, all error messages should be documented in the same way as those in {@link utils.log}.
+ * Therefore, all error messages should be documented in the same way as those in {@link module:utils/log}.
  *
- * Read more in the {@link utils.log} module.
+ * Read more in the {@link module:utils/log} module.
  *
- * @memberOf utils
  * @extends Error
  */
 export default class CKEditorError extends Error {
 	/**
 	 * Creates an instance of the CKEditorError class.
 	 *
-	 * Read more about error logging in the {@link utils.log} module.
+	 * Read more about error logging in the {@link module:utils/log} module.
 	 *
 	 * @param {String} message The error message in an `error-name: Error message.` format.
 	 * 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 added to the `message`.
 	 * @param {Object} [data] Additional data describing the error. A stringified version of this object
-	 * will be appended to the error {@link #message}, so the data are quickly visible in the console. The original
+	 * will be appended to the error message, so the data are quickly visible in the console. The original
 	 * data object will also be later available under the {@link #data} property.
 	 */
 	constructor( message, data ) {
@@ -35,14 +38,14 @@ export default class CKEditorError extends Error {
 		super( message );
 
 		/**
-		 * @member {String} utils.CKEditorError#name
+		 * @member {String}
 		 */
 		this.name = 'CKEditorError';
 
 		/**
 		 * The additional error data passed to the constructor.
 		 *
-		 * @member {Object} utils.CKEditorError#data
+		 * @member {Object}
 		 */
 		this.data = data;
 	}

+ 25 - 22
packages/ckeditor5-utils/src/collection.js

@@ -3,6 +3,10 @@
  * For licensing, see LICENSE.md.
  */
 
+/**
+ * @module utils/collection
+ */
+
 import EmitterMixin from './emittermixin.js';
 import CKEditorError from './ckeditorerror.js';
 import uid from './uid.js';
@@ -18,7 +22,6 @@ import mix from './mix.js';
  * By default an item in the collection is identified by its `id` property. The name of the identifier can be
  * configured through the constructor of the collection.
  *
- * @memberOf utils
  * @mixes EventEmitter
  */
 export default class Collection {
@@ -34,7 +37,7 @@ export default class Collection {
 		 * The internal list of items in the collection.
 		 *
 		 * @private
-		 * @type {Object[]}
+		 * @member {Object[]}
 		 */
 		this._items = [];
 
@@ -42,7 +45,7 @@ export default class Collection {
 		 * The internal map of items in the collection.
 		 *
 		 * @private
-		 * @type {Map}
+		 * @member {Map}
 		 */
 		this._itemMap = new Map();
 
@@ -50,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';
 	}
@@ -58,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;
@@ -73,7 +76,7 @@ export default class Collection {
 	 * @param {Object} item
 	 * @param {Number} [index] The position of the item in the collection. The item
 	 * is pushed to the collection when `index` not specified.
-	 * @fires utils.Collection#add
+	 * @fires #add
 	 */
 	add( item, index ) {
 		let itemId;
@@ -154,7 +157,7 @@ export default class Collection {
 	 *
 	 * @param {Object|Number|String} subject The item to remove, its id or index in the collection.
 	 * @returns {Object} The removed item.
-	 * @fires utils.Collection#remove
+	 * @fires #remove
 	 */
 	remove( subject ) {
 		let index, id, item;
@@ -205,7 +208,7 @@ export default class Collection {
 	 * Executes the callback for each item in the collection and composes an array or values returned by this callback.
 	 *
 	 * @param {Function} callback
-	 * @param {Item} callback.item
+	 * @param {Object} callback.item
 	 * @param {Number} callback.index
 	 * @params {Object} ctx Context in which the `callback` will be called.
 	 * @returns {Array} The result of mapping.
@@ -255,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 utils.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 utils.Collection#remove
- * @param {Object} item The removed item.
- */
+mix( Collection, EmitterMixin );

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

@@ -4,6 +4,10 @@
  */
 
 /**
+ * @module utils/comparearrays
+ */
+
+/**
  * Compares how given arrays relate to each other. One array can be: same as another array, prefix of another array
  * or completely different. If arrays are different, first index at which they differ is returned. Otherwise,
  * a flag specifying the relation is returned. Flags are negative numbers, so whenever a number >= 0 is returned
@@ -15,10 +19,9 @@
  *		compareArrays( [ 0, 2 ], [ 1, 2 ] );		// 0
  *		compareArrays( [ 0, 2 ], [ 0, 1 ] );		// 1
  *
- * @memberOf utils
  * @param {Array} a Array that is compared.
  * @param {Array} b Array to compare with.
- * @returns {utils.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 );
@@ -42,3 +45,7 @@ export default function compareArrays( a, b ) {
 		return 'extension';
 	}
 }
+
+/**
+ * @typedef {'extension'|'same'|'prefix'} module:utils/comparearrays~ArrayRelation
+ */

+ 7 - 5
packages/ckeditor5-utils/src/config.js

@@ -3,16 +3,18 @@
  * For licensing, see LICENSE.md.
  */
 
+/**
+ * @module utils/config
+ */
+
 import isPlainObject from './lib/lodash/isPlainObject.js';
 
 /**
  * Handles a configuration dictionary.
- *
- * @memberOf utils
  */
 export default class Config {
 	/**
-	 * Creates an instance of the {@link Config} class.
+	 * Creates an instance of the {@link ~Config} class.
 	 *
 	 * @param {Object} [configurations] The initial configurations to be set.
 	 */
@@ -21,7 +23,7 @@ export default class Config {
 		 * Store for the whole configuration.
 		 *
 		 * @private
-		 * @member {Object} utils.config#_config
+		 * @member {Object}
 		 */
 		this._config = {};
 
@@ -194,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.

+ 4 - 1
packages/ckeditor5-utils/src/count.js

@@ -4,11 +4,14 @@
  */
 
 /**
+ * @module utils/count
+ */
+
+/**
  * Returns the number of items return by the iterator.
  *
  *		count( [ 1, 2, 3, 4, 5 ] ); // 5;
  *
- * @memberOf utils
  * @param {Iterable.<*>} iterator Any iterator.
  * @returns {Number} Number of items returned by that iterator.
  */

+ 4 - 1
packages/ckeditor5-utils/src/diff.js

@@ -3,6 +3,10 @@
  * For licensing, see LICENSE.md.
  */
 
+/**
+ * @module utils/diff
+ */
+
 // The following code is based on the "O(NP) Sequence Comparison Algorithm"
 // by Sun Wu, Udi Manber, Gene Myers, Webb Miller.
 
@@ -12,7 +16,6 @@
  *
  *		diff( 'aba', 'acca' ); // [ 'equal', 'insert', 'insert', 'delete', 'equal' ]
  *
- * @method utils.diff
  * @param {Array|String} a Input array or string.
  * @param {Array|String} b Output array or string.
  * @param {Function} [cmp] Optional function used to compare array values, by default === is used.

+ 5 - 2
packages/ckeditor5-utils/src/difftochanges.js

@@ -4,6 +4,10 @@
  */
 
 /**
+ * @module utils/difftochanges
+ */
+
+/**
  * Creates a set of changes which need to be applied to the input in order to transform
  * it into the output. This function can be used with strings or arrays.
  *
@@ -21,8 +25,7 @@
  *
  *		input.join( '' ) == output.join( '' ); // -> true
  *
- * @method utils.diffToChanges
- * @param {Array.<'equal'|'insert'|'delete'>} diff Result of {@link utils.diff}.
+ * @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
  * in order to transform it into the output.

+ 4 - 1
packages/ckeditor5-utils/src/dom/createelement.js

@@ -3,6 +3,10 @@
  * For licensing, see LICENSE.md.
  */
 
+/**
+ * @module utils/dom/createelement
+ */
+
 import isString from '../lib/lodash/isString.js';
 import isIterable from '../isiterable.js';
 
@@ -14,7 +18,6 @@ import isIterable from '../isiterable.js';
  *		createElement( document, 'p', null, 'foo' ); // <p>foo</p>
  *		createElement( document, 'p', null, [ 'foo', createElement( document, 'img' ) ] ); // <p>foo<img></p>
  *
- * @method utils.dom.createElement
  * @param {Document} doc Document used to create element.
  * @param {String} name Name of the element.
  * @param {Object} attributes Object keys will become attributes keys and object values will became attributes values.

+ 0 - 8
packages/ckeditor5-utils/src/dom/dom.jsdoc

@@ -1,8 +0,0 @@
-/**
- * @license Copyright (c) 2003-2016, CKSource - Frederico Knabben. All rights reserved.
- * For licensing, see LICENSE.md.
- */
-
-/**
- * @namespace dom
- */

+ 30 - 25
packages/ckeditor5-utils/src/dom/emittermixin.js

@@ -3,6 +3,10 @@
  * For licensing, see LICENSE.md.
  */
 
+/**
+ * @module utils/dom/emittermixin
+ */
+
 import EmitterMixin from '../emittermixin.js';
 import uid from '../uid.js';
 import extend from '../lib/lodash/extend.js';
@@ -10,9 +14,9 @@ import isNative from '../lib/lodash/isNative.js';
 
 /**
  * Mixin that injects the DOM events API into its host. It provides the API
- * compatible with {@link utils.EmitterMixin}.
+ * compatible with {@link module:utils/emittermixin~EmitterMixin}.
  *
- * DOM emitter mixin is by default available in the {@link ui.View} class,
+ * DOM emitter mixin is by default available in the {@link module:ui/view~View} class,
  * but it can also be mixed into any other class:
  *
  *		import mix from '../utils/mix.js';
@@ -26,27 +30,27 @@ import isNative from '../lib/lodash/isNative.js';
  *			console.log( evt, domEvt );
  *		} );
  *
- * @mixin utils.dom.EmitterMixin
- * @mixes utils.EmitterMixin
- * @implements ui.DomEmitter
+ * @mixin module:utils/dom/emittermixin~EmitterMixin
+ * @mixes module:utils/emittermixin~EmitterMixin
+ * @implements module:utils/dom/emittermixin~Emitter
  */
 const DomEmitterMixin = extend( {}, EmitterMixin, {
 	/**
 	 * Registers a callback function to be executed when an event is fired in a specific Emitter or DOM Node.
-	 * It is backwards compatible with {@link utils.EmitterMixin#listenTo}.
+	 * It is backwards compatible with {@link module:utils/emittermixin~EmitterMixin#listenTo}.
 	 *
-	 * @param {utils.Emitter|Node} emitter The object that fires the event.
+	 * @param {module:utils/emittermixin~Emitter|Node} 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.
 	 * @param {Object} [options={}] Additional options.
-	 * @param {utils.PriorityString|Number} [options.priority='normal'] The priority of this event callback. The higher
+	 * @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.
 	 * @param {Boolean} [options.useCapture=false] Indicates that events of this type will be dispatched to the registered
 	 * listener before being dispatched to any EventTarget beneath it in the DOM tree.
 	 *
-	 * @method utils.dom.EmitterMixin#listenTo
+	 * @method module:utils/dom/emittermixin~EmitterMixin#listenTo
 	 */
 	listenTo( ...args ) {
 		const emitter = args[ 0 ];
@@ -63,20 +67,20 @@ const DomEmitterMixin = extend( {}, EmitterMixin, {
 
 	/**
 	 * Stops listening for events. It can be used at different levels:
-	 * It is backwards compatible with {@link utils.EmitterMixin#listenTo}.
+	 * It is backwards compatible with {@link module:utils/emittermixin~EmitterMixin#listenTo}.
 	 *
 	 * * To stop listening to a specific callback.
 	 * * To stop listening to a specific event.
 	 * * To stop listening to all events fired by a specific object.
 	 * * To stop listening to all events fired by all object.
 	 *
-	 * @param {utils.Emitter|Node} [emitter] The object to stop listening to. If omitted, stops it for all objects.
+	 * @param {module:utils/emittermixin~Emitter|Node} [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 utils.dom.EmitterMixin#stopListening
+	 * @method module:utils/dom/emittermixin~EmitterMixin#stopListening
 	 */
 	stopListening( ...args ) {
 		const emitter = args[ 0 ];
@@ -101,8 +105,8 @@ const DomEmitterMixin = extend( {}, EmitterMixin, {
 	 * Retrieves ProxyEmitter instance for given DOM Node residing in this Host.
 	 *
 	 * @param {Node} node DOM Node of the ProxyEmitter.
-	 * @method utils.dom.EmitterMixin#_getProxyEmitter
-	 * @return {ProxyEmitter} ProxyEmitter instance or null.
+	 * @method module:utils/dom/emittermixin~EmitterMixin#_getProxyEmitter
+	 * @return {module:utils/dom/emittermixin~ProxyEmitter} ProxyEmitter instance or null.
 	 */
 	_getProxyEmitter( node ) {
 		let proxy, emitters, emitterInfo;
@@ -125,7 +129,7 @@ export default DomEmitterMixin;
 
 /**
  * Creates a ProxyEmitter instance. Such an instance is a bridge between a DOM Node firing events
- * and any Host listening to them. It is backwards compatible with {@link utils.EmitterMixin#on}.
+ * and any Host listening to them. It is backwards compatible with {@link module:utils/emittermixin~EmitterMixin#on}.
  *
  *                                  listenTo( click, ... )
  *                    +-----------------------------------------+
@@ -149,9 +153,9 @@ export default DomEmitterMixin;
  *                    +-----------------------------------------+
  *                                fire( click, DOM Event )
  *
- * @memberOf ui
- * @mixes utils.EmitterMixin
- * @implements utils.dom.Emitter
+ * @mixes module:utils/emittermixin~EmitterMixin
+ * @implements module:utils/dom/emittermixin~Emitter
+ * @private
  */
 class ProxyEmitter {
 	/**
@@ -172,7 +176,7 @@ extend( ProxyEmitter.prototype, EmitterMixin, {
 	 * Collection of native DOM listeners.
 	 *
 	 * @private
-	 * @member {Object} ui.ProxyEmitter#_domListeners
+	 * @member {Object} module:utils/dom/emittermixin~ProxyEmitter#_domListeners
 	 */
 
 	/**
@@ -184,14 +188,14 @@ extend( ProxyEmitter.prototype, EmitterMixin, {
 	 * @param {String} event The name of the event.
 	 * @param {Function} callback The function to be called on event.
 	 * @param {Object} [options={}] Additional options.
-	 * @param {utils.PriorityString|Number} [options.priority='normal'] The priority of this event callback. The higher
+	 * @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.
 	 * @param {Boolean} [options.useCapture=false] Indicates that events of this type will be dispatched to the registered
 	 * listener before being dispatched to any EventTarget beneath it in the DOM tree.
 	 *
-	 * @method ui.ProxyEmitter#on
+	 * @method module:utils/dom/emittermixin~ProxyEmitter#on
 	 */
 	on( event, callback, options = {} ) {
 		// Execute parent class method first.
@@ -225,7 +229,7 @@ extend( ProxyEmitter.prototype, EmitterMixin, {
 	 * @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 ui.ProxyEmitter#off
+	 * @method module:utils/dom/emittermixin~ProxyEmitter#off
 	 */
 	off( event ) {
 		// Execute parent class method first.
@@ -247,9 +251,10 @@ extend( ProxyEmitter.prototype, EmitterMixin, {
 	 * is fired it will fire corresponding event on this ProxyEmitter.
 	 * Note: A native DOM Event is passed as an argument.
 	 *
+	 * @private
 	 * @param {String} event
 	 *
-	 * @method ui.ProxyEmitter#_createDomListener
+	 * @method module:utils/dom/emittermixin~ProxyEmitter#_createDomListener
 	 * @returns {Function} The DOM listener callback.
 	 */
 	_createDomListener( event ) {
@@ -288,7 +293,7 @@ function isDomNode( node ) {
 }
 
 /**
- * Interface representing classes which mix in {@link utils.dom.Emitter}.
+ * Interface representing classes which mix in {@link module:utils/dom/emittermixin~EmitterMixin}.
  *
- * @interface utils.dom.Emitter
+ * @interface Emitter
  */

+ 4 - 0
packages/ckeditor5-utils/src/dom/getancestors.js

@@ -6,6 +6,10 @@
 /* globals Node */
 
 /**
+ * @module utils/dom/getancestors
+ */
+
+/**
  * Returns all ancestors of given DOM node, starting from the top-most (root). Includes the given node itself. If the
  * node is a part of `DocumentFragment` that `DocumentFragment` will be returned. In contrary, if the node is
  * appended to a `Document`, that `Document` will not be returned (algorithms operating on DOM tree care for `Document#documentElement`

+ 4 - 0
packages/ckeditor5-utils/src/dom/getcommonancestor.js

@@ -3,6 +3,10 @@
  * For licensing, see LICENSE.md.
  */
 
+/**
+ * @module utils/dom/getcommonancestor
+ */
+
 import getAncestors from './getancestors.js';
 
 /**

+ 4 - 1
packages/ckeditor5-utils/src/dom/getdatafromelement.js

@@ -6,9 +6,12 @@
 /* globals HTMLTextAreaElement */
 
 /**
+ * @module utils/dom/getdatafromelement
+ */
+
+/**
  * Gets data from a given source element.
  *
- * @method utils.dom.getDataFromElement
  * @param {HTMLElement} el The element from which the data will be retrieved.
  * @returns {String} The data string.
  */

+ 4 - 1
packages/ckeditor5-utils/src/dom/indexof.js

@@ -4,9 +4,12 @@
  */
 
 /**
+ * @module utils/dom/indexof
+ */
+
+/**
  * Returns index of the node in the parent element.
  *
- * @method utils.dom.indexOf
  * @param {Node} node Node which index is tested.
  * @returns {Number} Index of the node in the parent element. Returns 0 if node has no parent.
  */

+ 4 - 1
packages/ckeditor5-utils/src/dom/insertat.js

@@ -4,9 +4,12 @@
  */
 
 /**
+ * @module utils/dom/insertat
+ */
+
+/**
  * Inserts node to the parent at given index.
  *
- * @method utils.dom.insertAt
  * @param {Element} parentElement Parent element.
  * @param {Number} index Insertions index.
  * @param {Node} nodeToInsert Node to insert.

+ 4 - 1
packages/ckeditor5-utils/src/dom/remove.js

@@ -4,9 +4,12 @@
  */
 
 /**
+ * @module utils/dom/remove
+ */
+
+/**
  * Removes given node from parent.
  *
- * @method utils.dom.remove
  * @param {Node} node Node to remove.
  */
 export default function remove( node ) {

+ 4 - 1
packages/ckeditor5-utils/src/dom/setdatainelement.js

@@ -3,12 +3,15 @@
  * For licensing, see LICENSE.md.
  */
 
+/**
+ * @module utils/dom/setdatainelement
+ */
+
 /* globals HTMLTextAreaElement */
 
 /**
  * Sets data in a given element.
  *
- * @method utils.dom.setDataInElement
  * @param {HTMLElement} el The element in which the data will be set.
  * @param {String} data The data string.
  */

+ 6 - 3
packages/ckeditor5-utils/src/dom/tounit.js

@@ -4,19 +4,22 @@
  */
 
 /**
+ * @module utils/dom/tounit
+ */
+
+/**
  * Returns a helper function, which adds a desired trailing
  * `unit` to the passed value.
  *
- * @method utils.dom.toUnit
  * @param {String} unit An unit like "px" or "em".
- * @returns {utils.dom.toUnit.helper}
+ * @returns {module:utils/dom/tounit~helper}
  */
 export default function toUnit( unit ) {
 	/**
 	 * A function, which adds a pre–defined trailing `unit`
 	 * to the passed `value`.
 	 *
-	 * @function utils.dom.toUnit.helper
+	 * @function helper
  	 * @param {*} value A value to be given the unit.
  	 * @returns {String} A value with the trailing unit.
 	 */

+ 5 - 3
packages/ckeditor5-utils/src/elementreplacer.js

@@ -4,10 +4,12 @@
  */
 
 /**
+ * @module utils/elementreplacer
+ */
+
+/**
  * Utility class allowing to hide existing HTML elements or replace them with given ones in a way that doesn't remove
  * the original elements from the DOM.
- *
- * @memberOf utils
  */
 export default class ElementReplacer {
 	constructor() {
@@ -15,7 +17,7 @@ export default class ElementReplacer {
 		 * The elements replaced by {@link #replace} and their replacements.
 		 *
 		 * @private
-		 * @member {Array.<Object>} utils.ElementReplacer#_replacedElements
+		 * @member {Array.<Object>}
 		 */
 		this._replacedElements = [];
 	}

+ 42 - 31
packages/ckeditor5-utils/src/emittermixin.js

@@ -3,6 +3,10 @@
  * For licensing, see LICENSE.md.
  */
 
+/**
+ * @module utils/emittermixin
+ */
+
 import EventInfo from './eventinfo.js';
 import uid from './uid.js';
 import priorities from './priorities.js';
@@ -10,8 +14,8 @@ import priorities from './priorities.js';
 /**
  * Mixin that injects the events API into its host.
  *
- * @mixin utils.EmitterMixin
- * @implements utils.Emitter
+ * @mixin EmitterMixin
+ * @implements module:utils/emittermixin~Emitter
  */
 const EmitterMixin = {
 	/**
@@ -24,14 +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 {utils.PriorityString|Number} [options.priority='normal'] The priority of this event callback. The higher
+	 * @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 utils.EmitterMixin#on
 	 */
 	on( event, callback, options = {} ) {
 		createEventNamespace( this, event );
@@ -69,14 +73,14 @@ 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.
-	 * @param {utils.PriorityString|Number} [options.priority='normal'] The priority of this event callback. The higher
+	 * @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 utils.EmitterMixin#once
 	 */
 	once( event, callback, options ) {
 		const onceCallback = function( event ) {
@@ -94,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 utils.EmitterMixin#off
 	 */
 	off( event, callback, context ) {
 		const lists = getCallbacksListsForNamespace( this, event );
@@ -119,15 +123,15 @@ const EmitterMixin = {
 	/**
 	 * Registers a callback function to be executed when an event is fired in a specific (emitter) object.
 	 *
-	 * @param {utils.Emitter} emitter The object that fires the event.
+	 * @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.
 	 * @param {Object} [options={}] Additional options.
-	 * @param {utils.PriorityString|Number} [options.priority='normal'] The priority of this event callback. The higher
+	 * @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 utils.EmitterMixin#listenTo
 	 */
 	listenTo( emitter, event, callback, options ) {
 		let emitters, emitterId, emitterInfo, eventCallbacks;
@@ -179,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.
 	 *
-	 * @param {utils.Emitter} [emitter] The object to stop listening to. If omitted, stops it for all objects.
+	 * @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 utils.EmitterMixin#stopListening
 	 */
 	stopListening( emitter, event, callback ) {
 		let emitters = this._listeningTo;
@@ -227,12 +231,12 @@ const EmitterMixin = {
 	/**
 	 * Fires an event, executing all callbacks registered for it.
 	 *
-	 * The first parameter passed to callbacks is an {@link EventInfo} object, followed by the optional `args` provided in
-	 * the `fire()` method call.
+	 * 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.
 	 *
-	 * @param {String|utils.EventInfo} eventOrInfo The name of the event or `EventInfo` object if event is delegated.
+	 * @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 utils.EmitterMixin#fire
 	 */
 	fire( eventOrInfo, ...args ) {
 		const eventInfo = eventOrInfo instanceof EventInfo ? eventOrInfo : new EventInfo( this, eventOrInfo );
@@ -288,7 +292,7 @@ const EmitterMixin = {
 	},
 
 	/**
-	 * Delegates selected events to another {@link utils.Emitter}. For instance:
+	 * Delegates selected events to another {@link module:utils/emittermixin~Emitter}. For instance:
 	 *
 	 *		emitterA.delegate( 'eventX' ).to( emitterB );
 	 *		emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );
@@ -301,19 +305,12 @@ const EmitterMixin = {
 	 *
 	 *		emitterA.fire( 'eventY', data );
 	 *
-	 * @method utils.EmitterMixin#delegate
+	 * @method #delegate
 	 * @param {...String} events Event names that will be delegated to another emitter.
-	 * @returns {utils.EmitterMixin.delegate#to}
+	 * @returns {module:utils/emittermixin~EmitterMixinDelegateChain}
 	 */
 	delegate( ...events ) {
 		return {
-			/**
-			 * Selects destination for {@link utils.EmitterMixin#delegate} events.
-			 *
-			 * @method utils.EmitterMixin.delegate#to
-			 * @param {utils.Emitter} emitter An `EmitterMixin` instance which is the destination for delegated events.
-			 * @param {String|Function} nameOrFunction A custom event name or function which converts the original name string.
-			 */
 			to: ( emitter, nameOrFunction ) => {
 				if ( !this._delegations ) {
 					this._delegations = new Map();
@@ -339,10 +336,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 {utils.Emitter} [emitter] (requires `event`) The object to stop delegating a particular event to. If omitted,
-	 * stops delegation of `event` to all emitters.
-	 * @method utils.EmitterMixin#stopDelegating
+	 * @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.
 	 */
 	stopDelegating( event, emitter ) {
 		if ( !this._delegations ) {
@@ -519,7 +516,21 @@ function fireDelegatedEvents( destinations, eventInfo, fireArgs ) {
 }
 
 /**
- * Interface representing classes which mix in {@link utils.EmitterMixin}.
+ * Interface representing classes which mix in {@link module:utils/emittermixin~EmitterMixin}.
+ *
+ * @interface Emitter
+ */
+
+/**
+ * The return value of {@link ~EmitterMixin#delegate}.
+ *
+ * @interface module:utils/emittermixin~EmitterMixinDelegateChain
+ */
+
+/**
+ * Selects destination for {@link module:utils/emittermixin~EmitterMixin#delegate} events.
  *
- * @interface utils.Emitter
+ * @method #to
+ * @param {module:utils/emittermixin~Emitter} emitter An `EmitterMixin` instance which is the destination for delegated events.
+ * @param {String|Function} nameOrFunction A custom event name or function which converts the original name string.
  */

+ 10 - 4
packages/ckeditor5-utils/src/env.js

@@ -5,26 +5,32 @@
 
 /* globals navigator:false */
 
+/**
+ * @module utils/env
+ */
+
 const userAgent = navigator.userAgent.toLowerCase();
 
 /**
  * A namespace containing environment and browser information.
  *
- * @namespace utils.env
+ * @namespace
  */
-export default {
+const env = {
 	/**
 	 * Indicates that application is running on Macintosh.
 	 *
-	 * @member {Boolean} utils.env.mac
+	 * @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 utils.env.isMac
  * @param {String} userAgent **Lowercase** `navigator.userAgent` string.
  * @returns {Boolean} Whether User Agent is running on Macintosh or not.
  */

+ 14 - 8
packages/ckeditor5-utils/src/eventinfo.js

@@ -3,21 +3,27 @@
  * For licensing, see LICENSE.md.
  */
 
+/**
+ * @module utils/eventinfo
+ */
+
 import spy from './spy.js';
 
 /**
  * The event object passed to event callbacks. It is used to provide information about the event as well as a tool to
  * manipulate it.
- *
- * @memberOf utils
  */
 export default class EventInfo {
+	/**
+	 * @param {Object} source The emitter.
+	 * @param {String} name The event name.
+	 */
 	constructor( source, name ) {
 		/**
 		 * The object that fired the event.
 		 *
 		 * @readonly
-		 * @member utils.EventInfo#source
+		 * @member {Object}
 		 */
 		this.source = source;
 
@@ -25,15 +31,15 @@ export default class EventInfo {
 		 * The event name.
 		 *
 		 * @readonly
-		 * @member utils.EventInfo#name
+		 * @member {String}
 		 */
 		this.name = name;
 
 		/**
-		 * Path this event has followed. See {@link utils.EmitterMixin#delegate}.
+		 * Path this event has followed. See {@link module:utils/emittermixin~EmitterMixin#delegate}.
 		 *
 		 * @readonly
-		 * @member utils.EventInfo#path
+		 * @member {Array.<Object>}
 		 */
 		this.path = [];
 
@@ -42,14 +48,14 @@ export default class EventInfo {
 		/**
 		 * Stops the event emitter to call further callbacks for this event interaction.
 		 *
-		 * @method utils.EventInfo#stop
+		 * @method #stop
 		 */
 		this.stop = spy();
 
 		/**
 		 * Removes the current callback from future interactions of this event.
 		 *
-		 * @method utils.EventInfo#off
+		 * @method #off
 		 */
 		this.off = spy();
 	}

+ 22 - 11
packages/ckeditor5-utils/src/focustracker.js

@@ -5,6 +5,10 @@
 
 /* global setTimeout, clearTimeout */
 
+/**
+ * @module utils/focustracker
+ */
+
 import DomEmitterMixin from './dom/emittermixin.js';
 import ObservableMixin from './observablemixin.js';
 import CKEditorError from './ckeditorerror.js';
@@ -13,16 +17,15 @@ import mix from './mix.js';
 /**
  * Allows observing a group of `HTMLElement`s whether at least one of them is focused.
  *
- * Used by the {@link core.Editor} in order to track whether the focus is still within the application,
+ * Used by the {@link module:core/editor~Editor} in order to track whether the focus is still within the application,
  * or were used outside of its UI.
  *
  * **Note** `focus` and `blur` listeners use event capturing, so it is only needed to register wrapper `HTMLElement`
  * which contain other `focusable` elements. But note that this wrapper element has to be focusable too
  * (have e.g. `tabindex="-1"`).
  *
- * @memberOf utils
- * @mixes utils.dom.EmitterMixin
- * @mixes utils.ObservableMixin
+ * @mixes module:utils/dom/emittermixin~EmitterMixin
+ * @mixes module:utils/observablemixin~ObservableMixin
  */
 export default class FocusTracker {
 	constructor() {
@@ -31,7 +34,7 @@ export default class FocusTracker {
 		 *
 		 * @readonly
 		 * @observable
-		 * @member {Boolean} utils.FocusTracker#isFocused
+		 * @member {Boolean} #isFocused
 		 */
 		this.set( 'isFocused', false );
 
@@ -39,7 +42,7 @@ export default class FocusTracker {
 		 * List of registered elements.
 		 *
 		 * @private
-		 * @member {Set<HTMLElement>} utils.FocusTracker#_elements
+		 * @member {Set.<HTMLElement>}
 		 */
 		this._elements = new Set();
 
@@ -47,7 +50,7 @@ export default class FocusTracker {
 		 * Event loop timeout.
 		 *
 		 * @private
-		 * @member {Number} utils.FocusTracker#_nextEventLoopTimeout
+		 * @member {Number}
 		 */
 		this._nextEventLoopTimeout = null;
 
@@ -55,7 +58,7 @@ export default class FocusTracker {
 		 * Currently focused element.
 		 *
 		 * @private
-		 * @member {HTMLElement} utils.FocusTracker#_focusedElement
+		 * @member {HTMLElement}
 		 */
 		this._focusedElement = null;
 	}
@@ -92,7 +95,7 @@ export default class FocusTracker {
 	}
 
 	/**
-	 * Stores currently focused element and set {utils.FocusTracker#isFocused} as `true`.
+	 * Stores currently focused element and set {#isFocused} as `true`.
 	 *
 	 * @private
 	 * @param {HTMLElement} element Element which has been focused.
@@ -105,11 +108,11 @@ export default class FocusTracker {
 	}
 
 	/**
-	 * Clears currently focused element and set {utils.FocusTracker#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 utils.FocusTracker#blur
+	 * @fires #blur
 	 */
 	_blur() {
 		this._nextEventLoopTimeout = setTimeout( () => {
@@ -117,6 +120,14 @@ export default class FocusTracker {
 			this.isFocused = false;
 		}, 0 );
 	}
+
+	/**
+	 * @event #focus
+	 */
+
+	/**
+	 * @event #blur
+	 */
 }
 
 mix( FocusTracker, DomEmitterMixin );

+ 4 - 1
packages/ckeditor5-utils/src/isiterable.js

@@ -4,9 +4,12 @@
  */
 
 /**
+ * @module utils/isiterable
+ */
+
+/**
  * Checks if value implements iterator interface.
  *
- * @memberOf utils
  * @param {*} value The value to check.
  * @returns {Boolean} True if value implements iterator interface.
  */

+ 16 - 21
packages/ckeditor5-utils/src/keyboard.js

@@ -3,15 +3,15 @@
  * For licensing, see LICENSE.md.
  */
 
-import CKEditorError from './ckeditorerror.js';
-import env from './env.js';
-
 /**
  * Set of utils related to keyboard support.
  *
- * @namespace utils.keyboard
+ * @module utils/keyboard
  */
 
+import CKEditorError from './ckeditorerror.js';
+import env from './env.js';
+
 /**
  * Object with `keyName => keyCode` pairs for a set of known keys.
  *
@@ -22,18 +22,15 @@ import env from './env.js';
  * * `arrow(left|up|right|bottom)`,
  * * `backspace`, `delete`, `enter`, `esc`, `tab`,
  * * `ctrl`, `cmd`, `shift`, `alt`.
- *
- * @member {Object} utils.keyboard.keyCodes
  */
 export const keyCodes = generateKnownKeyCodes();
 
 /**
- * Converts a key name or a {@link utils.keyboard.KeystrokeInfo keystroke info} into a key code.
+ * Converts a key name or a {@link module:utils/keyboard~KeystrokeInfo keystroke info} into a key code.
  *
- * Note: Key names are matched with {@link utils.keyboard.keyCodes} in a case-insensitive way.
+ * Note: Key names are matched with {@link module:utils/keyboard~keyCodes} in a case-insensitive way.
  *
- * @method utils.keyboard.getCode
- * @param {String|utils.keyboard.KeystrokeInfo} Key name (see {@link utils.keyboard.keyCodes})
+ * @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.
  */
@@ -45,7 +42,7 @@ export function getCode( key ) {
 
 		if ( !keyCode ) {
 			/**
-			 * Unknown key name. Only key names contained by the {@link utils.keyboard.keyCodes} can be used.
+			 * Unknown key name. Only key names contained by the {@link module:utils/keyboard~keyCodes} can be used.
 			 *
 			 * @errror keyboard-unknown-key
 			 * @param {String} key
@@ -64,20 +61,19 @@ export function getCode( key ) {
 
 /**
  * Parses keystroke and returns a keystroke code that will match the code returned by
- * link {@link utils.keyboard.getCode} for a corresponding {@link utils.keyboard.KeystrokeInfo keystroke info}.
+ * link {@link module:utils/keyboard.getCode} for a corresponding {@link module:utils/keyboard~KeystrokeInfo keystroke info}.
  *
  * The keystroke can be passed in two formats:
  *
  * * as a single string – e.g. `ctrl + A`,
- * * as an array of {@link utils.keyboard.keyCodes known key names} and key codes – e.g.:
+ * * as an array of {@link module:utils/keyboard~keyCodes known key names} and key codes – e.g.:
  *   * `[ 'ctrl', 32 ]` (ctrl + space),
  *   * `[ 'ctrl', 'a' ]` (ctrl + A).
  *
- * Note: Key names are matched with {@link utils.keyboard.keyCodes} in a case-insensitive way.
+ * Note: Key names are matched with {@link module:utils/keyboard~keyCodes} in a case-insensitive way.
  *
  * Note: Only keystrokes with a single non-modifier key are supported (e.g. `ctrl+A` is OK, but `ctrl+A+B` is not).
  *
- * @method 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 utils.keyboard.getEnvKeystrokeText
  * @param {String} keystroke Keystroke text.
  * @returns {String} Keystroke text specific for the environment.
  */
@@ -155,29 +150,29 @@ function splitKeystrokeText( keystroke ) {
 /**
  * Information about a keystroke.
  *
- * @interface utils.keyboard.KeystrokeInfo
+ * @interface module:utils/keyboard~KeystrokeInfo
  */
 
 /**
  * The [key code](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode).
  *
- * @member {Number} utils.keyboard.KeystrokeInfo#keyCode
+ * @member {Number} module:utils/keyboard~KeystrokeInfo#keyCode
  */
 
 /**
  * Whether the <kbd>Alt</kbd> modifier was pressed.
  *
- * @member {Bolean} utils.keyboard.KeystrokeInfo#altKey
+ * @member {Bolean} module:utils/keyboard~KeystrokeInfo#altKey
  */
 
 /**
  * Whether the <kbd>Ctrl</kbd> or <kbd>Cmd</kbd> modifier was pressed.
  *
- * @member {Bolean} utils.keyboard.KeystrokeInfo#ctrlKey
+ * @member {Bolean} module:utils/keyboard~KeystrokeInfo#ctrlKey
  */
 
 /**
  * Whether the <kbd>Shift</kbd> modifier was pressed.
  *
- * @member {Bolean} utils.keyboard.KeystrokeInfo#shiftKey
+ * @member {Bolean} module:utils/keyboard~KeystrokeInfo#shiftKey
  */

+ 9 - 7
packages/ckeditor5-utils/src/locale.js

@@ -4,13 +4,15 @@
  */
 
 /**
+ * @module utils/locale
+ */
+
+/**
  * Represents the localization services.
- *
- * @memberOf utils
  */
 export default class Locale {
 	/**
-	 * Creates a new instance of the Locale class. {@link Foo#bar}
+	 * Creates a new instance of the Locale class. {@link ~Locale}
 	 *
 	 * @param {String} [lang='en'] The language code in [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) format.
 	 */
@@ -19,13 +21,13 @@ export default class Locale {
 		 * The language code in [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) format.
 		 *
 		 * @readonly
-		 * @member {String} utils.Locale#lang
+		 * @member {String}
 		 */
 		this.lang = lang || 'en';
 
 		/**
-		 * Translates the given string to the {@link #lang}. This method is also availble in {@link Editor#t} and
-		 * {@link ui.View#t}.
+		 * Translates the given string to the {@link #lang}. This method is also availble in {@link module:core/editor~Editor#t} and
+		 * {@link module:ui/view~View#t}.
 		 *
 		 * The strings may contain placeholders (`%<index>`) for values which are passed as the second argument.
 		 * `<index>` is the index in the `values` array.
@@ -38,7 +40,7 @@ export default class Locale {
 		 *		const t = this.t;
 		 *		t( 'Label' );
 		 *
-		 * @method utils.Locale#t
+		 * @method #t
 		 * @param {String} str The string to translate.
 		 * @param {String[]} values Values that should be used to interpolate the string.
 		 */

+ 8 - 6
packages/ckeditor5-utils/src/log.js

@@ -6,6 +6,10 @@
 /* global console */
 
 /**
+ * @module utils/log
+ */
+
+/**
  * The logging module.
  *
  * This object features two functions that should be used across CKEditor code base to log errors and warnings.
@@ -33,21 +37,20 @@
  * log a warning.
  * * 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 utils.CKEditorError}.
+ * * Whenever it's really bad and it does not make sense to continue working, throw a {@link module:utils/ckeditorerror~CKEditorError}.
  *
- * @namespace utils.log
+ * @namespace
  */
 const log = {
 	/**
 	 * Logs an error to the console.
 	 *
-	 * Read more about error logging in the {@link utils.log} module.
+	 * Read more about error logging in the {@link module:utils/log} module.
 	 *
 	 * @param {String} message The error message in an `error-name: Error message.` format.
 	 * 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 utils.log.error
 	 */
 	error( message, data ) {
 		console.error( message, data );
@@ -56,13 +59,12 @@ const log = {
 	/**
 	 * Logs a warning to the console.
 	 *
-	 * Read more about error logging in the {@link utils.log} module.
+	 * Read more about error logging in the {@link module:utils/log} module.
 	 *
 	 * @param {String} message The warning message in a `warning-name: Warning message.` format.
 	 * 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 utils.log.warn
 	 */
 	warn( message, data ) {
 		console.warn( message, data );

+ 4 - 1
packages/ckeditor5-utils/src/mapsequal.js

@@ -4,9 +4,12 @@
  */
 
 /**
+ * @module utils/mapsequal
+ */
+
+/**
  * Checks whether given {Map}s are equal, that is has same size and same key-value pairs.
  *
- * @memberOf utils
  * @returns {Boolean} `true` if given maps are equal, `false` otherwise.
  */
 export default function mapsEqual( mapA, mapB ) {

+ 4 - 1
packages/ckeditor5-utils/src/mix.js

@@ -4,6 +4,10 @@
  */
 
 /**
+ * @module utils/mix
+ */
+
+/**
  * Copies enumerable properties and symbols from the objects given as 2nd+ parameters to the
  * prototype of first object (a constructor).
  *
@@ -23,7 +27,6 @@
  *
  * Note: Properties which already exist in the base class will not be overriden.
  *
- * @memberOf utils
  * @param {Function} [baseClass] Class which prototype will be extended.
  * @param {Object} [...mixins] Objects from which to get properties.
  */

+ 4 - 1
packages/ckeditor5-utils/src/nth.js

@@ -4,9 +4,12 @@
  */
 
 /**
+ * @module utils/nth
+ */
+
+/**
  * Returns `nth` (starts from `0` of course) item of an `iterable`.
  *
- * @memberOf utils
  * @param {Number} index
  * @param {Iterable.<*>} iterable
  * @returns {*}

+ 4 - 1
packages/ckeditor5-utils/src/objecttomap.js

@@ -4,12 +4,15 @@
  */
 
 /**
+ * @module utils/objecttomap
+ */
+
+/**
  * Transforms object to map.
  *
  *		const map = objectToMap( { 'foo': 1, 'bar': 2 } );
  *		map.get( 'foo' ); // 1
  *
- * @memberOf utils
  * @param {Object} obj Object to transform.
  * @returns {Map} Map created from object.
  */

+ 45 - 26
packages/ckeditor5-utils/src/observablemixin.js

@@ -3,6 +3,10 @@
  * For licensing, see LICENSE.md.
  */
 
+/**
+ * @module utils/observablemixin
+ */
+
 import EmitterMixin from './emittermixin.js';
 import CKEditorError from './ckeditorerror.js';
 import extend from './lib/lodash/extend.js';
@@ -14,11 +18,11 @@ const boundAttributesSymbol = Symbol( 'boundAttributes' );
 
 /**
  * Mixin that injects the "observable attributes" and data binding functionality.
- * Used mainly in the {@link ui.Model} class.
+ * Used mainly in the {@link module:ui/model~Model} class.
  *
- * @mixin utils.ObservableMixin
- * @mixes utils.EmitterMixin
- * @implements utils.Observable
+ * @mixin ObservableMixin
+ * @mixes module:utils/emittermixin~EmitterMixin
+ * @implements module:utils/observablemixin~Observable
  */
 const ObservableMixin = {
 	/**
@@ -27,11 +31,11 @@ const ObservableMixin = {
 	 *
 	 * It accepts also a single object literal containing key/value pairs with attributes to be set.
 	 *
-	 * This method throws the {@link observable-set-cannot-override} error if the observable instance already
+	 * This method throws the observable-set-cannot-override error if the observable instance already
 	 * have a property with a given attribute name. This prevents from mistakenly overriding existing
 	 * properties and methods, but means that `foo.set( 'bar', 1 )` may be slightly slower than `foo.bar = 1`.
 	 *
-	 * @method utils.ObservableMixin#set
+	 * @method #set
 	 * @param {String} name The attributes name.
 	 * @param {*} value The attributes value.
 	 */
@@ -53,7 +57,7 @@ const ObservableMixin = {
 			/**
 			 * Cannot override an existing property.
 			 *
-			 * This error is thrown when trying to {@link utils.Observable#set set} an attribute with
+			 * This error is thrown when trying to {@link ~Observable#set set} an attribute with
 			 * a name of an already existing property. For example:
 			 *
 			 *		let observable = new Model();
@@ -92,23 +96,23 @@ const ObservableMixin = {
 	},
 
 	/**
-	 * Binds observable attributes to another objects implementing {@link ObservableMixin}
-	 * interface (like {@link ui.Model}).
+	 * Binds observable attributes to another objects implementing {@link ~ObservableMixin}
+	 * interface (like {@link module:ui/model~Model}).
 	 *
 	 * Once bound, the observable will immediately share the current state of attributes
 	 * of the observable it is bound to and react to the changes to these attributes
 	 * in the future.
 	 *
-	 * **Note**: To release the binding use {@link utils.ObservableMixin#unbind}.
+	 * **Note**: To release the binding use {@link module:utils/observablemixin~ObservableMixin#unbind}.
 	 *
 	 *		A.bind( 'a' ).to( B );
 	 *		A.bind( 'a' ).to( B, 'b' );
 	 *		A.bind( 'a', 'b' ).to( B, 'c', 'd' );
 	 *		A.bind( 'a' ).to( B, 'b', C, 'd', ( b, d ) => b + d );
 	 *
-	 * @method utils.ObservableMixin#bind
+	 * @method #bind
 	 * @param {...String} bindAttrs Observable attributes that will be bound to another observable(s).
-	 * @returns {utils.BindChain}
+	 * @returns {module:utils/observablemixin~BindChain}
 	 */
 	bind( ...bindAttrs ) {
 		if ( !bindAttrs.length || !isStringArray( bindAttrs ) ) {
@@ -147,7 +151,7 @@ const ObservableMixin = {
 		const bindings = new Map();
 
 		/**
-		 * @typedef utils.Binding
+		 * @typedef Binding
 		 * @type Object
 		 * @property {Array} attr Attribute which is bound.
 		 * @property {Array} to Array of observable–attribute components of the binding (`{ observable: ..., attr: .. }`).
@@ -161,14 +165,14 @@ const ObservableMixin = {
 		} );
 
 		/**
-		 * @typedef utils.BindChain
+		 * @typedef BindChain
 		 * @type Object
-		 * @property {Function} to See {@link utils.ObservableMixin#_bindTo}.
+		 * @property {Function} to See {@link ~ObservableMixin#_bindTo}.
 		 * @property {Observable} _observable The observable which initializes the binding.
 		 * @property {Array} _bindAttrs Array of `_observable` attributes to be bound.
 		 * @property {Array} _to Array of `to()` observable–attributes (`{ observable: toObservable, attrs: ...toAttrs }`).
 		 * @property {Map} _bindings Stores bindings to be kept in
-		 *  {@link utils.ObservableMixin#_boundAttributes}/{@link utils.ObservableMixin#_boundObservables}
+		 *  {@link ~ObservableMixin#_boundAttributes}/{@link ~ObservableMixin#_boundObservables}
 		 * initiated in this binding chain.
 		 */
 		return {
@@ -182,12 +186,12 @@ const ObservableMixin = {
 	},
 
 	/**
-	 * Removes the binding created with {@link utils.ObservableMixin#bind}.
+	 * Removes the binding created with {@link ~ObservableMixin#bind}.
 	 *
 	 *		A.unbind( 'a' );
 	 *		A.unbind();
 	 *
-	 * @method utils.ObservableMixin#unbind
+	 * @method #unbind
 	 * @param {...String} [unbindAttrs] Observable attributes to be unbound. All the bindings will
 	 * be released if no attributes provided.
 	 */
@@ -244,6 +248,21 @@ const ObservableMixin = {
 			boundAttributes.clear();
 		}
 	}
+
+	/**
+	 * @private
+	 * @member ~ObservableMixin#_boundAttributes
+	 */
+
+	/**
+	 * @private
+	 * @member ~ObservableMixin#_boundObservables
+	 */
+
+	/**
+	 * @private
+	 * @member ~ObservableMixin#_bindTo
+	 */
 };
 
 export default ObservableMixin;
@@ -251,7 +270,7 @@ export default ObservableMixin;
 // Init symbol properties needed to for the observable mechanism to work.
 //
 // @private
-// @param {ObservableMixin} observable
+// @param {module:utils/observablemixin~ObservableMixin} observable
 function initObservable( observable ) {
 	// Do nothing if already inited.
 	if ( attributesSymbol in observable ) {
@@ -267,9 +286,9 @@ function initObservable( observable ) {
 	} );
 
 	// Map containing bindings to external observables. It shares the binding objects
-	// (`{ observable: A, attr: 'a', to: ... }`) with {@link utils.ObservableMixin#_boundAttributes} and
+	// (`{ observable: A, attr: 'a', to: ... }`) with {@link module:utils/observablemixin~ObservableMixin#_boundAttributes} and
 	// it is used to observe external observables to update own attributes accordingly.
-	// See {@link utils.ObservableMixin#bind}.
+	// See {@link module:utils/observablemixin~ObservableMixin#bind}.
 	//
 	//		A.bind( 'a', 'b', 'c' ).to( B, 'x', 'y', 'x' );
 	//		console.log( A._boundObservables );
@@ -348,7 +367,7 @@ function initObservable( observable ) {
 	} );
 }
 
-// A chaining for {@link utils.ObservableMixin#bind} providing `.to()` interface.
+// A chaining for {@link module:utils/observablemixin~ObservableMixin#bind} providing `.to()` interface.
 //
 // @private
 // @param {...[Observable|String|Function]} args Arguments of the `.to( args )` binding.
@@ -473,7 +492,7 @@ function parseBindToArgs( ...args ) {
 	return parsed;
 }
 
-// Synchronizes {@link Observable#_boundObservables} with {@link Binding}.
+// Synchronizes {@link module:utils/observablemixin#_boundObservables} with {@link Binding}.
 //
 // @private
 // @param {Binding} binding A binding to store in {@link Observable#_boundObservables}.
@@ -614,14 +633,14 @@ extend( ObservableMixin, EmitterMixin );
 /**
  * Fired when an attribute changed value.
  *
- * @event utils.ObservableMixin#change:{attribute}
+ * @event module:utils/observablemixin~ObservableMixin#change:{attribute}
  * @param {String} name The attribute name.
  * @param {*} value The new attribute value.
  * @param {*} oldValue The previous attribute value.
  */
 
 /**
- * Interface representing classes which mix in {@link utils.ObservableMixin}.
+ * Interface representing classes which mix in {@link module:utils/observablemixin~ObservableMixin}.
  *
- * @interface utils.Observable
+ * @interface Observable
  */

+ 8 - 3
packages/ckeditor5-utils/src/priorities.js

@@ -4,21 +4,26 @@
  */
 
 /**
+ * @module utils/priorities
+ */
+
+/**
  * String representing a priority value.
  *
- * @typedef {'highest'|'high'|'normal'|'low'|'lowest'} utils.PriorityString
+ * @typedef {'highest'|'high'|'normal'|'low'|'lowest'} module:utils/priorities~PriorityString
  */
 
 /**
  * Provides group of constants to use instead of hardcoding numeric priority values.
  *
- * @memberOf utils
+ * @namespace
  */
 const priorities = {
 	/**
 	 * Converts a string with priority name to it's numeric value. If `Number` is given, it just returns it.
 	 *
-	 * @param {utils.PriorityString|Number} priority Priority to convert.
+	 * @static
+	 * @param {module:utils/priorities~PriorityString|Number} priority Priority to convert.
 	 * @returns {Number} Converted priority.
 	 */
 	get( priority ) {

+ 7 - 2
packages/ckeditor5-utils/src/spy.js

@@ -4,17 +4,22 @@
  */
 
 /**
+ * @module utils/spy
+ */
+
+/**
  * Creates a spy function (ala Sinon.js) that can be used to inspect call to it.
  *
  * The following are the present features:
  *
  * * spy.called: property set to `true` if the function has been called at least once.
  *
- * @memberOf utils
  * @returns {Function} The spy function.
  */
-export default function spy() {
+function spy() {
 	return function spy() {
 		spy.called = true;
 	};
 }
+
+export default spy;

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

@@ -3,6 +3,10 @@
  * For licensing, see LICENSE.md.
  */
 
+/**
+ * @module utils/tomap
+ */
+
 import isPlainObject from './lib/lodash/isPlainObject.js';
 import objectToMap from './objecttomap.js';
 
@@ -13,7 +17,6 @@ import objectToMap from './objecttomap.js';
  *		map = toMap( [ [ 'foo', 1 ], [ 'bar', 2 ] ] );
  *		map = toMap( anotherMap );
  *
- * @memberOf utils
  * @param {Object|Iterable} data Object or iterable to transform.
  * @returns {Map} Map created from data.
  */

+ 7 - 5
packages/ckeditor5-utils/src/uid.js

@@ -4,14 +4,16 @@
  */
 
 /**
+ * @module utils/uid
+ */
+
+/**
  * Returns a unique id. This id is a number (starting from 1) which will never get repeated on successive calls
  * to this method.
  *
- * @function
- * @memberOf utils
- * @returns {String} A string representing the id.
+ * @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++ ) {
@@ -19,4 +21,4 @@ export default () => {
 	}
 
 	return uuid;
-};
+}

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

@@ -6,7 +6,7 @@
 /**
  * Set of utils to handle unicode characters.
  *
- * @namespace utils.unicode
+ * @module utils/unicode
  */
 
 /**