@ckeditor/ckeditor5-engine 35.3.2 → 36.0.0

package/src/model/position.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 /**
@@ -7,8 +7,7 @@
  */
 import TypeCheckable from './typecheckable';
 import TreeWalker from './treewalker';
-import compareArrays from '@ckeditor/ckeditor5-utils/src/comparearrays';
-import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+import { CKEditorError, compareArrays } from '@ckeditor/ckeditor5-utils';
 // To check if component is loaded more than once.
 import '@ckeditor/ckeditor5-utils/src/version';
 /**
@@ -42,10 +41,9 @@ export default class Position extends TypeCheckable {
     /**
      * Creates a position.
      *
-     * @param {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment} root Root of the position.
-     * @param {Array.<Number>} path Position path. See {@link module:engine/model/position~Position#path}.
-     * @param {module:engine/model/position~PositionStickiness} [stickiness='toNone'] Position stickiness.
-     * See {@link module:engine/model/position~PositionStickiness}.
+     * @param root Root of the position.
+     * @param path Position path. See {@link module:engine/model/position~Position#path}.
+     * @param stickiness Position stickiness. See {@link module:engine/model/position~PositionStickiness}.
      */
     constructor(root, path, stickiness = 'toNone') {
         super();
@@ -76,50 +74,8 @@ export default class Position extends TypeCheckable {
             path = [...root.getPath(), ...path];
             root = root.root;
         }
-        /**
-         * Root of the position path.
-         *
-         * @readonly
-         * @member {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment}
-         * module:engine/model/position~Position#root
-         */
         this.root = root;
-        /**
-         * Position of the node in the tree. **Path contains offsets, not indexes.**
-         *
-         * Position can be placed before, after or in a {@link module:engine/model/node~Node node} if that node has
-         * {@link module:engine/model/node~Node#offsetSize} greater than `1`. Items in position path are
-         * {@link module:engine/model/node~Node#startOffset starting offsets} of position ancestors, starting from direct root children,
-         * down to the position offset in it's parent.
-         *
-         *		 ROOT
-         *		  |- P            before: [ 0 ]         after: [ 1 ]
-         *		  |- UL           before: [ 1 ]         after: [ 2 ]
-         *		     |- LI        before: [ 1, 0 ]      after: [ 1, 1 ]
-         *		     |  |- foo    before: [ 1, 0, 0 ]   after: [ 1, 0, 3 ]
-         *		     |- LI        before: [ 1, 1 ]      after: [ 1, 2 ]
-         *		        |- bar    before: [ 1, 1, 0 ]   after: [ 1, 1, 3 ]
-         *
-         * `foo` and `bar` are representing {@link module:engine/model/text~Text text nodes}. Since text nodes has offset size
-         * greater than `1` you can place position offset between their start and end:
-         *
-         *		 ROOT
-         *		  |- P
-         *		  |- UL
-         *		     |- LI
-         *		     |  |- f^o|o  ^ has path: [ 1, 0, 1 ]   | has path: [ 1, 0, 2 ]
-         *		     |- LI
-         *		        |- b^a|r  ^ has path: [ 1, 1, 1 ]   | has path: [ 1, 1, 2 ]
-         *
-         * @readonly
-         * @member {Array.<Number>} module:engine/model/position~Position#path
-         */
         this.path = path;
-        /**
-         * Position stickiness. See {@link module:engine/model/position~PositionStickiness}.
-         *
-         * @member {module:engine/model/position~PositionStickiness} module:engine/model/position~Position#stickiness
-         */
         this.stickiness = stickiness;
     }
     /**
@@ -142,9 +98,6 @@ export default class Position extends TypeCheckable {
      * leads to a non-existing element, `parent` property will throw error.
      *
      * Also it is a good idea to cache `parent` property if it is used frequently in an algorithm (i.e. in a long loop).
-     *
-     * @readonly
-     * @type {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment}
      */
     get parent() {
         let parent = this.root;
@@ -164,7 +117,7 @@ export default class Position extends TypeCheckable {
                  * the {@glink framework/guides/architecture/editing-engine#indexes-and-offsets Editing engine architecture guide}.
                  *
                  * @error model-position-path-incorrect
-                 * @param {module:engine/model/position~Position} position The incorrect position.
+                 * @param position The incorrect position.
                  */
                 throw new CKEditorError('model-position-path-incorrect', this, { position: this });
             }
@@ -178,9 +131,6 @@ export default class Position extends TypeCheckable {
      * Position {@link module:engine/model/position~Position#offset offset} converted to an index in position's parent node. It is
      * equal to the {@link module:engine/model/node~Node#index index} of a node after this position. If position is placed
      * in text node, position index is equal to the index of that text node.
-     *
-     * @readonly
-     * @type {Number}
      */
     get index() {
         return this.parent.offsetToIndex(this.offset);
@@ -188,18 +138,12 @@ export default class Position extends TypeCheckable {
     /**
      * Returns {@link module:engine/model/text~Text text node} instance in which this position is placed or `null` if this
      * position is not in a text node.
-     *
-     * @readonly
-     * @type {module:engine/model/text~Text|null}
      */
     get textNode() {
         return getTextNodeAtPosition(this, this.parent);
     }
     /**
      * Node directly after this position or `null` if this position is in text node.
-     *
-     * @readonly
-     * @type {module:engine/model/node~Node|null}
      */
     get nodeAfter() {
         // Cache the parent and reuse for performance reasons. See #6579 and #6582.
@@ -208,9 +152,6 @@ export default class Position extends TypeCheckable {
     }
     /**
      * Node directly before this position or `null` if this position is in text node.
-     *
-     * @readonly
-     * @type {module:engine/model/node~Node|null}
      */
     get nodeBefore() {
         // Cache the parent and reuse for performance reasons. See #6579 and #6582.
@@ -219,18 +160,12 @@ export default class Position extends TypeCheckable {
     }
     /**
      * Is `true` if position is at the beginning of its {@link module:engine/model/position~Position#parent parent}, `false` otherwise.
-     *
-     * @readonly
-     * @type {Boolean}
      */
     get isAtStart() {
         return this.offset === 0;
     }
     /**
      * Is `true` if position is at the end of its {@link module:engine/model/position~Position#parent parent}, `false` otherwise.
-     *
-     * @readonly
-     * @type {Boolean}
      */
     get isAtEnd() {
         return this.offset == this.parent.maxOffset;
@@ -239,9 +174,6 @@ export default class Position extends TypeCheckable {
      * Checks whether this position is before or after given position.
      *
      * This method is safe to use it on non-existing positions (for example during operational transformation).
-     *
-     * @param {module:engine/model/position~Position} otherPosition Position to compare with.
-     * @returns {module:engine/model/position~PositionRelation}
      */
     compareWith(otherPosition) {
         if (this.root != otherPosition.root) {
@@ -265,20 +197,22 @@ export default class Position extends TypeCheckable {
      *
      * For example:
      *
-     * 		getLastMatchingPosition( value => value.type == 'text' );
-     * 		// <paragraph>[]foo</paragraph> -> <paragraph>foo[]</paragraph>
+     * ```ts
+     * getLastMatchingPosition( value => value.type == 'text' );
+     * // <paragraph>[]foo</paragraph> -> <paragraph>foo[]</paragraph>
      *
-     * 		getLastMatchingPosition( value => value.type == 'text', { direction: 'backward' } );
-     * 		// <paragraph>foo[]</paragraph> -> <paragraph>[]foo</paragraph>
+     * getLastMatchingPosition( value => value.type == 'text', { direction: 'backward' } );
+     * // <paragraph>foo[]</paragraph> -> <paragraph>[]foo</paragraph>
      *
-     * 		getLastMatchingPosition( value => false );
-     * 		// Do not move the position.
+     * getLastMatchingPosition( value => false );
+     * // Do not move the position.
+     * ```
      *
-     * @param {Function} skip Callback function. Gets {@link module:engine/model/treewalker~TreeWalkerValue} and should
+     * @param skip Callback function. Gets {@link module:engine/model/treewalker~TreeWalkerValue} and should
      * return `true` if the value should be skipped or `false` if not.
-     * @param {Object} options Object with configuration options. See {@link module:engine/model/treewalker~TreeWalker}.
+     * @param options Object with configuration options. See {@link module:engine/model/treewalker~TreeWalker}.
      *
-     * @returns {module:engine/model/position~Position} The position after the last item which matches the `skip` callback test.
+     * @returns The position after the last item which matches the `skip` callback test.
      */
     getLastMatchingPosition(skip, options = {}) {
         options.startPosition = this;
@@ -292,7 +226,7 @@ export default class Position extends TypeCheckable {
      *
      * This method is safe to use it on non-existing positions (for example during operational transformation).
      *
-     * @returns {Array.<Number>} Path to the parent.
+     * @returns Path to the parent.
      */
     getParentPath() {
         return this.path.slice(0, -1);
@@ -300,7 +234,7 @@ export default class Position extends TypeCheckable {
     /**
      * Returns ancestors array of this position, that is this position's parent and its ancestors.
      *
-     * @returns {Array.<module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment>} Array with ancestors.
+     * @returns Array with ancestors.
      */
     getAncestors() {
         const parent = this.parent;
@@ -314,8 +248,7 @@ export default class Position extends TypeCheckable {
     /**
      * Returns the parent element of the given name. Returns null if the position is not inside the desired parent.
      *
-     * @param {String} parentName The name of the parent element to find.
-     * @returns {module:engine/model/element~Element|null}
+     * @param parentName The name of the parent element to find.
      */
     findAncestor(parentName) {
         const parent = this.parent;
@@ -330,8 +263,8 @@ export default class Position extends TypeCheckable {
      *
      * This method is safe to use it on non-existing positions (for example during operational transformation).
      *
-     * @param {module:engine/model/position~Position} position The second position.
-     * @returns {Array.<Number>} The common path.
+     * @param position The second position.
+     * @returns The common path.
      */
     getCommonPath(position) {
         if (this.root != position.root) {
@@ -347,8 +280,7 @@ export default class Position extends TypeCheckable {
      * Returns an {@link module:engine/model/element~Element} or {@link module:engine/model/documentfragment~DocumentFragment}
      * which is a common ancestor of both positions. The {@link #root roots} of these two positions must be identical.
      *
-     * @param {module:engine/model/position~Position} position The second position.
-     * @returns {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment|null}
+     * @param position The second position.
      */
     getCommonAncestor(position) {
         const ancestorsA = this.getAncestors();
@@ -365,8 +297,8 @@ export default class Position extends TypeCheckable {
      *
      * This method is safe to use it on non-existing positions (for example during operational transformation).
      *
-     * @param {Number} shift Offset shift. Can be a negative value.
-     * @returns {module:engine/model/position~Position} Shifted position.
+     * @param shift Offset shift. Can be a negative value.
+     * @returns Shifted position.
      */
     getShiftedBy(shift) {
         const shifted = this.clone();
@@ -380,8 +312,8 @@ export default class Position extends TypeCheckable {
      * This method is safe to use it on non-existing positions (for example during operational transformation).
      *
      * @see module:engine/model/position~Position#isBefore
-     * @param {module:engine/model/position~Position} otherPosition Position to compare with.
-     * @returns {Boolean} True if this position is after given position.
+     * @param  otherPosition Position to compare with.
+     * @returns True if this position is after given position.
      */
     isAfter(otherPosition) {
         return this.compareWith(otherPosition) == 'after';
@@ -394,30 +326,36 @@ export default class Position extends TypeCheckable {
      * `a.isAfter( b ) || a.isEqual( b )` or `!a.isBefore( p ) && a.root == b.root` in most scenarios. If your
      * condition uses multiple `isAfter` and `isBefore` checks, build them so they do not use negated values, i.e.:
      *
-     *		if ( a.isBefore( b ) && c.isAfter( d ) ) {
-     *			// do A.
-     *		} else {
-     *			// do B.
-     *		}
+     * ```ts
+     * if ( a.isBefore( b ) && c.isAfter( d ) ) {
+     * 	// do A.
+     * } else {
+     * 	// do B.
+     * }
+     * ```
      *
      * or, if you have only one if-branch:
      *
-     *		if ( !( a.isBefore( b ) && c.isAfter( d ) ) {
-     *			// do B.
-     *		}
+     * ```ts
+     * if ( !( a.isBefore( b ) && c.isAfter( d ) ) {
+     * 	// do B.
+     * }
+     * ```
      *
      * rather than:
      *
-     *		if ( !a.isBefore( b ) || && !c.isAfter( d ) ) {
-     *			// do B.
-     *		} else {
-     *			// do A.
-     *		}
+     * ```ts
+     * if ( !a.isBefore( b ) || && !c.isAfter( d ) ) {
+     * 	// do B.
+     * } else {
+     * 	// do A.
+     * }
+     * ```
      *
      * This method is safe to use it on non-existing positions (for example during operational transformation).
      *
-     * @param {module:engine/model/position~Position} otherPosition Position to compare with.
-     * @returns {Boolean} True if this position is before given position.
+     * @param otherPosition Position to compare with.
+     * @returns True if this position is before given position.
      */
     isBefore(otherPosition) {
         return this.compareWith(otherPosition) == 'before';
@@ -427,8 +365,8 @@ export default class Position extends TypeCheckable {
      *
      * This method is safe to use it on non-existing positions (for example during operational transformation).
      *
-     * @param {module:engine/model/position~Position} otherPosition Position to compare with.
-     * @returns {Boolean} True if positions are same.
+     * @param otherPosition Position to compare with.
+     * @returns True if positions are same.
      */
     isEqual(otherPosition) {
         return this.compareWith(otherPosition) == 'same';
@@ -438,8 +376,8 @@ export default class Position extends TypeCheckable {
      * or empty nodes in a range between them. Technically, those positions are not equal but in many cases
      * they are very similar or even indistinguishable.
      *
-     * @param {module:engine/model/position~Position} otherPosition Position to compare with.
-     * @returns {Boolean} True if positions touch.
+     * @param otherPosition Position to compare with.
+     * @returns True if positions touch.
      */
     isTouching(otherPosition) {
         if (this.root !== otherPosition.root) {
@@ -488,8 +426,8 @@ export default class Position extends TypeCheckable {
      *
      * This method is safe to use it on non-existing positions (for example during operational transformation).
      *
-     * @param {module:engine/model/position~Position} position Position to compare with.
-     * @returns {Boolean} `true` if positions have the same parent, `false` otherwise.
+     * @param position Position to compare with.
+     * @returns `true` if positions have the same parent, `false` otherwise.
      */
     hasSameParentAs(position) {
         if (this.root !== position.root) {
@@ -509,8 +447,8 @@ export default class Position extends TypeCheckable {
      *
      * This method is safe to use it on non-existing positions (for example during operational transformation).
      *
-     * @param {module:engine/model/operation/operation~Operation} operation Operation to transform by.
-     * @returns {module:engine/model/position~Position} Transformed position.
+     * @param operation Operation to transform by.
+     * @returns Transformed position.
      */
     getTransformedByOperation(operation) {
         let result;
@@ -539,9 +477,6 @@ export default class Position extends TypeCheckable {
      * Returns a copy of this position transformed by an insert operation.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/operation/insertoperation~InsertOperation} operation
-     * @returns {module:engine/model/position~Position}
      */
     _getTransformedByInsertOperation(operation) {
         return this._getTransformedByInsertion(operation.position, operation.howMany);
@@ -550,9 +485,6 @@ export default class Position extends TypeCheckable {
      * Returns a copy of this position transformed by a move operation.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/operation/moveoperation~MoveOperation} operation
-     * @returns {module:engine/model/position~Position}
      */
     _getTransformedByMoveOperation(operation) {
         return this._getTransformedByMove(operation.sourcePosition, operation.targetPosition, operation.howMany);
@@ -561,9 +493,6 @@ export default class Position extends TypeCheckable {
      * Returns a copy of this position transformed by a split operation.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/operation/splitoperation~SplitOperation} operation
-     * @returns {module:engine/model/position~Position}
      */
     _getTransformedBySplitOperation(operation) {
         const movedRange = operation.movedRange;
@@ -585,9 +514,6 @@ export default class Position extends TypeCheckable {
      * Returns a copy of this position transformed by merge operation.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/operation/mergeoperation~MergeOperation} operation
-     * @returns {module:engine/model/position~Position}
      */
     _getTransformedByMergeOperation(operation) {
         const movedRange = operation.movedRange;
@@ -613,10 +539,9 @@ export default class Position extends TypeCheckable {
      * It may happen that this position is in a removed node. If that is the case, `null` is returned instead.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/position~Position} deletePosition Position before the first removed node.
-     * @param {Number} howMany How many nodes are removed.
-     * @returns {module:engine/model/position~Position|null} Transformed position or `null`.
+     * @param deletePosition Position before the first removed node.
+     * @param howMany How many nodes are removed.
+     * @returns Transformed position or `null`.
      */
     _getTransformedByDeletion(deletePosition, howMany) {
         const transformed = Position._createAt(this);
@@ -660,10 +585,9 @@ export default class Position extends TypeCheckable {
      * Returns a copy of this position that is updated by inserting `howMany` nodes at `insertPosition`.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/position~Position} insertPosition Position where nodes are inserted.
-     * @param {Number} howMany How many nodes are inserted.
-     * @returns {module:engine/model/position~Position} Transformed position.
+     * @param insertPosition Position where nodes are inserted.
+     * @param howMany How many nodes are inserted.
+     * @returns Transformed position.
      */
     _getTransformedByInsertion(insertPosition, howMany) {
         const transformed = Position._createAt(this);
@@ -694,11 +618,10 @@ export default class Position extends TypeCheckable {
      * Returns a copy of this position that is updated by moving `howMany` nodes from `sourcePosition` to `targetPosition`.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/position~Position} sourcePosition Position before the first element to move.
-     * @param {module:engine/model/position~Position} targetPosition Position where moved elements will be inserted.
-     * @param {Number} howMany How many consecutive nodes to move, starting from `sourcePosition`.
-     * @returns {module:engine/model/position~Position} Transformed position.
+     * @param sourcePosition Position before the first element to move.
+     * @param targetPosition Position where moved elements will be inserted.
+     * @param howMany How many consecutive nodes to move, starting from `sourcePosition`.
+     * @returns Transformed position.
      */
     _getTransformedByMove(sourcePosition, targetPosition, howMany) {
         // Update target position, as it could be affected by nodes removal.
@@ -732,10 +655,12 @@ export default class Position extends TypeCheckable {
      *
      * Example:
      *
-     *		let original = model.createPositionFromPath( root, [ 2, 3, 1 ] );
-     *		let source = model.createPositionFromPath( root, [ 2, 2 ] );
-     *		let target = model.createPositionFromPath( otherRoot, [ 1, 1, 3 ] );
-     *		original._getCombined( source, target ); // path is [ 1, 1, 4, 1 ], root is `otherRoot`
+     * ```ts
+     * let original = model.createPositionFromPath( root, [ 2, 3, 1 ] );
+     * let source = model.createPositionFromPath( root, [ 2, 2 ] );
+     * let target = model.createPositionFromPath( otherRoot, [ 1, 1, 3 ] );
+     * original._getCombined( source, target ); // path is [ 1, 1, 4, 1 ], root is `otherRoot`
+     * ```
      *
      * Explanation:
      *
@@ -747,10 +672,9 @@ export default class Position extends TypeCheckable {
      * Finally, the transformed position will point to `[ 1, 1, 4, 1 ]`.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/position~Position} source Beginning of the moved range.
-     * @param {module:engine/model/position~Position} target Position where the range is moved.
-     * @returns {module:engine/model/position~Position} Combined position.
+     * @param source Beginning of the moved range.
+     * @param target Position where the range is moved.
+     * @returns Combined position.
      */
     _getCombined(source, target) {
         const i = source.path.length - 1;
@@ -777,8 +701,6 @@ export default class Position extends TypeCheckable {
     }
     /**
      * Returns a new position that is equal to current position.
-     *
-     * @returns {module:engine/model/position~Position}
      */
     clone() {
         return new this.constructor(this.root, this.path, this.stickiness);
@@ -796,13 +718,9 @@ export default class Position extends TypeCheckable {
      * * {@link module:engine/model/position~Position._createBefore},
      * * {@link module:engine/model/position~Position._createAfter}.
      *
-     * @param {module:engine/model/item~Item|module:engine/model/position~Position} itemOrPosition
-     * @param {Number|'end'|'before'|'after'} [offset] Offset or one of the flags. Used only when the
-     * first parameter is a {@link module:engine/model/item~Item model item}.
-     * @param {module:engine/model/position~PositionStickiness} [stickiness='toNone'] Position stickiness. Used only when the
-     * first parameter is a {@link module:engine/model/item~Item model item}.
-     * @protected
      * @internal
+     * @param offset Offset or one of the flags. Used only when the first parameter is a {@link module:engine/model/item~Item model item}.
+     * @param stickiness Position stickiness. Used only when the first parameter is a {@link module:engine/model/item~Item model item}.
      */
     static _createAt(itemOrPosition, offset, stickiness = 'toNone') {
         if (itemOrPosition instanceof Position) {
@@ -844,11 +762,9 @@ export default class Position extends TypeCheckable {
     /**
      * Creates a new position, after given {@link module:engine/model/item~Item model item}.
      *
-     * @param {module:engine/model/item~Item} item Item after which the position should be placed.
-     * @param {module:engine/model/position~PositionStickiness} [stickiness='toNone'] Position stickiness.
-     * @returns {module:engine/model/position~Position}
-     * @protected
      * @internal
+     * @param item Item after which the position should be placed.
+     * @param stickiness Position stickiness.
      */
     static _createAfter(item, stickiness) {
         if (!item.parent) {
@@ -856,7 +772,7 @@ export default class Position extends TypeCheckable {
              * You can not make a position after a root element.
              *
              * @error model-position-after-root
-             * @param {module:engine/model/item~Item} root
+             * @param root
              */
             throw new CKEditorError('model-position-after-root', [this, item], { root: item });
         }
@@ -865,11 +781,9 @@ export default class Position extends TypeCheckable {
     /**
      * Creates a new position, before the given {@link module:engine/model/item~Item model item}.
      *
-     * @param {module:engine/model/item~Item} item Item before which the position should be placed.
-     * @param {module:engine/model/position~PositionStickiness} [stickiness='toNone'] Position stickiness.
-     * @returns {module:engine/model/position~Position}
-     * @protected
      * @internal
+     * @param item Item before which the position should be placed.
+     * @param stickiness Position stickiness.
      */
     static _createBefore(item, stickiness) {
         if (!item.parent) {
@@ -877,7 +791,7 @@ export default class Position extends TypeCheckable {
              * You can not make a position before a root element.
              *
              * @error model-position-before-root
-             * @param {module:engine/model/item~Item} root
+             * @param root
              */
             throw new CKEditorError('model-position-before-root', item, { root: item });
         }
@@ -886,9 +800,9 @@ export default class Position extends TypeCheckable {
     /**
      * Creates a `Position` instance from given plain object (i.e. parsed JSON string).
      *
-     * @param {Object} json Plain object to be converted to `Position`.
-     * @param {module:engine/model/document~Document} doc Document object that will be position owner.
-     * @returns {module:engine/model/position~Position} `Position` instance created using given plain object.
+     * @param json Plain object to be converted to `Position`.
+     * @param doc Document object that will be position owner.
+     * @returns `Position` instance created using given plain object.
      */
     static fromJSON(json, doc) {
         if (json.root === '$graveyard') {
@@ -901,27 +815,15 @@ export default class Position extends TypeCheckable {
              * Cannot create position for document. Root with specified name does not exist.
              *
              * @error model-position-fromjson-no-root
-             * @param {String} rootName
+             * @param rootName
              */
             throw new CKEditorError('model-position-fromjson-no-root', doc, { rootName: json.root });
         }
         return new Position(doc.getRoot(json.root), json.path, json.stickiness);
     }
 }
-/**
- * Checks whether this object is of the given.
- *
- *		position.is( 'position' ); // -> true
- *		position.is( 'model:position' ); // -> true
- *
- *		position.is( 'view:position' ); // -> false
- *		position.is( 'documentSelection' ); // -> false
- *
- * {@link module:engine/model/node~Node#is Check the entire list of model objects} which implement the `is()` method.
- *
- * @param {String} type
- * @returns {Boolean}
- */
+// The magic of type inference using `is` method is centralized in `TypeCheckable` class.
+// Proper overload would interfere with that.
 Position.prototype.is = function (type) {
     return type === 'position' || type === 'model:position';
 };
@@ -941,10 +843,7 @@ Position.prototype.is = function (type) {
  * * {@link module:engine/model/position~getNodeAfterPosition}
  * * {@link module:engine/model/position~getNodeBeforePosition}
  *
- * @param {module:engine/model/position~Position} position
- * @param {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment} positionParent The parent of the
- * given position.
- * @returns {module:engine/model/text~Text|null}
+ * @param positionParent The parent of the given position.
  */
 export function getTextNodeAtPosition(position, positionParent) {
     const node = positionParent.getChild(positionParent.offsetToIndex(position.offset));
@@ -972,11 +871,8 @@ export function getTextNodeAtPosition(position, positionParent) {
  * * {@link module:engine/model/position~getTextNodeAtPosition}
  * * {@link module:engine/model/position~getNodeBeforePosition}
  *
- * @param {module:engine/model/position~Position} position
- * @param {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment} positionParent The parent of the
- * given position.
- * @param {module:engine/model/text~Text|null} textNode Text node at the given position.
- * @returns {module:engine/model/node~Node|null}
+ * @param positionParent The parent of the given position.
+ * @param textNode Text node at the given position.
  */
 export function getNodeAfterPosition(position, positionParent, textNode) {
     if (textNode !== null) {
@@ -994,11 +890,8 @@ export function getNodeAfterPosition(position, positionParent, textNode) {
  * * {@link module:engine/model/position~getTextNodeAtPosition}
  * * {@link module:engine/model/position~getNodeAfterPosition}
  *
- * @param {module:engine/model/position~Position} position
- * @param {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment} positionParent The parent of the
- * given position.
- * @param {module:engine/model/text~Text|null} textNode Text node at the given position.
- * @returns {module:engine/model/node~Node|null}
+ * @param positionParent The parent of the given position.
+ * @param textNode Text node at the given position.
  */
 export function getNodeBeforePosition(position, positionParent, textNode) {
     if (textNode !== null) {
@@ -1006,18 +899,19 @@ export function getNodeBeforePosition(position, positionParent, textNode) {
     }
     return positionParent.getChild(positionParent.offsetToIndex(position.offset) - 1);
 }
-// This is a helper function for `Position#isTouching()`.
-//
-// It checks whether to given positions are touching, considering that they have the same root and paths
-// until given level, and at given level they differ by 1 (so they are branching at `level` point).
-//
-// The exact requirements for touching positions are described in `Position#isTouching()` and also
-// in the body of this function.
-//
-// @param {module:engine/model/position~Position} left Position "on the left" (it is before `right`).
-// @param {module:engine/model/position~Position} right Position "on the right" (it is after `left`).
-// @param {Number} level Level on which the positions are different.
-// @returns {Boolean}
+/**
+ * This is a helper function for `Position#isTouching()`.
+ *
+ * It checks whether to given positions are touching, considering that they have the same root and paths
+ * until given level, and at given level they differ by 1 (so they are branching at `level` point).
+ *
+ * The exact requirements for touching positions are described in `Position#isTouching()` and also
+ * in the body of this function.
+ *
+ * @param left Position "on the left" (it is before `right`).
+ * @param right Position "on the right" (it is after `left`).
+ * @param level Level on which the positions are different.
+ */
 function checkTouchingBranch(left, right, level) {
     if (level + 1 === left.path.length) {
         // Left position does not have any more entries after the point where the positions differ.
@@ -1046,14 +940,11 @@ function checkTouchingBranch(left, right, level) {
     // There are not elements between positions. The positions are touching.
     return true;
 }
-// Checks whether for given array, starting from given index until the end of the array, all items are `0`s.
-//
-// This is a helper function for `Position#isTouching()`.
-//
-// @private
-// @param {Array.<Number>} arr Array to check.
-// @param {Number} idx Index to start checking from.
-// @returns {Boolean}
+/**
+ * Checks whether for given array, starting from given index until the end of the array, all items are `0`s.
+ *
+ * This is a helper function for `Position#isTouching()`.
+ */
 function checkOnlyZeroes(arr, idx) {
     while (idx < arr.length) {
         if (arr[idx] !== 0) {
@@ -1063,15 +954,12 @@ function checkOnlyZeroes(arr, idx) {
     }
     return true;
 }
-// Checks whether for given position, starting from given path level, whether the position is at the end of
-// its parent and whether each element on the path to the position is also at at the end of its parent.
-//
-// This is a helper function for `Position#isTouching()`.
-//
-// @private
-// @param {module:engine/model/position~Position} pos Position to check.
-// @param {Number} level Level to start checking from.
-// @returns {Boolean}
+/**
+ * Checks whether for given position, starting from given path level, whether the position is at the end of
+ * its parent and whether each element on the path to the position is also at at the end of its parent.
+ *
+ * This is a helper function for `Position#isTouching()`.
+ */
 function checkOnlyMaxOffset(pos, level) {
     let parent = pos.parent;
     let idx = pos.path.length - 1;