@ckeditor/ckeditor5-utils 35.3.2 → 35.4.0

package/src/comparearrays.js

@@ -11,15 +11,17 @@
  * a flag specifying the relation is returned. Flags are negative numbers, so whenever a number >= 0 is returned
  * it means that arrays differ.
  *
- *		compareArrays( [ 0, 2 ], [ 0, 2 ] );		// 'same'
- *		compareArrays( [ 0, 2 ], [ 0, 2, 1 ] );		// 'prefix'
- *		compareArrays( [ 0, 2 ], [ 0 ] );			// 'extension'
- *		compareArrays( [ 0, 2 ], [ 1, 2 ] );		// 0
- *		compareArrays( [ 0, 2 ], [ 0, 1 ] );		// 1
+ * ```ts
+ * compareArrays( [ 0, 2 ], [ 0, 2 ] );		// 'same'
+ * compareArrays( [ 0, 2 ], [ 0, 2, 1 ] );		// 'prefix'
+ * compareArrays( [ 0, 2 ], [ 0 ] );			// 'extension'
+ * compareArrays( [ 0, 2 ], [ 1, 2 ] );		// 0
+ * compareArrays( [ 0, 2 ], [ 0, 1 ] );		// 1
+ * ```
  *
- * @param {Array} a Array that is compared.
- * @param {Array} b Array to compare with.
- * @returns {module:utils/comparearrays~ArrayRelation|Number} How array `a` is related to `b`.
+ * @param a Array that is compared.
+ * @param b Array to compare with.
+ * @returns How array `a` is related to `b`.
  */
 export default function compareArrays(a, b) {
     const minLen = Math.min(a.length, b.length);

package/src/config.js

@@ -8,21 +8,17 @@
 import { isPlainObject, isElement, cloneDeepWith } from 'lodash-es';
 /**
  * Handles a configuration dictionary.
+ *
+ * @typeParam Cfg A type of the configuration dictionary.
  */
 export default class Config {
     /**
      * Creates an instance of the {@link ~Config} class.
      *
-     * @param {Object} [configurations] The initial configurations to be set. Usually, provided by the user.
-     * @param {Object} [defaultConfigurations] The default configurations. Usually, provided by the system.
+     * @param configurations The initial configurations to be set. Usually, provided by the user.
+     * @param defaultConfigurations The default configurations. Usually, provided by the system.
      */
     constructor(configurations, defaultConfigurations) {
-        /**
-         * Store for the whole configuration.
-         *
-         * @private
-         * @member {Object}
-         */
         this._config = {};
         // Set default configuration.
         if (defaultConfigurations) {
@@ -35,57 +31,9 @@ export default class Config {
             this._setObjectToTarget(this._config, configurations);
         }
     }
-    /**
-     * Set configuration values.
-     *
-     * It accepts both a name/value pair or an object, which properties and values will be used to set
-     * configurations.
-     *
-     * It also accepts setting a "deep configuration" by using dots in the name. For example, `'resize.width'` sets
-     * the value for the `width` configuration in the `resize` subset.
-     *
-     *		config.set( 'width', 500 );
-     *		config.set( 'toolbar.collapsed', true );
-     *
-     *		// Equivalent to:
-     *		config.set( {
-     *			width: 500
-     *			toolbar: {
-     *				collapsed: true
-     *			}
-     *		} );
-     *
-     * Passing an object as the value will amend the configuration, not replace it.
-     *
-     *		config.set( 'toolbar', {
-     *			collapsed: true,
-     *		} );
-     *
-     *		config.set( 'toolbar', {
-     *			color: 'red',
-     *		} );
-     *
-     *		config.get( 'toolbar.collapsed' ); // true
-     *		config.get( 'toolbar.color' ); // 'red'
-     *
-     * @param {String|Object} name The configuration name or an object from which take properties as
-     * configuration entries. Configuration names are case-sensitive.
-     * @param {*} value The configuration value. Used if a name is passed.
-     */
     set(name, value) {
         this._setToTarget(this._config, name, value);
     }
-    /**
-     * Does exactly the same as {@link #set} with one exception – passed configuration extends
-     * existing one, but does not overwrite already defined values.
-     *
-     * 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} name The configuration name or an object from which take properties as
-     * configuration entries. Configuration names are case-sensitive.
-     * @param {*} value The configuration value. Used if a name is passed.
-     */
     define(name, value) {
         const isDefine = true;
         this._setToTarget(this._config, name, value, isDefine);
@@ -93,22 +41,24 @@ export default class Config {
     /**
      * Gets the value for a configuration entry.
      *
-     *		config.get( 'name' );
+     * ```ts
+     * config.get( 'name' );
+     * ```
      *
      * Deep configurations can be retrieved by separating each part with a dot.
      *
-     *		config.get( 'toolbar.collapsed' );
+     * ```ts
+     * config.get( 'toolbar.collapsed' );
+     * ```
      *
-     * @param {String} name The configuration name. Configuration names are case-sensitive.
-     * @returns {*} The configuration value or `undefined` if the configuration entry was not found.
+     * @param name The configuration name. Configuration names are case-sensitive.
+     * @returns The configuration value or `undefined` if the configuration entry was not found.
      */
     get(name) {
         return this._getFromSource(this._config, name);
     }
     /**
      * Iterates over all top level configuration names.
-     *
-     * @returns {Iterable.<String>}
      */
     *names() {
         for (const name of Object.keys(this._config)) {
@@ -118,12 +68,11 @@ export default class Config {
     /**
      * Saves passed configuration to the specified target (nested object).
      *
-     * @private
-     * @param {Object} target Nested config object.
-     * @param {String|Object} name The configuration name or an object from which take properties as
+     * @param target Nested config object.
+     * @param name The configuration name or an object from which take properties as
      * configuration entries. Configuration names are case-sensitive.
-     * @param {*} value The configuration value. Used if a name is passed.
-     * @param {Boolean} [isDefine=false] Define if passed configuration should overwrite existing one.
+     * @param value The configuration value. Used if a name is passed.
+     * @param isDefine Define if passed configuration should overwrite existing one.
      */
     _setToTarget(target, name, value, isDefine = false) {
         // In case of an object, iterate through it and call `_setToTarget` again for each property.
@@ -164,10 +113,9 @@ export default class Config {
     /**
      * Get specified configuration from specified source (nested object).
      *
-     * @private
-     * @param {Object} source level of nested object.
-     * @param {String} name The configuration name. Configuration names are case-sensitive.
-     * @returns {*} The configuration value or `undefined` if the configuration entry was not found.
+     * @param source level of nested object.
+     * @param name The configuration name. Configuration names are case-sensitive.
+     * @returns The configuration value or `undefined` if the configuration entry was not found.
      */
     _getFromSource(source, name) {
         // The configuration name should be split into parts if it has dots. E.g. `resize.width` -> [`resize`, `width`].
@@ -189,10 +137,9 @@ export default class Config {
     /**
      * Iterates through passed object and calls {@link #_setToTarget} method with object key and value for each property.
      *
-     * @private
-     * @param {Object} target Nested config object.
-     * @param {Object} configuration Configuration data set
-     * @param {Boolean} [isDefine] Defines if passed configuration is default configuration or not.
+     * @param target Nested config object.
+     * @param configuration Configuration data set
+     * @param isDefine Defines if passed configuration is default configuration or not.
      */
     _setObjectToTarget(target, configuration, isDefine) {
         Object.keys(configuration).forEach(key => {
@@ -200,17 +147,16 @@ export default class Config {
         });
     }
 }
-// Clones configuration object or value.
-// @param {*} source Source configuration
-// @returns {*} Cloned configuration value.
+/**
+ * Clones configuration object or value.
+ */
 function cloneConfig(source) {
     return cloneDeepWith(source, leaveDOMReferences);
 }
-// A customized function for cloneDeepWith.
-// It will leave references to DOM Elements instead of cloning them.
-//
-// @param {*} value
-// @returns {Element|undefined}
+/**
+ * A customized function for cloneDeepWith.
+ * It will leave references to DOM Elements instead of cloning them.
+ */
 function leaveDOMReferences(value) {
     return isElement(value) ? value : undefined;
 }

package/src/count.js

@@ -8,10 +8,12 @@
 /**
  * Returns the number of items return by the iterator.
  *
- *		count( [ 1, 2, 3, 4, 5 ] ); // 5;
+ * ```ts
+ * count( [ 1, 2, 3, 4, 5 ] ); // 5;
+ * ```
  *
- * @param {Iterable.<*>} iterable Any iterable.
- * @returns {Number} Number of items returned by that iterable.
+ * @param iterable Any iterable.
+ * @returns Number of items returned by that iterable.
  */
 export default function count(iterable) {
     let count = 0;

package/src/diff.js

@@ -12,17 +12,19 @@ import fastDiff from './fastdiff';
  * Calculates the difference between two arrays or strings producing an array containing a list of changes
  * necessary to transform input into output.
  *
- *		diff( 'aba', 'acca' ); // [ 'equal', 'insert', 'insert', 'delete', 'equal' ]
+ * ```ts
+ * diff( 'aba', 'acca' ); // [ 'equal', 'insert', 'insert', 'delete', 'equal' ]
+ * ```
  *
  * This function is based on the "O(NP) Sequence Comparison Algorithm" by Sun Wu, Udi Manber, Gene Myers, Webb Miller.
  * Unfortunately, while it gives the most precise results, its to complex for longer strings/arrow (above 200 items).
  * Therefore, `diff()` automatically switches to {@link module:utils/fastdiff~fastDiff `fastDiff()`} when detecting
  * such a scenario. The return formats of both functions are identical.
  *
- * @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.
- * @returns {Array.<module:utils/diff~DiffResult>} Array of changes.
+ * @param a Input array or string.
+ * @param b Output array or string.
+ * @param cmp Optional function used to compare array values, by default === is used.
+ * @returns Array of changes.
  */
 export default function diff(a, b, cmp) {
     // Set the comparator function.

package/src/difftochanges.js

@@ -9,23 +9,26 @@
  * 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.
  *
- *		const input = Array.from( 'abc' );
- *		const output = Array.from( 'xaby' );
- *		const changes = diffToChanges( diff( input, output ), output );
+ * ```ts
+ * const input = Array.from( 'abc' );
+ * const output = Array.from( 'xaby' );
+ * const changes = diffToChanges( diff( input, output ), output );
  *
- *		changes.forEach( change => {
- *			if ( change.type == 'insert' ) {
- *				input.splice( change.index, 0, ...change.values );
- *			} else if ( change.type == 'delete' ) {
- *				input.splice( change.index, change.howMany );
- *			}
- *		} );
+ * changes.forEach( change => {
+ * 	if ( change.type == 'insert' ) {
+ * 		input.splice( change.index, 0, ...change.values );
+ * 	} else if ( change.type == 'delete' ) {
+ * 		input.splice( change.index, change.howMany );
+ * 	}
+ * } );
  *
- *		input.join( '' ) == output.join( '' ); // -> true
+ * input.join( '' ) == output.join( '' ); // -> true
+ * ```
  *
- * @param {Array.<module:utils/diff~DiffResult>} 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.<module:utils/difftochanges~Change>} Set of changes (insert or delete) which need to be applied to the input
+ * @typeParam T The type of output array element.
+ * @param diff Result of {@link module:utils/diff~diff}.
+ * @param output The string or array which was passed as diff's output.
+ * @returns Set of changes (insert or delete) which need to be applied to the input
  * in order to transform it into the output.
  */
 export default function diffToChanges(diff, output) {

package/src/dom/createelement.js

@@ -10,17 +10,19 @@ import { isString } from 'lodash-es';
 /**
  * Creates element with attributes and children.
  *
- *		createElement( document, 'p' ); // <p>
- *		createElement( document, 'p', { class: 'foo' } ); // <p class="foo">
- *		createElement( document, 'p', null, 'foo' ); // <p>foo</p>
- *		createElement( document, 'p', null, [ 'foo', createElement( document, 'img' ) ] ); // <p>foo<img></p>
+ * ```ts
+ * createElement( document, 'p' ); // <p>
+ * createElement( document, 'p', { class: 'foo' } ); // <p class="foo">
+ * createElement( document, 'p', null, 'foo' ); // <p>foo</p>
+ * createElement( document, 'p', null, [ 'foo', createElement( document, 'img' ) ] ); // <p>foo<img></p>
+ * ```
  *
- * @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.
- * @param {Node|String|Iterable.<Node|String>} [children] Child or any iterable of children. Strings will be automatically turned
+ * @param doc Document used to create element.
+ * @param name Name of the element.
+ * @param attributes Object keys will become attributes keys and object values will became attributes values.
+ * @param children Child or any iterable of children. Strings will be automatically turned
  * into Text nodes.
- * @returns {Element} Created element.
+ * @returns Created element.
  */
 export default function createElement(doc, name, attributes = {}, children = []) {
     const namespace = attributes && attributes.xmlns;

package/src/dom/emittermixin.js

@@ -2,37 +2,18 @@
  * @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
  */
-/* eslint-disable new-cap */
 /**
  * @module utils/dom/emittermixin
  */
-import { _getEmitterListenedTo, _setEmitterId, Emitter as BaseEmitter } from '../emittermixin';
+import EmitterMixin, { _getEmitterListenedTo, _setEmitterId } from '../emittermixin';
 import uid from '../uid';
 import isNode from './isnode';
 import isWindow from './iswindow';
-/**
- * Mixin that injects the DOM events API into its host. It provides the API
- * compatible with {@link module:utils/emittermixin~EmitterMixin}.
- *
- * 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';
- *		import DomEmitterMixin from '../utils/dom/emittermixin.js';
- *		import { Emitter } from '../utils/emittermixin.js';
- *
- *		class SomeView extends DomEmitterMixin( Emitter ) {}
- *
- *		const view = new SomeView();
- *		view.listenTo( domElement, ( evt, domEvt ) => {
- *			console.log( evt, domEvt );
- *		} );
- *
- * @mixin EmitterMixin
- * @mixes module:utils/emittermixin~EmitterMixin
- * @implements module:utils/dom/emittermixin~Emitter
- */
+const defaultEmitterClass = DomEmitterMixin(EmitterMixin());
 export default function DomEmitterMixin(base) {
+    if (!base) {
+        return defaultEmitterClass;
+    }
     class Mixin extends base {
         listenTo(emitter, event, callback, options = {}) {
             // Check if emitter is an instance of DOM Node. If so, use corresponding ProxyEmitter (or create one if not existing).
@@ -46,7 +27,7 @@ export default function DomEmitterMixin(base) {
             }
             else {
                 // Execute parent class method with Emitter (or ProxyEmitter) instance.
-                BaseEmitter.prototype.listenTo.call(this, emitter, event, callback, options);
+                super.listenTo(emitter, event, callback, options);
             }
         }
         stopListening(emitter, event, callback) {
@@ -59,20 +40,19 @@ export default function DomEmitterMixin(base) {
             }
             else {
                 // Execute parent class method with Emitter (or ProxyEmitter) instance.
-                BaseEmitter.prototype.stopListening.call(this, emitter, event, callback);
+                super.stopListening(emitter, event, callback);
             }
         }
         /**
          * Retrieves ProxyEmitter instance for given DOM Node residing in this Host and given options.
          *
-         * @private
-         * @param {Node|Window} node DOM Node of the ProxyEmitter.
-         * @param {Object} [options] Additional options.
-         * @param {Boolean} [options.useCapture=false] Indicates that events of this type will be dispatched to the registered
+         * @param node DOM Node of the ProxyEmitter.
+         * @param options Additional options.
+         * @param options.useCapture 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.
-         * @param {Boolean} [options.usePassive=false] Indicates that the function specified by listener will never call preventDefault()
+         * @param options.usePassive Indicates that the function specified by listener will never call preventDefault()
          * and prevents blocking browser's main thread by this event handler.
-         * @returns {module:utils/dom/emittermixin~ProxyEmitter|null} ProxyEmitter instance bound to the DOM Node.
+         * @returns ProxyEmitter instance bound to the DOM Node.
          */
         _getProxyEmitter(node, options) {
             return _getEmitterListenedTo(this, getProxyEmitterId(node, options));
@@ -80,9 +60,7 @@ export default function DomEmitterMixin(base) {
         /**
          * Retrieves all the ProxyEmitter instances for given DOM Node residing in this Host.
          *
-         * @private
-         * @param {Node|Window} node DOM Node of the ProxyEmitter.
-         * @returns {Array.<module:utils/dom/emittermixin~ProxyEmitter>}
+         * @param node DOM Node of the ProxyEmitter.
          */
         _getAllProxyEmitters(node) {
             return [
@@ -95,7 +73,6 @@ export default function DomEmitterMixin(base) {
     }
     return Mixin;
 }
-export const Emitter = DomEmitterMixin(BaseEmitter);
 // Backward compatibility with `mix`
 ([
     '_getProxyEmitter', '_getAllProxyEmitters',
@@ -103,11 +80,11 @@ export const Emitter = DomEmitterMixin(BaseEmitter);
     'stopListening', 'fire', 'delegate', 'stopDelegating',
     '_addEventListener', '_removeEventListener'
 ]).forEach(key => {
-    DomEmitterMixin[key] = Emitter.prototype[key];
+    DomEmitterMixin[key] = defaultEmitterClass.prototype[key];
 });
 /**
  * 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 module:utils/emittermixin~EmitterMixin#on}.
+ * and any Host listening to them. It is backwards compatible with {@link module:utils/emittermixin~Emitter#on}.
  * There is a separate instance for each combination of modes (useCapture & usePassive). The mode is concatenated with
  * UID stored in HTMLElement to give each instance unique identifier.
  *
@@ -132,18 +109,14 @@ export const Emitter = DomEmitterMixin(BaseEmitter);
  *                    |                                         |                  click (DOM Event)
  *                    +-----------------------------------------+
  *                                fire( click, DOM Event )
- *
- * @mixes module:utils/emittermixin~EmitterMixin
- * @implements module:utils/dom/emittermixin~Emitter
- * @private
  */
-class ProxyEmitter extends BaseEmitter {
+class ProxyEmitter extends EmitterMixin() {
     /**
-     * @param {Node|Window} node DOM Node that fires events.
-     * @param {Object} [options] Additional options.
-     * @param {Boolean} [options.useCapture=false] Indicates that events of this type will be dispatched to the registered
+     * @param node DOM Node that fires events.
+     * @param options Additional options.
+     * @param options.useCapture 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.
-     * @param {Boolean} [options.usePassive=false] Indicates that the function specified by listener will never call preventDefault()
+     * @param options.usePassive Indicates that the function specified by listener will never call preventDefault()
      * and prevents blocking browser's main thread by this event handler.
      */
     constructor(node, options) {
@@ -162,10 +135,9 @@ class ProxyEmitter extends BaseEmitter {
      * a corresponding Emitter event will also fire with DOM Event object as an argument.
      *
      * **Note**: This is automatically called by the
-     * {@link module:utils/emittermixin~EmitterMixin#listenTo `EmitterMixin#listenTo()`}.
+     * {@link module:utils/emittermixin~Emitter#listenTo `Emitter#listenTo()`}.
      *
-     * @method module:utils/dom/emittermixin~ProxyEmitter#attach
-     * @param {String} event The name of the event.
+     * @param event The name of the event.
      */
     attach(event) {
         // If the DOM Listener for given event already exist it is pointless
@@ -187,10 +159,9 @@ class ProxyEmitter extends BaseEmitter {
      * Stops executing the callback on the given event.
      *
      * **Note**: This is automatically called by the
-     * {@link module:utils/emittermixin~EmitterMixin#stopListening `EmitterMixin#stopListening()`}.
+     * {@link module:utils/emittermixin~Emitter#stopListening `Emitter#stopListening()`}.
      *
-     * @method module:utils/dom/emittermixin~ProxyEmitter#detach
-     * @param {String} event The name of the event.
+     * @param event The name of the event.
      */
     detach(event) {
         let events;
@@ -204,29 +175,24 @@ class ProxyEmitter extends BaseEmitter {
     /**
      * Adds callback to emitter for given event.
      *
-     * @protected
-     * @method module:utils/dom/emittermixin~ProxyEmitter#_addEventListener
-     * @param {String} event The name of the event.
-     * @param {Function} callback The function to be called on event.
-     * @param {Object} [options={}] Additional options.
-     * @param {module:utils/priorities~PriorityString} [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.
+     * @internal
+     * @param event The name of the event.
+     * @param callback The function to be called on event.
+     * @param options Additional options.
      */
     _addEventListener(event, callback, options) {
         this.attach(event);
-        BaseEmitter.prototype._addEventListener.call(this, event, callback, options);
+        EmitterMixin().prototype._addEventListener.call(this, event, callback, options);
     }
     /**
      * Removes callback from emitter for given event.
      *
-     * @protected
-     * @method module:utils/dom/emittermixin~ProxyEmitter#_removeEventListener
-     * @param {String} event The name of the event.
-     * @param {Function} callback The function to stop being called.
+     * @internal
+     * @param event The name of the event.
+     * @param callback The function to stop being called.
      */
     _removeEventListener(event, callback) {
-        BaseEmitter.prototype._removeEventListener.call(this, event, callback);
+        EmitterMixin().prototype._removeEventListener.call(this, event, callback);
         this.detach(event);
     }
     /**
@@ -234,10 +200,8 @@ class ProxyEmitter extends BaseEmitter {
      * is fired it will fire corresponding event on this ProxyEmitter.
      * Note: A native DOM Event is passed as an argument.
      *
-     * @private
-     * @method module:utils/dom/emittermixin~ProxyEmitter#_createDomListener
-     * @param {String} event The name of the event.
-     * @returns {Function} The DOM listener callback.
+     * @param event The name of the event.
+     * @returns The DOM listener callback.
      */
     _createDomListener(event) {
         const domListener = (domEvt) => {
@@ -253,22 +217,17 @@ class ProxyEmitter extends BaseEmitter {
         return domListener;
     }
 }
-// Gets an unique DOM Node identifier. The identifier will be set if not defined.
-//
-// @private
-// @param {Node} node
-// @returns {String} UID for given DOM Node.
+/**
+ * Gets an unique DOM Node identifier. The identifier will be set if not defined.
+ *
+ * @returns UID for given DOM Node.
+ */
 function getNodeUID(node) {
     return node['data-ck-expando'] || (node['data-ck-expando'] = uid());
 }
-// Gets id of the ProxyEmitter for the given node.
-//
-// Combines DOM Node identifier and additional options.
-//
-// @private
-// @param {Node} node
-// @param {Object} options Additional options.
-// @returns {String} ProxyEmitter id.
+/**
+ * Gets id of the ProxyEmitter for the given node.
+ */
 function getProxyEmitterId(node, options) {
     let id = getNodeUID(node);
     for (const option of Object.keys(options).sort()) {

package/src/dom/getancestors.js

@@ -12,8 +12,8 @@
  * appended to a `Document`, that `Document` will not be returned (algorithms operating on DOM tree care for `Document#documentElement`
  * at most, which will be returned).
  *
- * @param {Node} node DOM node.
- * @returns {Array.<Node|DocumentFragment>} Array of given `node` parents.
+ * @param node DOM node.
+ * @returns Array of given `node` parents.
  */
 export default function getAncestors(node) {
     const nodes = [];

package/src/dom/getborderwidths.js

@@ -8,8 +8,8 @@
 /**
  * Returns an object containing CSS border widths of a specified HTML element.
  *
- * @param {HTMLElement} element An element which has CSS borders.
- * @returns {module:utils/dom/getborderwidths~BorderWidths} An object containing `top`, `left`, `right` and `bottom` properties
+ * @param element An element which has CSS borders.
+ * @returns An object containing `top`, `left`, `right` and `bottom` properties
  * with numerical values of the `border-[top,left,right,bottom]-width` CSS styles.
  */
 export default function getBorderWidths(element) {

package/src/dom/getcommonancestor.js

@@ -9,9 +9,9 @@ import getAncestors from './getancestors';
 /**
  * Searches and returns the lowest common ancestor of two given nodes.
  *
- * @param {Node} nodeA First node.
- * @param {Node} nodeB Second node.
- * @returns {Node|DocumentFragment|Document|null} Lowest common ancestor of both nodes or `null` if nodes do not have a common ancestor.
+ * @param nodeA First node.
+ * @param nodeB Second node.
+ * @returns Lowest common ancestor of both nodes or `null` if nodes do not have a common ancestor.
  */
 export default function getCommonAncestor(nodeA, nodeB) {
     const ancestorsA = getAncestors(nodeA);

package/src/dom/getdatafromelement.js

@@ -9,8 +9,8 @@
 /**
  * Gets data from a given source element.
  *
- * @param {HTMLElement} el The element from which the data will be retrieved.
- * @returns {String} The data string.
+ * @param el The element from which the data will be retrieved.
+ * @returns The data string.
  */
 export default function getDataFromElement(el) {
     if (el instanceof HTMLTextAreaElement) {

package/src/dom/getpositionedancestor.js

@@ -9,8 +9,7 @@ import global from './global';
 /**
  * For a given element, returns the nearest ancestor element which CSS position is not "static".
  *
- * @param {HTMLElement} [element] The native DOM element to be checked.
- * @returns {HTMLElement|null}
+ * @param element The native DOM element to be checked.
  */
 export default function getPositionedAncestor(element) {
     if (!element || !element.parentNode) {