Parcourir la source

Merge branch 'master' into t/190

Piotrek Koszuliński il y a 9 ans
Parent
commit
9375dddb84

+ 5 - 8
packages/ckeditor5-utils/CHANGES.md

@@ -1,9 +1,9 @@
-{App Name} Changelog
-====================
+CKEditor 5 Core Framework Changelog
+========================================
 
-## App 1.2.3
+## CKEditor 5 Core Framework 0.0.2
 
-**Major|Minor|Patch Release** - Build Date: yyyy-mm-dd
+**Major|Minor|Patch Release**  Build Date: yyyy-mm-dd
 
 New Features:
 
@@ -15,14 +15,11 @@ Fixed Issues:
 * [#Issue Number](http://issue/url): Item 1.
 * Item 2
 
-
 Other Changes:
 
 * Item 1
 * Item 2
 
----
-
-## App 1.2.2
+## CKEditor 5 Core Framework 0.0.1
 
 ...

+ 2 - 3
packages/ckeditor5-utils/CONTRIBUTING.md

@@ -1,5 +1,4 @@
 Contributing
-============
+========================================
 
-Information about contributing can be found at the following page:
-https://github.com/ckeditor/ckeditor5/blob/master/CONTRIBUTING.md
+Information about contributing can be found at the following page: <https://github.com/ckeditor/ckeditor5/blob/master/CONTRIBUTING.md>.

+ 10 - 18
packages/ckeditor5-utils/LICENSE.md

@@ -1,37 +1,29 @@
 Software License Agreement
 ==========================
 
-**CKEditor 5 Core Framework** - https://github.com/ckeditor/ckeditor5-core <br>
+**CKEditor 5 Core Framework**  https://github.com/ckeditor/ckeditor5-core <br>
 Copyright (c) 2003-2016, [CKSource](http://cksource.com) Frederico Knabben. All rights reserved.
 
 Licensed under the terms of any of the following licenses at your choice:
 
- * [GNU General Public License Version 2 or later (the "GPL")](http://www.gnu.org/licenses/gpl.html)
+* [GNU General Public License Version 2 or later (the "GPL")](http://www.gnu.org/licenses/gpl.html)
+* [GNU Lesser General Public License Version 2.1 or later (the "LGPL")](http://www.gnu.org/licenses/lgpl.html)
+* [Mozilla Public License Version 1.1 or later (the "MPL")](http://www.mozilla.org/MPL/MPL-1.1.html)
 
- * [GNU Lesser General Public License Version 2.1 or later (the "LGPL")](http://www.gnu.org/licenses/lgpl.html)
-
- * [Mozilla Public License Version 1.1 or later (the "MPL")](http://www.mozilla.org/MPL/MPL-1.1.html)
-
-You are not required to, but if you want to explicitly declare the license you have chosen to be bound to when using,
-reproducing, modifying and distributing this software, just include a text file titled "legal.txt" in your version of
-this software, indicating your license choice. In any case, your choice will not restrict any recipient of your version
-of this software to use, reproduce, modify and distribute this software under any of the above licenses.
+You are not required to, but if you want to explicitly declare the license you have chosen to be bound to when using, reproducing, modifying and distributing this software, just include a text file titled "legal.txt" in your version of this software, indicating your license choice. In any case, your choice will not restrict any recipient of your version of this software to use, reproduce, modify and distribute this software under any of the above licenses.
 
 Sources of Intellectual Property Included in CKEditor
 -----------------------------------------------------
 
-Where not otherwise indicated, all CKEditor content is authored by CKSource engineers and consists of CKSource-owned
-intellectual property. In some specific instances, CKEditor will incorporate work done by developers outside of CKSource
-with their express permission.
+Where not otherwise indicated, all CKEditor content is authored by CKSource engineers and consists of CKSource-owned intellectual property. In some specific instances, CKEditor will incorporate work done by developers outside of CKSource with their express permission.
 
 Third parties' software included:
 
- * Lo-Dash (src/lib/lodash) <br>
-   Copyright 2012-2015 [The Dojo Foundation](http://dojofoundation.org/) <br>
-   Available under [MIT license](http://lodash.com/license)
+* Lo-Dash (src/lib/lodash) <br>
+  Copyright 2012-2015 [The Dojo Foundation](http://dojofoundation.org/) <br>
+  Available under [MIT license](http://lodash.com/license)
 
 Trademarks
 ----------
 
-**CKEditor** is a trademark of [CKSource](http://cksource.com) Frederico Knabben. All other brand and product names are
-trademarks, registered trademarks or service marks of their respective holders.
+**CKEditor** is a trademark of [CKSource](http://cksource.com) Frederico Knabben. All other brand and product names are trademarks, registered trademarks or service marks of their respective holders.

+ 2 - 3
packages/ckeditor5-utils/README.md

@@ -1,10 +1,9 @@
 CKEditor 5 Core Framework
-================================
+========================================
 
 [![devDependency Status](https://david-dm.org/ckeditor/ckeditor5-core/dev-status.svg)](https://david-dm.org/ckeditor/ckeditor5-core#info=devDependencies)
 
-The core framework of CKEditor 5 project. More information about the project can be found at the following url: <br>
-https://github.com/ckeditor/ckeditor5
+The core framework of CKEditor 5 project. More information about the project can be found at the following url: <https://github.com/ckeditor/ckeditor5>.
 
 ## License
 

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

@@ -13,17 +13,15 @@
  *
  * Read more in the {@link core.log} module.
  *
- * @class CKEditorError
+ * @memberOf core
  * @extends Error
  */
-
 export default class CKEditorError extends Error {
 	/**
 	 * Creates an instance of the CKEditorError class.
 	 *
 	 * Read more about error logging in the {@link core.log} module.
 	 *
-	 * @constructor
 	 * @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`.
@@ -38,12 +36,15 @@ export default class CKEditorError extends Error {
 
 		super( message );
 
+		/**
+		 * @member {String} core.CKEditorError#name
+		 */
 		this.name = 'CKEditorError';
 
 		/**
 		 * The additional error data passed to the constructor.
 		 *
-		 * @property {Object} data
+		 * @member {Object} core.CKEditorError#data
 		 */
 		this.data = data;
 	}

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

@@ -19,16 +19,14 @@ import utils from './utils.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.
  *
- * @class Collection
- * @mixins EventEmitter
+ * @memberOf core
+ * @mixes EventEmitter
  */
-
 export default class Collection {
 	/**
 	 * Creates a new Collection instance.
 	 *
-	 * @constructor
-	 * @param {Iterale} [items] Items to be added to the collection.
+	 * @param {Iterable} [items] Items to be added to the collection.
 	 * @param {Object} options The options object.
 	 * @param {String} [options.idProperty='id'] The name of the property which is considered to identify an item.
 	 */
@@ -37,7 +35,7 @@ export default class Collection {
 		 * The internal list of items in the collection.
 		 *
 		 * @private
-		 * @property {Object[]}
+		 * @type {Object[]}
 		 */
 		this._items = [];
 
@@ -45,7 +43,7 @@ export default class Collection {
 		 * The internal map of items in the collection.
 		 *
 		 * @private
-		 * @property {Map}
+		 * @type {Map}
 		 */
 		this._itemMap = new Map();
 
@@ -53,7 +51,7 @@ export default class Collection {
 		 * The name of the property which is considered to identify an item.
 		 *
 		 * @private
-		 * @property {String}
+		 * @type {String}
 		 */
 		this._idProperty = options && options.idProperty || 'id';
 	}
@@ -76,6 +74,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 {@link core.Collection.add add}
 	 */
 	add( item, index ) {
 		let itemId;
@@ -157,6 +156,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 {@link core.Collection.remove remove}
 	 */
 	remove( subject ) {
 		let index, id, item;
@@ -270,13 +270,13 @@ utils.mix( Collection, EmitterMixin );
 /**
  * Fired when an item is added to the collection.
  *
- * @event add
+ * @event core.Collection.add
  * @param {Object} item The added item.
  */
 
 /**
  * Fired when an item is removed from the collection.
  *
- * @event remove
+ * @event core.Collection.remove
  * @param {Object} item The removed item.
  */

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

@@ -13,16 +13,14 @@ import utils from './utils.js';
 /**
  * Handles a configuration dictionary.
  *
- * @class core.Config
- * @mixins core.ObservableMixin
+ * @memberOf core
+ * @mixes core.ObservableMixin
  */
-
 export default class Config {
 	/**
 	 * Creates an instance of the {@link Config} class.
 	 *
 	 * @param {Object} [configurations] The initial configurations to be set.
-	 * @constructor
 	 */
 	constructor( configurations ) {
 		if ( configurations ) {
@@ -63,7 +61,7 @@ export default class Config {
 	 *     config.toolbar.collapsed; // true
 	 *     config.toolbar.color; // 'red'
 	 *
-	 * @param {String|Object} nameOrConfigurations The configuration name or an object from which take properties as
+	 * @param {String|Object} name The configuration name or an object from which take properties as
 	 * configuration entries. Configuration names are case-insensitive.
 	 * @param {*} [value=null] The configuration value. Used if a name is passed to nameOrConfigurations.
 	 */
@@ -171,7 +169,7 @@ export default class Config {
 	 * This method is supposed to be called by plugin developers to setup plugin's configurations. It would be
 	 * rarely used for other needs.
 	 *
-	 * @param {String|Object} nameOrConfigurations The configuration name or an object from which take properties as
+	 * @param {String|Object} name The configuration name or an object from which take properties as
 	 * configuration entries.
 	 * @param {*} [value] The configuration value. Used if a name is passed to nameOrConfigurations. If undefined,
 	 * the configuration is set to `null`.
@@ -181,7 +179,6 @@ export default class Config {
 			/**
 			 * TODO
 			 *
-			 * @property
 			 * @type {Config}
 			 */
 			this.definition = new Config();

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

@@ -15,11 +15,9 @@ let eventsCounter = 0;
 /**
  * Mixin that injects the events API into its host.
  *
- * @singleton
- * @class core.EmitterMixin
- * @implementes core.Emitter
+ * @mixin core.EmitterMixin
+ * @implements core.Emitter
  */
-
 const EmitterMixin = {
 	/**
 	 * Registers a callback function to be executed when an event is fired.
@@ -30,6 +28,7 @@ const EmitterMixin = {
 	 * event.
 	 * @param {Number} [priority=10] The priority of this callback in relation to other callbacks to that same event.
 	 * Lower values are called first.
+	 * @method core.EmitterMixin#on
 	 */
 	on( event, callback, ctx, priority ) {
 		const callbacks = getCallbacks( this, event );
@@ -69,6 +68,7 @@ const EmitterMixin = {
 	 * event.
 	 * @param {Number} [priority=10] The priority of this callback in relation to other callbacks to that same event.
 	 * Lower values are called first.
+	 * @method core.EmitterMixin#once
 	 */
 	once( event, callback, ctx, priority ) {
 		const onceCallback = function( event ) {
@@ -90,6 +90,7 @@ const EmitterMixin = {
 	 * @param {Function} callback The function to stop being called.
 	 * @param {Object} [ctx] 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 core.EmitterMixin#off
 	 */
 	off( event, callback, ctx ) {
 		const callbacks = getCallbacksIfAny( this, event );
@@ -118,6 +119,7 @@ const EmitterMixin = {
 	 * @param {Object} [ctx] The object that represents `this` in the callback. Defaults to `emitter`.
 	 * @param {Number} [priority=10] The priority of this callback in relation to other callbacks to that same event.
 	 * Lower values are called first.
+	 * @method core.EmitterMixin#listenTo
 	 */
 	listenTo( emitter, event, callback, ctx, priority ) {
 		let emitters, emitterId, emitterInfo, eventCallbacks;
@@ -174,6 +176,7 @@ const EmitterMixin = {
 	 * 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 core.EmitterMixin#stopListening
 	 */
 	stopListening( emitter, event, callback ) {
 		let emitters = this._listeningTo;
@@ -221,6 +224,7 @@ const EmitterMixin = {
 	 *
 	 * @param {String} event The name of the event.
 	 * @param {...*} [args] Additional arguments to be passed to the callbacks.
+	 * @method core.EmitterMixin#fire
 	 */
 	fire( event, args ) {
 		const callbacks = getCallbacksIfAny( this, event );

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

@@ -11,18 +11,21 @@ import utils from './utils.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.
  *
- * @class EventInfo
+ * @memberOf core
  */
-
 export default class EventInfo {
 	constructor( source, name ) {
 		/**
 		 * The object that fired the event.
+		 *
+		 * @member core.EventInfo#source
 		 */
 		this.source = source;
 
 		/**
 		 * The event name.
+		 *
+		 * @member core.EventInfo#name
 		 */
 		this.name = name;
 
@@ -31,14 +34,14 @@ export default class EventInfo {
 		/**
 		 * Stops the event emitter to call further callbacks for this event interaction.
 		 *
-		 * @method
+		 * @method core.EventInfo#stop
 		 */
 		this.stop = utils.spy();
 
 		/**
 		 * Removes the current callback from future interactions of this event.
 		 *
-		 * @method
+		 * @method core.EventInfo#off
 		 */
 		this.off = utils.spy();
 	}

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

@@ -35,10 +35,8 @@
  * log an error.
  * * Whenever it's really bad and it does not make sense to continue working, throw a {@link core.CKEditorError}.
  *
- * @class log
- * @singleton
+ * @namespace core.log
  */
-
 const log = {
 	/**
 	 * Logs an error to the console.
@@ -49,6 +47,7 @@ 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 core.log.error
 	 */
 	error( message, data ) {
 		console.error( message, data );
@@ -63,10 +62,11 @@ 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 core.log.warn
 	 */
 	warn( message, data ) {
 		console.warn( message, data );
 	}
 };
 
-export default log;
+export default log;

+ 25 - 21
packages/ckeditor5-utils/src/observablemixin.js

@@ -18,12 +18,10 @@ const boundAttributesSymbol = Symbol( 'boundAttributes' );
  * Mixin that injects the "observable attributes" and data binding functionality.
  * Used mainly in the {@link core.ui.Model} class.
  *
- * @singleton
- * @class core.ObservableMixin
- * @mixins EmitterMixin
+ * @mixin core.ObservableMixin
+ * @mixes core.EmitterMixin
  * @implements core.Observable
  */
-
 const ObservableMixin = {
 	/**
 	 * Creates and sets the value of an observable attribute of this object. Such an attribute becomes a part
@@ -35,6 +33,7 @@ const ObservableMixin = {
 	 * 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 core.ObservableMixin#set
 	 * @param {String} name The attributes name.
 	 * @param {*} value The attributes value.
 	 */
@@ -103,15 +102,16 @@ const ObservableMixin = {
 	 * 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 #unbind}.
+	 * **Note**: To release the binding use {@link core.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 core.ObservableMixin#bind
 	 * @param {String...} bindAttrs Observable attributes that will be bound to another observable(s).
-	 * @returns {BindChain}
+	 * @returns {core.BindChain}
 	 */
 	bind( ...bindAttrs ) {
 		if ( !bindAttrs.length || !isStringArray( bindAttrs ) ) {
@@ -150,7 +150,7 @@ const ObservableMixin = {
 		const bindings = new Map();
 
 		/**
-		 * @typedef Binding
+		 * @typedef core.Binding
 		 * @type Object
 		 * @property {Array} attr Attribute which is bound.
 		 * @property {Array} to Array of observable–attribute components of the binding (`{ observable: ..., attr: .. }`).
@@ -164,13 +164,14 @@ const ObservableMixin = {
 		} );
 
 		/**
-		 * @typedef BindChain
+		 * @typedef core.BindChain
 		 * @type Object
-		 * @property {Function} to See {@link #_bindTo}.
+		 * @property {Function} to See {@link core.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 #_boundAttributes}/{@link #_boundObservables}
+		 * @property {Map} _bindings Stores bindings to be kept in
+		 *  {@link core.ObservableMixin#_boundAttributes}/{@link core.ObservableMixin#_boundObservables}
 		 * initiated in this binding chain.
 		 */
 		return {
@@ -184,12 +185,13 @@ const ObservableMixin = {
 	},
 
 	/**
-	 * Removes the binding created with {@link #bind}.
+	 * Removes the binding created with {@link core.ObservableMixin#bind}.
 	 *
 	 *		A.unbind( 'a' );
 	 *		A.unbind();
 	 *
-	 * @param {String...} [bindAttrs] Observable attributes to be unbound. All the bindings will
+	 * @method core.ObservableMixin#unbind
+	 * @param {String} [unbindAttrs] Observable attributes to be unbound. All the bindings will
 	 * be released if no attributes provided.
 	 */
 	unbind( ...unbindAttrs ) {
@@ -262,15 +264,15 @@ function initObservable( observable ) {
 	// The internal hash containing the observable's state.
 	//
 	// @private
-	// @property {Map} _attributes
+	// @type {Map}
 	Object.defineProperty( observable, attributesSymbol, {
 		value: new Map()
 	} );
 
 	// Map containing bindings to external observables. It shares the binding objects
-	// (`{ observable: A, attr: 'a', to: ... }`) with {@link #_boundAttributes} and
+	// (`{ observable: A, attr: 'a', to: ... }`) with {@link core.ObservableMixin#_boundAttributes} and
 	// it is used to observe external observables to update own attributes accordingly.
-	// See {@link #bind}.
+	// See {@link core.ObservableMixin#bind}.
 	//
 	//		A.bind( 'a', 'b', 'c' ).to( B, 'x', 'y', 'x' );
 	//		console.log( A._boundObservables );
@@ -311,15 +313,17 @@ function initObservable( observable ) {
 	//			} )
 	//
 	// @private
-	// @property {Map} _boundObservables
+	// @type {Map}
 	Object.defineProperty( observable, boundObservablesSymbol, {
 		value: new Map()
 	} );
 
 	// Object that stores which attributes of this observable are bound and how. It shares
-	// the binding objects (`{ observable: A, attr: 'a', to: ... }`) with {@link #_boundObservables}.
-	// This data structure is a reverse of {@link #_boundObservables} and it is helpful for {@link #unbind}.
-	// See {@link #bind}.
+	// the binding objects (`{ observable: A, attr: 'a', to: ... }`) with {@link core.ObservableMixin#_boundObservables}.
+	// This data structure is a reverse of {@link core.ObservableMixin#_boundObservables} and it is helpful for
+	// {@link core.ObservableMixin#unbind}.
+	//
+	// See {@link core.ObservableMixin#bind}.
 	//
 	//		A.bind( 'a', 'b', 'c' ).to( B, 'x', 'y', 'x' );
 	//		console.log( A._boundAttributes );
@@ -341,13 +345,13 @@ function initObservable( observable ) {
 	//			} )
 	//
 	// @private
-	// @property {Map} _boundAttributes
+	// @type {Map}
 	Object.defineProperty( observable, boundAttributesSymbol, {
 		value: new Map()
 	} );
 }
 
-// A chaining for {@link #bind} providing `.to()` interface.
+// A chaining for {@link core.ObservableMixin#bind} providing `.to()` interface.
 //
 // @private
 // @param {...[Observable|String|Function]} args Arguments of the `.to( args )` binding.

+ 19 - 5
packages/ckeditor5-utils/src/utils.js

@@ -8,12 +8,8 @@
 import isPlainObject from './lib/lodash/isPlainObject.js';
 
 /**
- * An index at which arrays differ. If arrays are same at all indexes, it represents how arrays are related.
- * In this case, possible values are: 'SAME', 'PREFIX' or 'EXTENSION'.
- *
- * @typedef {String|Number} utils.ArrayRelation
+ * @namespace core.utils
  */
-
 const utils = {
 	/**
 	 * Creates a spy function (ala Sinon.js) that can be used to inspect call to it.
@@ -22,6 +18,7 @@ const utils = {
 	 *
 	 *  * spy.called: property set to `true` if the function has been called at least once.
 	 *
+	 * @memberOf core.utils
 	 * @returns {Function} The spy function.
 	 */
 	spy() {
@@ -34,6 +31,8 @@ const utils = {
 	 * 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 core.utils
 	 * @returns {Number} A number representing the id.
 	 */
 	uid: ( () => {
@@ -47,6 +46,7 @@ const utils = {
 	/**
 	 * Checks if value implements iterator interface.
 	 *
+	 * @memberOf core.utils
 	 * @param {*} value The value to check.
 	 * @returns {Boolean} True if value implements iterator interface.
 	 */
@@ -66,6 +66,7 @@ const utils = {
 	 *   compareArrays( [ 0, 2 ], [ 1, 2 ] ); // 0
 	 *   compareArrays( [ 0, 2 ], [ 0, 1 ] ); // 1
 	 *
+	 * @memberOf core.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`.
@@ -99,6 +100,7 @@ const utils = {
 	 *		const map = utils.objectToMap( { 'foo': 1, 'bar': 2 } );
 	 *		map.get( 'foo' ); // 1
 	 *
+	 * @memberOf core.utils
 	 * @param {Object} obj Object to transform.
 	 * @returns {Map} Map created from object.
 	 */
@@ -119,6 +121,7 @@ const utils = {
 	 *		map = utils.toMap( [ [ 'foo', 1 ], [ 'bar', 2 ] ] );
 	 *		map = utils.toMap( anotherMap );
 	 *
+	 * @memberOf core.utils
 	 * @param {Object|Iterable} data Object or iterable to transform.
 	 * @returns {Map} Map created from data.
 	 */
@@ -133,6 +136,7 @@ const utils = {
 	/**
 	 * Checks whether given {Map}s are equal, that is has same size and same key-value pairs.
 	 *
+	 * @memberOf core.utils
 	 * @returns {Boolean} `true` if given maps are equal, `false` otherwise.
 	 */
 	mapsEqual( mapA, mapB ) {
@@ -155,6 +159,7 @@ const utils = {
 	/**
 	 * Returns `nth` (starts from `0` of course) item of an `iterable`.
 	 *
+	 * @memberOf core.utils
 	 * @param {Number} index
 	 * @param {Iterable.<*>} iterable
 	 * @returns {*}
@@ -190,6 +195,7 @@ const utils = {
 	 *
 	 * Note: Properties which already exist in the base class will not be overriden.
 	 *
+	 * @memberOf core.utils
 	 * @param {Function} [baseClass] Class which prototype will be extended.
 	 * @param {Object} [...mixins] Objects from which to get properties.
 	 */
@@ -210,4 +216,12 @@ const utils = {
 	}
 };
 
+/**
+ * An index at which arrays differ. If arrays are same at all indexes, it represents how arrays are related.
+ * In this case, possible values are: 'SAME', 'PREFIX' or 'EXTENSION'.
+ *
+ * @memberOf core.utils
+ * @typedef {String|Number} ArrayRelation
+ */
+
 export default utils;