@ckeditor/ckeditor5-engine 35.3.2 → 36.0.0

package/src/model/selection.js

@@ -1,8 +1,7 @@
 /**
- * @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
  */
-/* eslint-disable new-cap */
 /**
  * @module engine/model/selection
  */
@@ -10,93 +9,79 @@ import TypeCheckable from './typecheckable';
 import Node from './node';
 import Position from './position';
 import Range from './range';
-import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
-import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
-import isIterable from '@ckeditor/ckeditor5-utils/src/isiterable';
+import { CKEditorError, EmitterMixin, isIterable } from '@ckeditor/ckeditor5-utils';
 /**
  * Selection is a set of {@link module:engine/model/range~Range ranges}. It has a direction specified by its
  * {@link module:engine/model/selection~Selection#anchor anchor} and {@link module:engine/model/selection~Selection#focus focus}
  * (it can be {@link module:engine/model/selection~Selection#isBackward forward or backward}).
  * Additionally, selection may have its own attributes (think – whether text typed in in this selection
  * should have those attributes – e.g. whether you type a bolded text).
- *
- * @mixes module:utils/emittermixin~EmitterMixin
  */
 export default class Selection extends EmitterMixin(TypeCheckable) {
     /**
      * Creates a new selection instance based on the given {@link module:engine/model/selection~Selectable selectable}
      * or creates an empty selection if no arguments were passed.
      *
-     *		// Creates empty selection without ranges.
-     *		const selection = writer.createSelection();
+     * ```ts
+     * // Creates empty selection without ranges.
+     * const selection = writer.createSelection();
      *
-     *		// Creates selection at the given range.
-     *		const range = writer.createRange( start, end );
-     *		const selection = writer.createSelection( range );
+     * // Creates selection at the given range.
+     * const range = writer.createRange( start, end );
+     * const selection = writer.createSelection( range );
      *
-     *		// Creates selection at the given ranges
-     *		const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
-     *		const selection = writer.createSelection( ranges );
+     * // Creates selection at the given ranges
+     * const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
+     * const selection = writer.createSelection( ranges );
      *
-     *		// Creates selection from the other selection.
-     *		// Note: It doesn't copies selection attributes.
-     *		const otherSelection = writer.createSelection();
-     *		const selection = writer.createSelection( otherSelection );
+     * // Creates selection from the other selection.
+     * // Note: It doesn't copy selection attributes.
+     * const otherSelection = writer.createSelection();
+     * const selection = writer.createSelection( otherSelection );
      *
-     *		// Creates selection from the given document selection.
-     *		// Note: It doesn't copies selection attributes.
-     *		const documentSelection = model.document.selection;
-     *		const selection = writer.createSelection( documentSelection );
+     * // Creates selection from the given document selection.
+     * // Note: It doesn't copy selection attributes.
+     * const documentSelection = model.document.selection;
+     * const selection = writer.createSelection( documentSelection );
      *
-     *		// Creates selection at the given position.
-     *		const position = writer.createPositionFromPath( root, path );
-     *		const selection = writer.createSelection( position );
+     * // Creates selection at the given position.
+     * const position = writer.createPositionFromPath( root, path );
+     * const selection = writer.createSelection( position );
      *
-     *		// Creates selection at the given offset in the given element.
-     *		const paragraph = writer.createElement( 'paragraph' );
-     *		const selection = writer.createSelection( paragraph, offset );
+     * // Creates selection at the given offset in the given element.
+     * const paragraph = writer.createElement( 'paragraph' );
+     * const selection = writer.createSelection( paragraph, offset );
      *
-     *		// Creates a range inside an {@link module:engine/model/element~Element element} which starts before the
-     *		// first child of that element and ends after the last child of that element.
-     *		const selection = writer.createSelection( paragraph, 'in' );
+     * // Creates a range inside an {@link module:engine/model/element~Element element} which starts before the
+     * // first child of that element and ends after the last child of that element.
+     * const selection = writer.createSelection( paragraph, 'in' );
      *
-     *		// Creates a range on an {@link module:engine/model/item~Item item} which starts before the item and ends
-     *		// just after the item.
-     *		const selection = writer.createSelection( paragraph, 'on' );
+     * // Creates a range on an {@link module:engine/model/item~Item item} which starts before the item and ends
+     * // just after the item.
+     * const selection = writer.createSelection( paragraph, 'on' );
+     * ```
      *
      * Selection's constructor allow passing additional options (`'backward'`) as the last argument.
      *
-     *		// Creates backward selection.
-     *		const selection = writer.createSelection( range, { backward: true } );
+     * ```ts
+     * // Creates backward selection.
+     * const selection = writer.createSelection( range, { backward: true } );
+     * ```
      *
-     * @param {module:engine/model/selection~Selectable} [selectable]
-     * @param {Number|'before'|'end'|'after'|'on'|'in'} [placeOrOffset] Sets place or offset of the selection.
-     * @param {Object} [options]
-     * @param {Boolean} [options.backward] Sets this selection instance to be backward.
+     * @internal
      */
     constructor(...args) {
         super();
         /**
          * Specifies whether the last added range was added as a backward or forward range.
-         *
-         * @private
-         * @type {Boolean}
          */
         this._lastRangeBackward = false;
-        /**
-         * Stores selection ranges.
-         *
-         * @protected
-         * @type {Array.<module:engine/model/range~Range>}
-         */
-        this._ranges = [];
         /**
          * List of attributes set on current selection.
-         *
-         * @protected
-         * @type {Map.<String,*>}
          */
         this._attrs = new Map();
+        /** @internal */
+        this._ranges = [];
         if (args.length) {
             this.setTo(...args);
         }
@@ -115,8 +100,6 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
      * May be set to `null` if there are no ranges in the selection.
      *
      * @see #focus
-     * @readonly
-     * @type {module:engine/model/position~Position|null}
      */
     get anchor() {
         if (this._ranges.length > 0) {
@@ -132,8 +115,6 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
      * May be set to `null` if there are no ranges in the selection.
      *
      * @see #anchor
-     * @readonly
-     * @type {module:engine/model/position~Position|null}
      */
     get focus() {
         if (this._ranges.length > 0) {
@@ -145,9 +126,6 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
     /**
      * Whether the selection is collapsed. Selection is collapsed when there is exactly one range in it
      * and it is collapsed.
-     *
-     * @readonly
-     * @type {Boolean}
      */
     get isCollapsed() {
         const length = this._ranges.length;
@@ -160,18 +138,12 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
     }
     /**
      * Returns the number of ranges in the selection.
-     *
-     * @readonly
-     * @type {Number}
      */
     get rangeCount() {
         return this._ranges.length;
     }
     /**
      * Specifies whether the selection's {@link #focus} precedes the selection's {@link #anchor}.
-     *
-     * @readonly
-     * @type {Boolean}
      */
     get isBackward() {
         return !this.isCollapsed && this._lastRangeBackward;
@@ -180,9 +152,8 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
      * Checks whether this selection is equal to the given selection. Selections are equal if they have the same directions,
      * the same number of ranges and all ranges from one selection equal to ranges from the another selection.
      *
-     * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} otherSelection
-     * Selection to compare with.
-     * @returns {Boolean} `true` if selections are equal, `false` otherwise.
+     * @param otherSelection Selection to compare with.
+     * @returns `true` if selections are equal, `false` otherwise.
      */
     isEqual(otherSelection) {
         if (this.rangeCount != otherSelection.rangeCount) {
@@ -210,8 +181,6 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
     }
     /**
      * Returns an iterable object that iterates over copies of selection ranges.
-     *
-     * @returns {Iterable.<module:engine/model/range~Range>}
      */
     *getRanges() {
         for (const range of this._ranges) {
@@ -225,8 +194,6 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
      * (not to confuse with the first range added to the selection).
      *
      * Returns `null` if there are no ranges in selection.
-     *
-     * @returns {module:engine/model/range~Range|null}
      */
     getFirstRange() {
         let first = null;
@@ -244,8 +211,6 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
      * recently added to the selection).
      *
      * Returns `null` if there are no ranges in selection.
-     *
-     * @returns {module:engine/model/range~Range|null}
      */
     getLastRange() {
         let last = null;
@@ -262,8 +227,6 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
      * any other position in the selection.
      *
      * Returns `null` if there are no ranges in selection.
-     *
-     * @returns {module:engine/model/position~Position|null}
      */
     getFirstPosition() {
         const first = this.getFirstRange();
@@ -275,8 +238,6 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
      * any other position in the selection.
      *
      * Returns `null` if there are no ranges in selection.
-     *
-     * @returns {module:engine/model/position~Position|null}
      */
     getLastPosition() {
         const lastRange = this.getLastRange();
@@ -286,52 +247,55 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
      * Sets this selection's ranges and direction to the specified location based on the given
      * {@link module:engine/model/selection~Selectable selectable}.
      *
-     *		// Removes all selection's ranges.
-     *		selection.setTo( null );
+     * ```ts
+     * // Removes all selection's ranges.
+     * selection.setTo( null );
      *
-     *		// Sets selection to the given range.
-     *		const range = writer.createRange( start, end );
-     *		selection.setTo( range );
+     * // Sets selection to the given range.
+     * const range = writer.createRange( start, end );
+     * selection.setTo( range );
      *
-     *		// Sets selection to given ranges.
-     *		const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
-     *		selection.setTo( ranges );
+     * // Sets selection to given ranges.
+     * const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
+     * selection.setTo( ranges );
      *
-     *		// Sets selection to other selection.
-     *		// Note: It doesn't copies selection attributes.
-     *		const otherSelection = writer.createSelection();
-     *		selection.setTo( otherSelection );
+     * // Sets selection to other selection.
+     * // Note: It doesn't copy selection attributes.
+     * const otherSelection = writer.createSelection();
+     * selection.setTo( otherSelection );
      *
-     *		// Sets selection to the given document selection.
-     *		// Note: It doesn't copies selection attributes.
-     *		const documentSelection = new DocumentSelection( doc );
-     *		selection.setTo( documentSelection );
+     * // Sets selection to the given document selection.
+     * // Note: It doesn't copy selection attributes.
+     * const documentSelection = new DocumentSelection( doc );
+     * selection.setTo( documentSelection );
      *
-     *		// Sets collapsed selection at the given position.
-     *		const position = writer.createPositionFromPath( root, path );
-     *		selection.setTo( position );
+     * // Sets collapsed selection at the given position.
+     * const position = writer.createPositionFromPath( root, path );
+     * selection.setTo( position );
      *
-     *		// Sets collapsed selection at the position of the given node and an offset.
-     *		selection.setTo( paragraph, offset );
+     * // Sets collapsed selection at the position of the given node and an offset.
+     * selection.setTo( paragraph, offset );
+     * ```
      *
      * Creates a range inside an {@link module:engine/model/element~Element element} which starts before the first child of
      * that element and ends after the last child of that element.
      *
-     *		selection.setTo( paragraph, 'in' );
+     * ```ts
+     * selection.setTo( paragraph, 'in' );
+     * ```
      *
      * Creates a range on an {@link module:engine/model/item~Item item} which starts before the item and ends just after the item.
      *
-     *		selection.setTo( paragraph, 'on' );
+     * ```ts
+     * selection.setTo( paragraph, 'on' );
+     * ```
      *
      * `Selection#setTo()`' method allow passing additional options (`backward`) as the last argument.
      *
-     *		// Sets backward selection.
-     *		const selection = writer.createSelection( range, { backward: true } );
-     *
-     * @param {module:engine/model/selection~Selectable} selectable
-     * @param {Number|'before'|'end'|'after'|'on'|'in'} [placeOrOffset] Sets place or offset of the selection.
-     * @param {Object} [options]
-     * @param {Boolean} [options.backward] Sets this selection instance to be backward.
+     * ```ts
+     * // Sets backward selection.
+     * const selection = writer.createSelection( range, { backward: true } );
+     * ```
      */
     setTo(...args) {
         let [selectable, placeOrOffset, options] = args;
@@ -403,10 +367,9 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
      * is treated like the last added range and is used to set {@link module:engine/model/selection~Selection#anchor} and
      * {@link module:engine/model/selection~Selection#focus}. Accepts a flag describing in which direction the selection is made.
      *
-     * @protected
      * @fires change:range
-     * @param {Iterable.<module:engine/model/range~Range>} newRanges Ranges to set.
-     * @param {Boolean} [isLastBackward=false] Flag describing if last added range was selected forward - from start to end (`false`)
+     * @param newRanges Ranges to set.
+     * @param isLastBackward Flag describing if last added range was selected forward - from start to end (`false`)
      * or backward - from end to start (`true`).
      */
     _setRanges(newRanges, isLastBackward = false) {
@@ -446,9 +409,7 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
      * {@link module:engine/model/writer~Writer#createPositionAt writer.createPositionAt()} parameters.
      *
      * @fires change:range
-     * @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
-     * first parameter is a {@link module:engine/model/item~Item model item}.
+     * @param offset Offset or one of the flags. Used only when first parameter is a {@link module:engine/model/item~Item model item}.
      */
     setFocus(itemOrPosition, offset) {
         if (this.anchor === null) {
@@ -480,8 +441,8 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
     /**
      * Gets an attribute value for given key or `undefined` if that attribute is not set on the selection.
      *
-     * @param {String} key Key of attribute to look for.
-     * @returns {*} Attribute value or `undefined`.
+     * @param key Key of attribute to look for.
+     * @returns Attribute value or `undefined`.
      */
     getAttribute(key) {
         return this._attrs.get(key);
@@ -491,16 +452,12 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
      *
      * Attributes are returned as arrays containing two items. First one is attribute key and second is attribute value.
      * This format is accepted by native `Map` object and also can be passed in `Node` constructor.
-     *
-     * @returns {Iterable.<*>}
      */
     getAttributes() {
         return this._attrs.entries();
     }
     /**
      * Returns iterable that iterates over this selection's attribute keys.
-     *
-     * @returns {Iterable.<String>}
      */
     getAttributeKeys() {
         return this._attrs.keys();
@@ -508,8 +465,8 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
     /**
      * Checks if the selection has an attribute for given key.
      *
-     * @param {String} key Key of attribute to check.
-     * @returns {Boolean} `true` if attribute with given key is set on selection, `false` otherwise.
+     * @param key Key of attribute to check.
+     * @returns `true` if attribute with given key is set on selection, `false` otherwise.
      */
     hasAttribute(key) {
         return this._attrs.has(key);
@@ -521,7 +478,7 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
      * removed attribute key.
      *
      * @fires change:attribute
-     * @param {String} key Key of attribute to remove.
+     * @param key Key of attribute to remove.
      */
     removeAttribute(key) {
         if (this.hasAttribute(key)) {
@@ -536,8 +493,8 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
      * the attribute key.
      *
      * @fires change:attribute
-     * @param {String} key Key of attribute to set.
-     * @param {*} value Attribute value.
+     * @param key Key of attribute to set.
+     * @param value Attribute value.
      */
     setAttribute(key, value) {
         if (this.getAttribute(key) !== value) {
@@ -549,8 +506,6 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
      * Returns the selected element. {@link module:engine/model/element~Element Element} is considered as selected if there is only
      * one range in the selection, and that range contains exactly one element.
      * Returns `null` if there is no selected element.
-     *
-     * @returns {module:engine/model/element~Element|null}
      */
     getSelectedElement() {
         if (this.rangeCount !== 1) {
@@ -568,40 +523,48 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
      *
      * In this case the function will return exactly all 3 paragraphs (note: `<blockQuote>` is not a block itself):
      *
-     *		<paragraph>[a</paragraph>
-     *		<blockQuote>
-     *			<paragraph>b</paragraph>
-     *		</blockQuote>
-     *		<paragraph>c]d</paragraph>
+     * ```xml
+     * <paragraph>[a</paragraph>
+     * <blockQuote>
+     * 	<paragraph>b</paragraph>
+     * </blockQuote>
+     * <paragraph>c]d</paragraph>
+     * ```
      *
      * In this case the paragraph will also be returned, despite the collapsed selection:
      *
-     *		<paragraph>[]a</paragraph>
+     * ```xml
+     * <paragraph>[]a</paragraph>
+     * ```
      *
      * In such a scenario, however, only blocks A, B & E will be returned as blocks C & D are nested in block B:
      *
-     *		[<blockA></blockA>
-     *		<blockB>
-     *			<blockC></blockC>
-     *			<blockD></blockD>
-     *		</blockB>
-     *		<blockE></blockE>]
+     * ```xml
+     * [<blockA></blockA>
+     * <blockB>
+     * 	<blockC></blockC>
+     * 	<blockD></blockD>
+     * </blockB>
+     * <blockE></blockE>]
+     * ```
      *
      * If the selection is inside a block all the inner blocks (A & B) are returned:
      *
-     * 		<block>
-     *			<blockA>[a</blockA>
-     * 			<blockB>b]</blockB>
-     * 		</block>
+     * ```xml
+     * <block>
+     * 	<blockA>[a</blockA>
+     * 	<blockB>b]</blockB>
+     * </block>
+     * ```
      *
      * **Special case**: If a selection ends at the beginning of a block, that block is not returned as from user perspective
      * this block wasn't selected. See [#984](https://github.com/ckeditor/ckeditor5-engine/issues/984) for more details.
      *
-     *		<paragraph>[a</paragraph>
-     *		<paragraph>b</paragraph>
-     *		<paragraph>]c</paragraph> // this block will not be returned
-     *
-     * @returns {Iterable.<module:engine/model/element~Element>}
+     * ```xml
+     * <paragraph>[a</paragraph>
+     * <paragraph>b</paragraph>
+     * <paragraph>]c</paragraph> // this block will not be returned
+     * ```
      */
     *getSelectedBlocks() {
         const visited = new WeakSet();
@@ -631,9 +594,6 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
      *
      * By default, this method will check whether the entire content of the selection's current root is selected.
      * Useful to check if e.g. the user has just pressed <kbd>Ctrl</kbd> + <kbd>A</kbd>.
-     *
-     * @param {module:engine/model/element~Element} [element=this.anchor.root]
-     * @returns {Boolean}
      */
     containsEntireContent(element = this.anchor.root) {
         const limitStartPosition = Position._createAt(element, 0);
@@ -644,9 +604,6 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
     /**
      * Adds given range to internal {@link #_ranges ranges array}. Throws an error
      * if given range is intersecting with any range that is already stored in this selection.
-     *
-     * @protected
-     * @param {module:engine/model/range~Range} range Range to add.
      */
     _pushRange(range) {
         this._checkRange(range);
@@ -654,9 +611,6 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
     }
     /**
      * Checks if given range intersects with ranges that are already in the selection. Throws an error if it does.
-     *
-     * @protected
-     * @param {module:engine/model/range~Range} range Range to check.
      */
     _checkRange(range) {
         for (let i = 0; i < this._ranges.length; i++) {
@@ -665,8 +619,8 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
                  * Trying to add a range that intersects with another range in the selection.
                  *
                  * @error model-selection-range-intersects
-                 * @param {module:engine/model/range~Range} addedRange Range that was added to the selection.
-                 * @param {module:engine/model/range~Range} intersectingRange Range in the selection that intersects with `addedRange`.
+                 * @param addedRange Range that was added to the selection.
+                 * @param intersectingRange Range in the selection that intersects with `addedRange`.
                  */
                 throw new CKEditorError('model-selection-range-intersects', [this, range], { addedRange: range, intersectingRange: this._ranges[i] });
             }
@@ -675,9 +629,6 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
     /**
      * Replaces all the ranges by the given ones.
      * Uses {@link #_popRange _popRange} and {@link #_pushRange _pushRange} to ensure proper ranges removal and addition.
-     *
-     * @param {Array.<module:engine/model/range~Range>} ranges
-     * @protected
      */
     _replaceAllRanges(ranges) {
         this._removeAllRanges();
@@ -688,8 +639,6 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
     /**
      * Deletes ranges from internal range array. Uses {@link #_popRange _popRange} to
      * ensure proper ranges removal.
-     *
-     * @protected
      */
     _removeAllRanges() {
         while (this._ranges.length > 0) {
@@ -698,32 +647,20 @@ export default class Selection extends EmitterMixin(TypeCheckable) {
     }
     /**
      * Removes most recently added range from the selection.
-     *
-     * @protected
      */
     _popRange() {
         this._ranges.pop();
     }
 }
-/**
- * Checks whether this object is of the given.
- *
- *		selection.is( 'selection' ); // -> true
- *		selection.is( 'model:selection' ); // -> true
- *
- *		selection.is( 'view:selection' ); // -> false
- *		selection.is( 'range' ); // -> 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.
 Selection.prototype.is = function (type) {
     return type === 'selection' || type === 'model:selection';
 };
-// Checks whether the given element extends $block in the schema and has a parent (is not a root).
-// Marks it as already visited.
+/**
+ * Checks whether the given element extends $block in the schema and has a parent (is not a root).
+ * Marks it as already visited.
+ */
 function isUnvisitedBlock(element, visited) {
     if (visited.has(element)) {
         return false;
@@ -731,13 +668,17 @@ function isUnvisitedBlock(element, visited) {
     visited.add(element);
     return element.root.document.model.schema.isBlock(element) && !!element.parent;
 }
-// Checks if the given element is a $block was not previously visited and is a top block in a range.
+/**
+ * Checks if the given element is a $block was not previously visited and is a top block in a range.
+ */
 function isUnvisitedTopBlock(element, visited, range) {
     return isUnvisitedBlock(element, visited) && isTopBlockInRange(element, range);
 }
-// Finds the lowest element in position's ancestors which is a block.
-// It will search until first ancestor that is a limit element.
-// Marks all ancestors as already visited to not include any of them later on.
+/**
+ * Finds the lowest element in position's ancestors which is a block.
+ * It will search until first ancestor that is a limit element.
+ * Marks all ancestors as already visited to not include any of them later on.
+ */
 function getParentBlock(position, visited) {
     const element = position.parent;
     const schema = element.root.document.model.schema;
@@ -756,10 +697,9 @@ function getParentBlock(position, visited) {
     ancestors.forEach(element => visited.add(element));
     return block;
 }
-// Checks if the blocks is not nested in other block inside a range.
-//
-// @param {module:engine/model/element~Element} block Block to check.
-// @param {module:engine/model/range~Range} range Range to check.
+/**
+ * Checks if the blocks is not nested in other block inside a range.
+ */
 function isTopBlockInRange(block, range) {
     const parentBlock = findAncestorBlock(block);
     if (!parentBlock) {
@@ -769,10 +709,9 @@ function isTopBlockInRange(block, range) {
     const isParentInRange = range.containsRange(Range._createOn(parentBlock), true);
     return !isParentInRange;
 }
-// Returns first ancestor block of a node.
-//
-// @param {module:engine/model/node~Node} node
-// @returns {module:engine/model/node~Node|undefined}
+/**
+ * Returns first ancestor block of a node.
+ */
 function findAncestorBlock(node) {
     const schema = node.root.document.model.schema;
     let parent = node.parent;