@ckeditor/ckeditor5-utils 35.3.2 → 35.4.0

package/src/emittermixin.js

@@ -5,7 +5,6 @@
 /**
  * @module utils/emittermixin
  */
-/* eslint-disable new-cap */
 import EventInfo from './eventinfo';
 import uid from './uid';
 import priorities from './priorities';
@@ -16,18 +15,11 @@ import CKEditorError from './ckeditorerror';
 const _listeningTo = Symbol('listeningTo');
 const _emitterId = Symbol('emitterId');
 const _delegations = Symbol('delegations');
-/**
- * Mixin that injects the {@link ~Emitter events API} into its host.
- *
- * Read more about the concept of emitters in the:
- * * {@glink framework/guides/architecture/core-editor-architecture#event-system-and-observables Event system and observables}
- * section of the {@glink framework/guides/architecture/core-editor-architecture Core editor architecture} guide.
- * * {@glink framework/guides/deep-dive/event-system Event system} deep dive guide.
- *
- * @mixin EmitterMixin
- * @implements module:utils/emittermixin~Emitter
- */
+const defaultEmitterClass = EmitterMixin(Object);
 export default function EmitterMixin(base) {
+    if (!base) {
+        return defaultEmitterClass;
+    }
     class Mixin extends base {
         on(event, callback, options) {
             this.listenTo(this, event, callback, options);
@@ -250,24 +242,21 @@ export default function EmitterMixin(base) {
     }
     return Mixin;
 }
-export const Emitter = EmitterMixin(Object);
 // Backward compatibility with `mix`
 ([
     'on', 'once', 'off', 'listenTo',
     'stopListening', 'fire', 'delegate', 'stopDelegating',
     '_addEventListener', '_removeEventListener'
 ]).forEach(key => {
-    EmitterMixin[key] = Emitter.prototype[key];
+    EmitterMixin[key] = defaultEmitterClass.prototype[key];
 });
 /**
  * Checks if `listeningEmitter` listens to an emitter with given `listenedToEmitterId` and if so, returns that emitter.
  * If not, returns `null`.
  *
  * @internal
- * @protected
- * @param {module:utils/emittermixin~Emitter} listeningEmitter An emitter that listens.
- * @param {String} listenedToEmitterId Unique emitter id of emitter listened to.
- * @returns {module:utils/emittermixin~Emitter|null}
+ * @param listeningEmitter An emitter that listens.
+ * @param listenedToEmitterId Unique emitter id of emitter listened to.
  */
 export function _getEmitterListenedTo(listeningEmitter, listenedToEmitterId) {
     const listeningTo = listeningEmitter[_listeningTo];
@@ -282,9 +271,8 @@ export function _getEmitterListenedTo(listeningEmitter, listenedToEmitterId) {
  * **Note:** `_emitterId` can be set only once.
  *
  * @internal
- * @protected
- * @param {module:utils/emittermixin~Emitter} emitter An emitter for which id will be set.
- * @param {String} [id] Unique id to set. If not passed, random unique id will be set.
+ * @param emitter An emitter for which id will be set.
+ * @param id Unique id to set. If not passed, random unique id will be set.
  */
 export function _setEmitterId(emitter, id) {
     if (!emitter[_emitterId]) {
@@ -295,16 +283,16 @@ export function _setEmitterId(emitter, id) {
  * Returns emitter's unique id.
  *
  * @internal
- * @protected
- * @param {module:utils/emittermixin~Emitter} emitter An emitter which id will be returned.
- * @returns {String|undefined}
+ * @param emitter An emitter which id will be returned.
  */
 export function _getEmitterId(emitter) {
     return emitter[_emitterId];
 }
-// Gets the internal `_events` property of the given object.
-// `_events` property store all lists with callbacks for registered event names.
-// If there were no events registered on the object, empty `_events` object is created.
+/**
+ * Gets the internal `_events` property of the given object.
+ * `_events` property store all lists with callbacks for registered event names.
+ * If there were no events registered on the object, empty `_events` object is created.
+ */
 function getEvents(source) {
     if (!source._events) {
         Object.defineProperty(source, '_events', {
@@ -313,18 +301,22 @@ function getEvents(source) {
     }
     return source._events;
 }
-// Creates event node for generic-specific events relation architecture.
+/**
+ * Creates event node for generic-specific events relation architecture.
+ */
 function makeEventNode() {
     return {
         callbacks: [],
         childEvents: []
     };
 }
-// Creates an architecture for generic-specific events relation.
-// If needed, creates all events for given eventName, i.e. if the first registered event
-// is foo:bar:abc, it will create foo:bar:abc, foo:bar and foo event and tie them together.
-// It also copies callbacks from more generic events to more specific events when
-// specific events are created.
+/**
+ * Creates an architecture for generic-specific events relation.
+ * If needed, creates all events for given eventName, i.e. if the first registered event
+ * is foo:bar:abc, it will create foo:bar:abc, foo:bar and foo event and tie them together.
+ * It also copies callbacks from more generic events to more specific events when
+ * specific events are created.
+ */
 function createEventNamespace(source, eventName) {
     const events = getEvents(source);
     // First, check if the event we want to add to the structure already exists.
@@ -375,9 +367,11 @@ function createEventNamespace(source, eventName) {
         events[name].childEvents.push(childEventName);
     }
 }
-// Gets an array containing callbacks list for a given event and it's more specific events.
-// I.e. if given event is foo:bar and there is also foo:bar:abc event registered, this will
-// return callback list of foo:bar and foo:bar:abc (but not foo).
+/**
+ * Gets an array containing callbacks list for a given event and it's more specific events.
+ * I.e. if given event is foo:bar and there is also foo:bar:abc event registered, this will
+ * return callback list of foo:bar and foo:bar:abc (but not foo).
+ */
 function getCallbacksListsForNamespace(source, eventName) {
     const eventNode = getEvents(source)[eventName];
     if (!eventNode) {
@@ -390,9 +384,11 @@ function getCallbacksListsForNamespace(source, eventName) {
     }
     return callbacksLists;
 }
-// Get the list of callbacks for a given event, but only if there any callbacks have been registered.
-// If there are no callbacks registered for given event, it checks if this is a specific event and looks
-// for callbacks for it's more generic version.
+/**
+ * Get the list of callbacks for a given event, but only if there any callbacks have been registered.
+ * If there are no callbacks registered for given event, it checks if this is a specific event and looks
+ * for callbacks for it's more generic version.
+ */
 function getCallbacksForEvent(source, eventName) {
     let event;
     if (!source._events || !(event = source._events[eventName]) || !event.callbacks.length) {
@@ -409,13 +405,13 @@ function getCallbacksForEvent(source, eventName) {
     }
     return event.callbacks;
 }
-// Fires delegated events for given map of destinations.
-//
-// @private
-// * @param {Map.<utils.Emitter>} destinations A map containing
-// `[ {@link module:utils/emittermixin~Emitter}, "event name" ]` pair destinations.
-// * @param {utils.EventInfo} eventInfo The original event info object.
-// * @param {Array.<*>} fireArgs Arguments the original event was fired with.
+/**
+ * Fires delegated events for given map of destinations.
+ *
+ * @param destinations A map containing `[ {@link module:utils/emittermixin~Emitter}, "event name" ]` pair destinations.
+ * @param eventInfo The original event info object.
+ * @param fireArgs Arguments the original event was fired with.
+ */
 function fireDelegatedEvents(destinations, eventInfo, fireArgs) {
     for (let [emitter, name] of destinations) {
         if (!name) {
@@ -429,7 +425,9 @@ function fireDelegatedEvents(destinations, eventInfo, fireArgs) {
         emitter.fire(delegatedInfo, ...fireArgs);
     }
 }
-// Helper for registering event callback on the emitter.
+/**
+ * Helper for registering event callback on the emitter.
+ */
 function addEventListener(listener, emitter, event, callback, options) {
     if (emitter._addEventListener) {
         emitter._addEventListener(event, callback, options);
@@ -440,7 +438,9 @@ function addEventListener(listener, emitter, event, callback, options) {
         (listener._addEventListener).call(emitter, event, callback, options);
     }
 }
-// Helper for removing event callback from the emitter.
+/**
+ * Helper for removing event callback from the emitter.
+ */
 function removeEventListener(listener, emitter, event, callback) {
     if (emitter._removeEventListener) {
         emitter._removeEventListener(event, callback);

package/src/env.js

@@ -9,8 +9,6 @@
 /**
  * Safely returns `userAgent` from browser's navigator API in a lower case.
  * If navigator API is not available it will return an empty string.
- *
- * @returns {String}
  */
 export function getUserAgent() {
     // In some environments navigator API might not be available.
@@ -24,73 +22,16 @@ export function getUserAgent() {
 const userAgent = getUserAgent();
 /**
  * A namespace containing environment and browser information.
- *
- * @namespace
  */
 const env = {
-    /**
-     * Indicates that the application is running on Macintosh.
-     *
-     * @static
-     * @type {Boolean}
-     */
     isMac: isMac(userAgent),
-    /**
-     * Indicates that the application is running on Windows.
-     *
-     * @static
-     * @type {Boolean}
-     */
     isWindows: isWindows(userAgent),
-    /**
-     * Indicates that the application is running in Firefox (Gecko).
-     *
-     * @static
-     * @type {Boolean}
-     */
     isGecko: isGecko(userAgent),
-    /**
-     * Indicates that the application is running in Safari.
-     *
-     * @static
-     * @type {Boolean}
-     */
     isSafari: isSafari(userAgent),
-    /**
-     * Indicates the the application is running in iOS.
-     *
-     * @static
-     * @type {Boolean}
-     */
     isiOS: isiOS(userAgent),
-    /**
-     * Indicates that the application is running on Android mobile device.
-     *
-     * @static
-     * @type {Boolean}
-     */
     isAndroid: isAndroid(userAgent),
-    /**
-     * Indicates that the application is running in a browser using the Blink engine.
-     *
-     * @static
-     * @type {Boolean}
-     */
     isBlink: isBlink(userAgent),
-    /**
-     * Environment features information.
-     *
-     * @memberOf module:utils/env~env
-     * @namespace
-     */
     features: {
-        /**
-         * Indicates that the environment supports ES2018 Unicode property escapes — like `\p{P}` or `\p{L}`.
-         * More information about unicode properties might be found
-         * [in Unicode Standard Annex #44](https://www.unicode.org/reports/tr44/#GC_Values_Table).
-         *
-         * @type {Boolean}
-         */
         isRegExpUnicodePropertySupported: isRegExpUnicodePropertySupported()
     }
 };
@@ -98,8 +39,8 @@ export default env;
 /**
  * Checks if User Agent represented by the string is running on Macintosh.
  *
- * @param {String} userAgent **Lowercase** `navigator.userAgent` string.
- * @returns {Boolean} Whether User Agent is running on Macintosh or not.
+ * @param userAgent **Lowercase** `navigator.userAgent` string.
+ * @returns Whether User Agent is running on Macintosh or not.
  */
 export function isMac(userAgent) {
     return userAgent.indexOf('macintosh') > -1;
@@ -107,8 +48,8 @@ export function isMac(userAgent) {
 /**
  * Checks if User Agent represented by the string is running on Windows.
  *
- * @param {String} userAgent **Lowercase** `navigator.userAgent` string.
- * @returns {Boolean} Whether User Agent is running on Windows or not.
+ * @param userAgent **Lowercase** `navigator.userAgent` string.
+ * @returns Whether User Agent is running on Windows or not.
  */
 export function isWindows(userAgent) {
     return userAgent.indexOf('windows') > -1;
@@ -116,8 +57,8 @@ export function isWindows(userAgent) {
 /**
  * Checks if User Agent represented by the string is Firefox (Gecko).
  *
- * @param {String} userAgent **Lowercase** `navigator.userAgent` string.
- * @returns {Boolean} Whether User Agent is Firefox or not.
+ * @param userAgent **Lowercase** `navigator.userAgent` string.
+ * @returns Whether User Agent is Firefox or not.
  */
 export function isGecko(userAgent) {
     return !!userAgent.match(/gecko\/\d+/);
@@ -125,8 +66,8 @@ export function isGecko(userAgent) {
 /**
  * Checks if User Agent represented by the string is Safari.
  *
- * @param {String} userAgent **Lowercase** `navigator.userAgent` string.
- * @returns {Boolean} Whether User Agent is Safari or not.
+ * @param userAgent **Lowercase** `navigator.userAgent` string.
+ * @returns Whether User Agent is Safari or not.
  */
 export function isSafari(userAgent) {
     return userAgent.indexOf(' applewebkit/') > -1 && userAgent.indexOf('chrome') === -1;
@@ -134,8 +75,8 @@ export function isSafari(userAgent) {
 /**
  * Checks if User Agent represented by the string is running in iOS.
  *
- * @param {String} userAgent **Lowercase** `navigator.userAgent` string.
- * @returns {Boolean} Whether User Agent is running in iOS or not.
+ * @param userAgent **Lowercase** `navigator.userAgent` string.
+ * @returns Whether User Agent is running in iOS or not.
  */
 export function isiOS(userAgent) {
     // "Request mobile site" || "Request desktop site".
@@ -144,8 +85,8 @@ export function isiOS(userAgent) {
 /**
  * Checks if User Agent represented by the string is Android mobile device.
  *
- * @param {String} userAgent **Lowercase** `navigator.userAgent` string.
- * @returns {Boolean} Whether User Agent is Safari or not.
+ * @param userAgent **Lowercase** `navigator.userAgent` string.
+ * @returns Whether User Agent is Safari or not.
  */
 export function isAndroid(userAgent) {
     return userAgent.indexOf('android') > -1;
@@ -153,8 +94,8 @@ export function isAndroid(userAgent) {
 /**
  * Checks if User Agent represented by the string is Blink engine.
  *
- * @param {String} userAgent **Lowercase** `navigator.userAgent` string.
- * @returns {Boolean} Whether User Agent is Blink engine or not.
+ * @param userAgent **Lowercase** `navigator.userAgent` string.
+ * @returns Whether User Agent is Blink engine or not.
  */
 export function isBlink(userAgent) {
     // The Edge browser before switching to the Blink engine used to report itself as Chrome (and "Edge/")
@@ -165,8 +106,6 @@ export function isBlink(userAgent) {
  * Checks if the current environment supports ES2018 Unicode properties like `\p{P}` or `\p{L}`.
  * More information about unicode properties might be found
  * [in Unicode Standard Annex #44](https://www.unicode.org/reports/tr44/#GC_Values_Table).
- *
- * @returns {Boolean}
  */
 export function isRegExpUnicodePropertySupported() {
     let isSupported = false;

package/src/eventinfo.js

@@ -12,8 +12,8 @@ import spy from './spy';
  */
 export default class EventInfo {
     /**
-     * @param {Object} source The emitter.
-     * @param {String} name The event name.
+     * @param source The emitter.
+     * @param name The event name.
      */
     constructor(source, name) {
         this.source = source;

package/src/fastdiff.js

@@ -2,94 +2,112 @@
  * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
+/**
+ * @module utils/fastdiff
+ */
 /**
  * Finds positions of the first and last change in the given string/array and generates a set of changes:
  *
- *		fastDiff( '12a', '12xyza' );
- *		// [ { index: 2, type: 'insert', values: [ 'x', 'y', 'z' ] } ]
+ * ```ts
+ * fastDiff( '12a', '12xyza' );
+ * // [ { index: 2, type: 'insert', values: [ 'x', 'y', 'z' ] } ]
  *
- *		fastDiff( '12a', '12aa' );
- *		// [ { index: 3, type: 'insert', values: [ 'a' ] } ]
+ * fastDiff( '12a', '12aa' );
+ * // [ { index: 3, type: 'insert', values: [ 'a' ] } ]
  *
- *		fastDiff( '12xyza', '12a' );
- *		// [ { index: 2, type: 'delete', howMany: 3 } ]
+ * fastDiff( '12xyza', '12a' );
+ * // [ { index: 2, type: 'delete', howMany: 3 } ]
  *
- *		fastDiff( [ '1', '2', 'a', 'a' ], [ '1', '2', 'a' ] );
- *		// [ { index: 3, type: 'delete', howMany: 1 } ]
+ * fastDiff( [ '1', '2', 'a', 'a' ], [ '1', '2', 'a' ] );
+ * // [ { index: 3, type: 'delete', howMany: 1 } ]
  *
- *		fastDiff( [ '1', '2', 'a', 'b', 'c', '3' ], [ '2', 'a', 'b' ] );
- *		// [ { index: 0, type: 'insert', values: [ '2', 'a', 'b' ] }, { index: 3, type: 'delete', howMany: 6 } ]
+ * fastDiff( [ '1', '2', 'a', 'b', 'c', '3' ], [ '2', 'a', 'b' ] );
+ * // [ { index: 0, type: 'insert', values: [ '2', 'a', 'b' ] }, { index: 3, type: 'delete', howMany: 6 } ]
+ * ```
  *
  * Passed arrays can contain any type of data, however to compare them correctly custom comparator function
  * should be passed as a third parameter:
  *
- *		fastDiff( [ { value: 1 }, { value: 2 } ], [ { value: 1 }, { value: 3 } ], ( a, b ) => {
- *			return a.value === b.value;
- *		} );
- *		// [ { index: 1, type: 'insert', values: [ { value: 3 } ] }, { index: 2, type: 'delete', howMany: 1 } ]
+ * ```ts
+ * fastDiff( [ { value: 1 }, { value: 2 } ], [ { value: 1 }, { value: 3 } ], ( a, b ) => {
+ * 	return a.value === b.value;
+ * } );
+ * // [ { index: 1, type: 'insert', values: [ { value: 3 } ] }, { index: 2, type: 'delete', howMany: 1 } ]
+ * ```
  *
  * The resulted set of changes can be applied to the input in order to transform it into the output, for example:
  *
- *		let input = '12abc3';
- *		const output = '2ab';
- *		const changes = fastDiff( input, output );
+ * ```ts
+ * let input = '12abc3';
+ * const output = '2ab';
+ * const changes = fastDiff( input, output );
  *
- *		changes.forEach( change => {
- *			if ( change.type == 'insert' ) {
- *				input = input.substring( 0, change.index ) + change.values.join( '' ) + input.substring( change.index );
- *			} else if ( change.type == 'delete' ) {
- *				input = input.substring( 0, change.index ) + input.substring( change.index + change.howMany );
- *			}
- *		} );
+ * changes.forEach( change => {
+ * 	if ( change.type == 'insert' ) {
+ * 		input = input.substring( 0, change.index ) + change.values.join( '' ) + input.substring( change.index );
+ * 	} else if ( change.type == 'delete' ) {
+ * 		input = input.substring( 0, change.index ) + input.substring( change.index + change.howMany );
+ * 	}
+ * } );
  *
- *		// input equals output now
+ * // input equals output now
+ * ```
  *
  * or in case of arrays:
  *
- *		let input = [ '1', '2', 'a', 'b', 'c', '3' ];
- *		const output = [ '2', 'a', 'b' ];
- *		const changes = fastDiff( input, output );
+ * ```ts
+ * let input = [ '1', '2', 'a', 'b', 'c', '3' ];
+ * const output = [ '2', 'a', 'b' ];
+ * const changes = fastDiff( input, output );
  *
- *		changes.forEach( change => {
- *			if ( change.type == 'insert' ) {
- *				input = input.slice( 0, change.index ).concat( change.values, input.slice( change.index ) );
- *			} else if ( change.type == 'delete' ) {
- *				input = input.slice( 0, change.index ).concat( input.slice( change.index + change.howMany ) );
- *			}
- *		} );
+ * changes.forEach( change => {
+ * 	if ( change.type == 'insert' ) {
+ * 		input = input.slice( 0, change.index ).concat( change.values, input.slice( change.index ) );
+ * 	} else if ( change.type == 'delete' ) {
+ * 		input = input.slice( 0, change.index ).concat( input.slice( change.index + change.howMany ) );
+ * 	}
+ * } );
  *
- *		// input equals output now
+ * // input equals output now
+ * ```
  *
  * By passing `true` as the fourth parameter (`atomicChanges`) the output of this function will become compatible with
  * the {@link module:utils/diff~diff `diff()`} function:
  *
- *		fastDiff( '12a', '12xyza' );
- *		// [ 'equal', 'equal', 'insert', 'insert', 'insert', 'equal' ]
+ * ```ts
+ * fastDiff( '12a', '12xyza', undefined, true );
+ * // [ 'equal', 'equal', 'insert', 'insert', 'insert', 'equal' ]
+ * ```
  *
  * The default output format of this function is compatible with the output format of
  * {@link module:utils/difftochanges~diffToChanges `diffToChanges()`}. The `diffToChanges()` input format is, in turn,
  * compatible with the output of {@link module:utils/diff~diff `diff()`}:
  *
- *		const a = '1234';
- *		const b = '12xyz34';
- *
- *		// Both calls will return the same results (grouped changes format).
- *		fastDiff( a, b );
- *		diffToChanges( diff( a, b ) );
- *
- *		// Again, both calls will return the same results (atomic changes format).
- *		fastDiff( a, b, null, true );
- *		diff( a, b );
- *
- *
- * @param {Array|String} a Input array or string.
- * @param {Array|String} b Input array or string.
- * @param {Function} [cmp] Optional function used to compare array values, by default `===` (strict equal operator) is used.
- * @param {Boolean} [atomicChanges=false] Whether an array of `inset|delete|equal` operations should
+ * ```ts
+ * const a = '1234';
+ * const b = '12xyz34';
+ *
+ * // Both calls will return the same results (grouped changes format).
+ * fastDiff( a, b );
+ * diffToChanges( diff( a, b ) );
+ *
+ * // Again, both calls will return the same results (atomic changes format).
+ * fastDiff( a, b, undefined, true );
+ * diff( a, b );
+ * ```
+ *
+ * @typeParam T The type of array elements.
+ * @typeParam AtomicChanges The type of `atomicChanges` parameter (selects the result type).
+ * @param a Input array or string.
+ * @param b Input array or string.
+ * @param cmp Optional function used to compare array values, by default `===` (strict equal operator) is used.
+ * @param atomicChanges Whether an array of `inset|delete|equal` operations should
  * be returned instead of changes set. This makes this function compatible with {@link module:utils/diff~diff `diff()`}.
- * @returns {Array} Array of changes.
+ * Defaults to `false`.
+ * @returns Array of changes. The elements are either {@link module:utils/diff~DiffResult} or {@link module:utils/difftochanges~Change},
+ * depending on `atomicChanges` parameter.
  */
-export default function fastDiff(a, b, cmp, atomicChanges = false) {
+export default function fastDiff(a, b, cmp, atomicChanges) {
     // Set the comparator function.
     cmp = cmp || function (a, b) {
         return a === b;
@@ -105,24 +123,23 @@ export default function fastDiff(a, b, cmp, atomicChanges = false) {
     // Find first and last change.
     const changeIndexes = findChangeBoundaryIndexes(arrayA, arrayB, cmp);
     // Transform into changes array.
-    return atomicChanges ? changeIndexesToAtomicChanges(changeIndexes, arrayB.length) : changeIndexesToChanges(arrayB, changeIndexes);
+    const result = atomicChanges ?
+        changeIndexesToAtomicChanges(changeIndexes, arrayB.length) :
+        changeIndexesToChanges(arrayB, changeIndexes);
+    return result;
 }
-// Finds position of the first and last change in the given arrays. For example:
-//
-//		const indexes = findChangeBoundaryIndexes( [ '1', '2', '3', '4' ], [ '1', '3', '4', '2', '4' ] );
-//		console.log( indexes ); // { firstIndex: 1, lastIndexOld: 3, lastIndexNew: 4 }
-//
-// The above indexes means that in the first array the modified part is `1[23]4` and in the second array it is `1[342]4`.
-// Based on such indexes, array with `insert`/`delete` operations which allows transforming first value into the second one
-// can be generated.
-//
-// @param {Array} arr1
-// @param {Array} arr2
-// @param {Function} cmp Comparator function.
-// @returns {Object}
-// @returns {Number} return.firstIndex Index of the first change in both values (always the same for both).
-// @returns {Number} result.lastIndexOld Index of the last common value in `arr1`.
-// @returns {Number} result.lastIndexNew Index of the last common value in `arr2`.
+/**
+ * Finds position of the first and last change in the given arrays. For example:
+ *
+ * ```ts
+ * const indexes = findChangeBoundaryIndexes( [ '1', '2', '3', '4' ], [ '1', '3', '4', '2', '4' ] );
+ * console.log( indexes ); // { firstIndex: 1, lastIndexOld: 3, lastIndexNew: 4 }
+ * ```
+ *
+ * The above indexes means that in the first array the modified part is `1[23]4` and in the second array it is `1[342]4`.
+ * Based on such indexes, array with `insert`/`delete` operations which allows transforming first value into the second one
+ * can be generated.
+ */
 function findChangeBoundaryIndexes(arr1, arr2, cmp) {
     // Find the first difference between passed values.
     const firstIndex = findFirstDifferenceIndex(arr1, arr2, cmp);
@@ -150,12 +167,9 @@ function findChangeBoundaryIndexes(arr1, arr2, cmp) {
     const lastIndexNew = arr2.length - lastIndex;
     return { firstIndex, lastIndexOld, lastIndexNew };
 }
-// Returns a first index on which given arrays differ. If both arrays are the same, -1 is returned.
-//
-// @param {Array} arr1
-// @param {Array} arr2
-// @param {Function} cmp Comparator function.
-// @returns {Number}
+/**
+ * Returns a first index on which given arrays differ. If both arrays are the same, -1 is returned.
+ */
 function findFirstDifferenceIndex(arr1, arr2, cmp) {
     for (let i = 0; i < Math.max(arr1.length, arr2.length); i++) {
         if (arr1[i] === undefined || arr2[i] === undefined || !cmp(arr1[i], arr2[i])) {
@@ -164,21 +178,24 @@ function findFirstDifferenceIndex(arr1, arr2, cmp) {
     }
     return -1; // Return -1 if arrays are equal.
 }
-// Returns a copy of the given array with `howMany` elements removed starting from the beginning and in reversed order.
-//
-// @param {Array} arr Array to be processed.
-// @param {Number} howMany How many elements from array beginning to remove.
-// @returns {Array} Shortened and reversed array.
+/**
+ * Returns a copy of the given array with `howMany` elements removed starting from the beginning and in reversed order.
+ *
+ * @param arr Array to be processed.
+ * @param howMany How many elements from array beginning to remove.
+ * @returns Shortened and reversed array.
+ */
 function cutAndReverse(arr, howMany) {
     return arr.slice(howMany).reverse();
 }
-// Generates changes array based on change indexes from `findChangeBoundaryIndexes` function. This function will
-// generate array with 0 (no changes), 1 (deletion or insertion) or 2 records (insertion and deletion).
-//
-// @param {Array} newArray New array for which change indexes were calculated.
-// @param {Object} changeIndexes Change indexes object from `findChangeBoundaryIndexes` function.
-// @returns {Array.<module:utils/difftochanges~Change>} Array of changes compatible with
-// {@link module:utils/difftochanges~diffToChanges} format.
+/**
+ * Generates changes array based on change indexes from `findChangeBoundaryIndexes` function. This function will
+ * generate array with 0 (no changes), 1 (deletion or insertion) or 2 records (insertion and deletion).
+ *
+ * @param newArray New array for which change indexes were calculated.
+ * @param changeIndexes Change indexes object from `findChangeBoundaryIndexes` function.
+ * @returns Array of changes compatible with {@link module:utils/difftochanges~diffToChanges} format.
+ */
 function changeIndexesToChanges(newArray, changeIndexes) {
     const result = [];
     const { firstIndex, lastIndexOld, lastIndexNew } = changeIndexes;
@@ -201,11 +218,13 @@ function changeIndexesToChanges(newArray, changeIndexes) {
     }
     return result;
 }
-// Generates array with set `equal|insert|delete` operations based on change indexes from `findChangeBoundaryIndexes` function.
-//
-// @param {Object} changeIndexes Change indexes object from `findChangeBoundaryIndexes` function.
-// @param {Number} newLength Length of the new array on which `findChangeBoundaryIndexes` calculated change indexes.
-// @returns {Array.<module:utils/diff~DiffResult>} Array of changes compatible with {@link module:utils/diff~diff} format.
+/**
+ * Generates array with set `equal|insert|delete` operations based on change indexes from `findChangeBoundaryIndexes` function.
+ *
+ * @param changeIndexes Change indexes object from `findChangeBoundaryIndexes` function.
+ * @param newLength Length of the new array on which `findChangeBoundaryIndexes` calculated change indexes.
+ * @returns Array of changes compatible with {@link module:utils/diff~diff} format.
+ */
 function changeIndexesToAtomicChanges(changeIndexes, newLength) {
     const { firstIndex, lastIndexOld, lastIndexNew } = changeIndexes;
     // No changes.