@ckeditor/ckeditor5-engine 35.3.2 → 36.0.0

package/src/model/range.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
  */
 /**
@@ -8,8 +8,7 @@
 import TypeCheckable from './typecheckable';
 import Position from './position';
 import TreeWalker from './treewalker';
-import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
-import compareArrays from '@ckeditor/ckeditor5-utils/src/comparearrays';
+import { CKEditorError, compareArrays } from '@ckeditor/ckeditor5-utils';
 /**
  * Represents a range in the model tree.
  *
@@ -23,25 +22,12 @@ export default class Range extends TypeCheckable {
     /**
      * Creates a range spanning from `start` position to `end` position.
      *
-     * @param {module:engine/model/position~Position} start The start position.
-     * @param {module:engine/model/position~Position|null} [end] The end position. If not set,
-     * the range will be collapsed at the `start` position.
+     * @param start The start position.
+     * @param end The end position. If not set, the range will be collapsed at the `start` position.
      */
     constructor(start, end) {
         super();
-        /**
-         * Start position.
-         *
-         * @readonly
-         * @member {module:engine/model/position~Position}
-         */
         this.start = Position._createAt(start);
-        /**
-         * End position.
-         *
-         * @readonly
-         * @member {module:engine/model/position~Position}
-         */
         this.end = end ? Position._createAt(end) : Position._createAt(start);
         // If the range is collapsed, treat in a similar way as a position and set its boundaries stickiness to 'toNone'.
         // In other case, make the boundaries stick to the "inside" of the range.
@@ -59,26 +45,20 @@ export default class Range extends TypeCheckable {
      *
      * This iterator uses {@link module:engine/model/treewalker~TreeWalker} with `boundaries` set to this range
      * and `ignoreElementEnd` option set to `true`.
-     *
-     * @returns {Iterator.<module:engine/model/treewalker~TreeWalkerValue>}
      */
     *[Symbol.iterator]() {
         yield* new TreeWalker({ boundaries: this, ignoreElementEnd: true });
     }
     /**
-     * Returns whether the range is collapsed, that is if {@link #start} and
+     * Describes whether the range is collapsed, that is if {@link #start} and
      * {@link #end} positions are equal.
-     *
-     * @type {Boolean}
      */
     get isCollapsed() {
         return this.start.isEqual(this.end);
     }
     /**
-     * Returns whether this range is flat, that is if {@link #start} position and
+     * Describes whether this range is flat, that is if {@link #start} position and
      * {@link #end} position are in the same {@link module:engine/model/position~Position#parent}.
-     *
-     * @type {Boolean}
      */
     get isFlat() {
         const startParentPath = this.start.getParentPath();
@@ -87,8 +67,6 @@ export default class Range extends TypeCheckable {
     }
     /**
      * Range root element.
-     *
-     * @type {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment}
      */
     get root() {
         return this.start.root;
@@ -96,8 +74,8 @@ export default class Range extends TypeCheckable {
     /**
      * Checks whether this range contains given {@link module:engine/model/position~Position position}.
      *
-     * @param {module:engine/model/position~Position} position Position to check.
-     * @returns {Boolean} `true` if given {@link module:engine/model/position~Position position} is contained
+     * @param position Position to check.
+     * @returns `true` if given {@link module:engine/model/position~Position position} is contained
      * in this range,`false` otherwise.
      */
     containsPosition(position) {
@@ -106,8 +84,8 @@ export default class Range extends TypeCheckable {
     /**
      * Checks whether this range contains given {@link ~Range range}.
      *
-     * @param {module:engine/model/range~Range} otherRange Range to check.
-     * @param {Boolean} [loose=false] Whether the check is loose or strict. If the check is strict (`false`), compared range cannot
+     * @param otherRange Range to check.
+     * @param loose Whether the check is loose or strict. If the check is strict (`false`), compared range cannot
      * start or end at the same position as this range boundaries. If the check is loose (`true`), compared range can start, end or
      * even be equal to this range. Note that collapsed ranges are always compared in strict mode.
      * @returns {Boolean} `true` if given {@link ~Range range} boundaries are contained by this range, `false` otherwise.
@@ -122,8 +100,6 @@ export default class Range extends TypeCheckable {
     }
     /**
      * Checks whether given {@link module:engine/model/item~Item} is inside this range.
-     *
-     * @param {module:engine/model/item~Item} item Model item to check.
      */
     containsItem(item) {
         const pos = Position._createBefore(item);
@@ -132,8 +108,8 @@ export default class Range extends TypeCheckable {
     /**
      * Two ranges are equal if their {@link #start} and {@link #end} positions are equal.
      *
-     * @param {module:engine/model/range~Range} otherRange Range to compare with.
-     * @returns {Boolean} `true` if ranges are equal, `false` otherwise.
+     * @param otherRange Range to compare with.
+     * @returns `true` if ranges are equal, `false` otherwise.
      */
     isEqual(otherRange) {
         return this.start.isEqual(otherRange.start) && this.end.isEqual(otherRange.end);
@@ -141,8 +117,8 @@ export default class Range extends TypeCheckable {
     /**
      * Checks and returns whether this range intersects with given range.
      *
-     * @param {module:engine/model/range~Range} otherRange Range to compare with.
-     * @returns {Boolean} `true` if ranges intersect, `false` otherwise.
+     * @param otherRange Range to compare with.
+     * @returns `true` if ranges intersect, `false` otherwise.
      */
     isIntersecting(otherRange) {
         return this.start.isBefore(otherRange.end) && this.end.isAfter(otherRange.start);
@@ -153,24 +129,26 @@ export default class Range extends TypeCheckable {
      *
      * Examples:
      *
-     *		let range = model.createRange(
-     *			model.createPositionFromPath( root, [ 2, 7 ] ),
-     *			model.createPositionFromPath( root, [ 4, 0, 1 ] )
-     *		);
-     *		let otherRange = model.createRange( model.createPositionFromPath( root, [ 1 ] ), model.createPositionFromPath( root, [ 5 ] ) );
-     *		let transformed = range.getDifference( otherRange );
-     *		// transformed array has no ranges because `otherRange` contains `range`
+     * ```ts
+     * let range = model.createRange(
+     * 	model.createPositionFromPath( root, [ 2, 7 ] ),
+     * 	model.createPositionFromPath( root, [ 4, 0, 1 ] )
+     * );
+     * let otherRange = model.createRange( model.createPositionFromPath( root, [ 1 ] ), model.createPositionFromPath( root, [ 5 ] ) );
+     * let transformed = range.getDifference( otherRange );
+     * // transformed array has no ranges because `otherRange` contains `range`
      *
-     *		otherRange = model.createRange( model.createPositionFromPath( root, [ 1 ] ), model.createPositionFromPath( root, [ 3 ] ) );
-     *		transformed = range.getDifference( otherRange );
-     *		// transformed array has one range: from [ 3 ] to [ 4, 0, 1 ]
+     * otherRange = model.createRange( model.createPositionFromPath( root, [ 1 ] ), model.createPositionFromPath( root, [ 3 ] ) );
+     * transformed = range.getDifference( otherRange );
+     * // transformed array has one range: from [ 3 ] to [ 4, 0, 1 ]
      *
-     *		otherRange = model.createRange( model.createPositionFromPath( root, [ 3 ] ), model.createPositionFromPath( root, [ 4 ] ) );
-     *		transformed = range.getDifference( otherRange );
-     *		// transformed array has two ranges: from [ 2, 7 ] to [ 3 ] and from [ 4 ] to [ 4, 0, 1 ]
+     * otherRange = model.createRange( model.createPositionFromPath( root, [ 3 ] ), model.createPositionFromPath( root, [ 4 ] ) );
+     * transformed = range.getDifference( otherRange );
+     * // transformed array has two ranges: from [ 2, 7 ] to [ 3 ] and from [ 4 ] to [ 4, 0, 1 ]
+     * ```
      *
-     * @param {module:engine/model/range~Range} otherRange Range to differentiate against.
-     * @returns {Array.<module:engine/model/range~Range>} The difference between ranges.
+     * @param otherRange Range to differentiate against.
+     * @returns The difference between ranges.
      */
     getDifference(otherRange) {
         const ranges = [];
@@ -199,18 +177,20 @@ export default class Range extends TypeCheckable {
      *
      * Examples:
      *
-     *		let range = model.createRange(
-     *			model.createPositionFromPath( root, [ 2, 7 ] ),
-     *			model.createPositionFromPath( root, [ 4, 0, 1 ] )
-     *		);
-     *		let otherRange = model.createRange( model.createPositionFromPath( root, [ 1 ] ), model.createPositionFromPath( root, [ 2 ] ) );
-     *		let transformed = range.getIntersection( otherRange ); // null - ranges have no common part
+     * ```ts
+     * let range = model.createRange(
+     * 	model.createPositionFromPath( root, [ 2, 7 ] ),
+     * 	model.createPositionFromPath( root, [ 4, 0, 1 ] )
+     * );
+     * let otherRange = model.createRange( model.createPositionFromPath( root, [ 1 ] ), model.createPositionFromPath( root, [ 2 ] ) );
+     * let transformed = range.getIntersection( otherRange ); // null - ranges have no common part
      *
-     *		otherRange = model.createRange( model.createPositionFromPath( root, [ 3 ] ), model.createPositionFromPath( root, [ 5 ] ) );
-     *		transformed = range.getIntersection( otherRange ); // range from [ 3 ] to [ 4, 0, 1 ]
+     * otherRange = model.createRange( model.createPositionFromPath( root, [ 3 ] ), model.createPositionFromPath( root, [ 5 ] ) );
+     * transformed = range.getIntersection( otherRange ); // range from [ 3 ] to [ 4, 0, 1 ]
+     * ```
      *
-     * @param {module:engine/model/range~Range} otherRange Range to check for intersection.
-     * @returns {module:engine/model/range~Range|null} A common part of given ranges or `null` if ranges have no common part.
+     * @param otherRange Range to check for intersection.
+     * @returns A common part of given ranges or `null` if ranges have no common part.
      */
     getIntersection(otherRange) {
         if (this.isIntersecting(otherRange)) {
@@ -239,27 +219,29 @@ export default class Range extends TypeCheckable {
      *
      * Examples:
      *
-     *		let range = model.createRange(
-     *			model.createPositionFromPath( root, [ 2, 7 ] ),
-     *			model.createPositionFromPath( root, [ 4, 0, 1 ] )
-     *		);
-     *		let otherRange = model.createRange(
-     *			model.createPositionFromPath( root, [ 1 ] ),
-     *			model.createPositionFromPath( root, [ 2 ] )
-     *		);
-     *		let transformed = range.getJoined( otherRange ); // null - ranges have no common part
-     *
-     *		otherRange = model.createRange(
-     *			model.createPositionFromPath( root, [ 3 ] ),
-     *			model.createPositionFromPath( root, [ 5 ] )
-     *		);
-     *		transformed = range.getJoined( otherRange ); // range from [ 2, 7 ] to [ 5 ]
-     *
-     * @param {module:engine/model/range~Range} otherRange Range to be joined.
-     * @param {Boolean} [loose=false] Whether the intersection check is loose or strict. If the check is strict (`false`),
+     * ```ts
+     * let range = model.createRange(
+     * 	model.createPositionFromPath( root, [ 2, 7 ] ),
+     * 	model.createPositionFromPath( root, [ 4, 0, 1 ] )
+     * );
+     * let otherRange = model.createRange(
+     * 	model.createPositionFromPath( root, [ 1 ] ),
+     * 	model.createPositionFromPath( root, [ 2 ] )
+     * );
+     * let transformed = range.getJoined( otherRange ); // null - ranges have no common part
+     *
+     * otherRange = model.createRange(
+     * 	model.createPositionFromPath( root, [ 3 ] ),
+     * 	model.createPositionFromPath( root, [ 5 ] )
+     * );
+     * transformed = range.getJoined( otherRange ); // range from [ 2, 7 ] to [ 5 ]
+     * ```
+     *
+     * @param otherRange Range to be joined.
+     * @param loose Whether the intersection check is loose or strict. If the check is strict (`false`),
      * ranges are tested for intersection or whether start/end positions are equal. If the check is loose (`true`),
      * compared range is also checked if it's {@link module:engine/model/position~Position#isTouching touching} current range.
-     * @returns {module:engine/model/range~Range|null} A sum of given ranges or `null` if ranges have no common part.
+     * @returns A sum of given ranges or `null` if ranges have no common part.
      */
     getJoined(otherRange, loose = false) {
         let shouldJoin = this.isIntersecting(otherRange);
@@ -289,31 +271,35 @@ export default class Range extends TypeCheckable {
      *
      * See an example of a model structure (`[` and `]` are range boundaries):
      *
-     *		root                                                            root
-     *		 |- element DIV                         DIV             P2              P3             DIV
-     *		 |   |- element H                   H        P1        f o o           b a r       H         P4
-     *		 |   |   |- "fir[st"             fir[st     lorem                               se]cond     ipsum
-     *		 |   |- element P1
-     *		 |   |   |- "lorem"                                              ||
-     *		 |- element P2                                                   ||
-     *		 |   |- "foo"                                                    VV
-     *		 |- element P3
-     *		 |   |- "bar"                                                   root
-     *		 |- element DIV                         DIV             [P2             P3]             DIV
-     *		 |   |- element H                   H       [P1]       f o o           b a r        H         P4
-     *		 |   |   |- "se]cond"            fir[st]    lorem                               [se]cond     ipsum
-     *		 |   |- element P4
-     *		 |   |   |- "ipsum"
+     * ```
+     * root                                                            root
+     *  |- element DIV                         DIV             P2              P3             DIV
+     *  |   |- element H                   H        P1        f o o           b a r       H         P4
+     *  |   |   |- "fir[st"             fir[st     lorem                               se]cond     ipsum
+     *  |   |- element P1
+     *  |   |   |- "lorem"                                              ||
+     *  |- element P2                                                   ||
+     *  |   |- "foo"                                                    VV
+     *  |- element P3
+     *  |   |- "bar"                                                   root
+     *  |- element DIV                         DIV             [P2             P3]             DIV
+     *  |   |- element H                   H       [P1]       f o o           b a r        H         P4
+     *  |   |   |- "se]cond"            fir[st]    lorem                               [se]cond     ipsum
+     *  |   |- element P4
+     *  |   |   |- "ipsum"
+     * ```
      *
      * As it can be seen, letters contained in the range are: `stloremfoobarse`, spread across different parents.
      * We are looking for minimal set of flat ranges that contains the same nodes.
      *
      * Minimal flat ranges for above range `( [ 0, 0, 3 ], [ 3, 0, 2 ] )` will be:
      *
-     *		( [ 0, 0, 3 ], [ 0, 0, 5 ] ) = "st"
-     *		( [ 0, 1 ], [ 0, 2 ] ) = element P1 ("lorem")
-     *		( [ 1 ], [ 3 ] ) = element P2, element P3 ("foobar")
-     *		( [ 3, 0, 0 ], [ 3, 0, 2 ] ) = "se"
+     * ```
+     * ( [ 0, 0, 3 ], [ 0, 0, 5 ] ) = "st"
+     * ( [ 0, 1 ], [ 0, 2 ] ) = element P1 ("lorem")
+     * ( [ 1 ], [ 3 ] ) = element P2, element P3 ("foobar")
+     * ( [ 3, 0, 0 ], [ 3, 0, 2 ] ) = "se"
+     * ```
      *
      * **Note:** if an {@link module:engine/model/element~Element element} is not wholly contained in this range, it won't be returned
      * in any of the returned flat ranges. See in the example how `H` elements at the beginning and at the end of the range
@@ -321,7 +307,7 @@ export default class Range extends TypeCheckable {
      *
      * **Note:** this method is not returning flat ranges that contain no nodes.
      *
-     * @returns {Array.<module:engine/model/range~Range>} Array of flat ranges covering this range.
+     * @returns Array of flat ranges covering this range.
      */
     getMinimalFlatRanges() {
         const ranges = [];
@@ -355,20 +341,17 @@ export default class Range extends TypeCheckable {
      *
      * For example, to iterate over all items in the entire document root:
      *
-     *		// Create a range spanning over the entire root content:
-     *		const range = editor.model.createRangeIn( editor.model.document.getRoot() );
+     * ```ts
+     * // Create a range spanning over the entire root content:
+     * const range = editor.model.createRangeIn( editor.model.document.getRoot() );
      *
-     *		// Iterate over all items in this range:
-     *		for ( const value of range.getWalker() ) {
-     *			console.log( value.item );
-     *		}
+     * // Iterate over all items in this range:
+     * for ( const value of range.getWalker() ) {
+     * 	console.log( value.item );
+     * }
+     * ```
      *
-     * @param {Object} options Object with configuration options. See {@link module:engine/model/treewalker~TreeWalker}.
-     * @param {module:engine/model/position~Position} [options.startPosition]
-     * @param {Boolean} [options.singleCharacters=false]
-     * @param {Boolean} [options.shallow=false]
-     * @param {Boolean} [options.ignoreElementEnd=false]
-     * @returns {module:engine/model/treewalker~TreeWalker}
+     * @param options Object with configuration options. See {@link module:engine/model/treewalker~TreeWalker}.
      */
     getWalker(options = {}) {
         options.boundaries = this;
@@ -385,8 +368,7 @@ export default class Range extends TypeCheckable {
      * You may specify additional options for the tree walker. See {@link module:engine/model/treewalker~TreeWalker} for
      * a full list of available options.
      *
-     * @param {Object} [options] Object with configuration options. See {@link module:engine/model/treewalker~TreeWalker}.
-     * @returns {Iterable.<module:engine/model/item~Item>}
+     * @param options Object with configuration options. See {@link module:engine/model/treewalker~TreeWalker}.
      */
     *getItems(options = {}) {
         options.boundaries = this;
@@ -406,8 +388,7 @@ export default class Range extends TypeCheckable {
      * You may specify additional options for the tree walker. See {@link module:engine/model/treewalker~TreeWalker} for
      * a full list of available options.
      *
-     * @param {Object} options Object with configuration options. See {@link module:engine/model/treewalker~TreeWalker}.
-     * @returns {Iterable.<module:engine/model/position~Position>}
+     * @param options Object with configuration options. See {@link module:engine/model/treewalker~TreeWalker}.
      */
     *getPositions(options = {}) {
         options.boundaries = this;
@@ -424,8 +405,8 @@ export default class Range extends TypeCheckable {
      * moved to a different part of document tree). For this reason, an array is returned by this method and it
      * may contain one or more `Range` instances.
      *
-     * @param {module:engine/model/operation/operation~Operation} operation Operation to transform range by.
-     * @returns {Array.<module:engine/model/range~Range>} Range which is the result of transformation.
+     * @param operation Operation to transform range by.
+     * @returns Range which is the result of transformation.
      */
     getTransformedByOperation(operation) {
         switch (operation.type) {
@@ -446,8 +427,8 @@ export default class Range extends TypeCheckable {
      * Returns a range that is a result of transforming this range by multiple `operations`.
      *
      * @see ~Range#getTransformedByOperation
-     * @param {Iterable.<module:engine/model/operation/operation~Operation>} operations Operations to transform the range by.
-     * @returns {Array.<module:engine/model/range~Range>} Range which is the result of transformation.
+     * @param operations Operations to transform the range by.
+     * @returns Range which is the result of transformation.
      */
     getTransformedByOperations(operations) {
         const ranges = [new Range(this.start, this.end)];
@@ -476,8 +457,6 @@ export default class Range extends TypeCheckable {
     /**
      * Returns an {@link module:engine/model/element~Element} or {@link module:engine/model/documentfragment~DocumentFragment}
      * which is a common ancestor of the range's both ends (in which the entire range is contained).
-     *
-     * @returns {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment|null}
      */
     getCommonAncestor() {
         return this.start.getCommonAncestor(this.end);
@@ -486,8 +465,6 @@ export default class Range extends TypeCheckable {
      * Returns an {@link module:engine/model/element~Element Element} contained by the range.
      * The element will be returned when it is the **only** node within the range and **fully–contained**
      * at the same time.
-     *
-     * @returns {module:engine/model/element~Element|null}
      */
     getContainedElement() {
         if (this.isCollapsed) {
@@ -503,7 +480,7 @@ export default class Range extends TypeCheckable {
     /**
      * Converts `Range` to plain object and returns it.
      *
-     * @returns {Object} `Node` converted to plain object.
+     * @returns `Node` converted to plain object.
      */
     toJSON() {
         return {
@@ -513,8 +490,6 @@ export default class Range extends TypeCheckable {
     }
     /**
      * Returns a new range that is equal to current range.
-     *
-     * @returns {module:engine/model/range~Range}
      */
     clone() {
         return new this.constructor(this.start, this.end);
@@ -525,9 +500,6 @@ export default class Range extends TypeCheckable {
      * One or more ranges may be returned as a result of this transformation.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/operation/insertoperation~InsertOperation} operation
-     * @returns {Array.<module:engine/model/range~Range>}
      */
     _getTransformedByInsertOperation(operation, spread = false) {
         return this._getTransformedByInsertion(operation.position, operation.howMany, spread);
@@ -538,9 +510,6 @@ export default class Range extends TypeCheckable {
      * One or more ranges may be returned as a result of this transformation.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/operation/moveoperation~MoveOperation} operation
-     * @returns {Array.<module:engine/model/range~Range>}
      */
     _getTransformedByMoveOperation(operation, spread = false) {
         const sourcePosition = operation.sourcePosition;
@@ -554,9 +523,6 @@ export default class Range extends TypeCheckable {
      * Always one range is returned. The transformation is done in a way to not break the range.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/operation/splitoperation~SplitOperation} operation
-     * @returns {module:engine/model/range~Range}
      */
     _getTransformedBySplitOperation(operation) {
         const start = this.start._getTransformedBySplitOperation(operation);
@@ -578,9 +544,6 @@ export default class Range extends TypeCheckable {
      * Always one range is returned. The transformation is done in a way to not break the range.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/operation/mergeoperation~MergeOperation} operation
-     * @returns {module:engine/model/range~Range}
      */
     _getTransformedByMergeOperation(operation) {
         // Special case when the marker is set on "the closing tag" of an element. Marker can be set like that during
@@ -655,29 +618,30 @@ export default class Range extends TypeCheckable {
      *
      * Examples:
      *
-     *		let range = model.createRange(
-     *			model.createPositionFromPath( root, [ 2, 7 ] ),
-     *			model.createPositionFromPath( root, [ 4, 0, 1 ] )
-     *		);
-     *		let transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 1 ] ), 2 );
-     *		// transformed array has one range from [ 4, 7 ] to [ 6, 0, 1 ]
+     * ```ts
+     * let range = model.createRange(
+     * 	model.createPositionFromPath( root, [ 2, 7 ] ),
+     * 	model.createPositionFromPath( root, [ 4, 0, 1 ] )
+     * );
+     * let transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 1 ] ), 2 );
+     * // transformed array has one range from [ 4, 7 ] to [ 6, 0, 1 ]
      *
-     *		transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 4, 0, 0 ] ), 4 );
-     *		// transformed array has one range from [ 2, 7 ] to [ 4, 0, 5 ]
+     * transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 4, 0, 0 ] ), 4 );
+     * // transformed array has one range from [ 2, 7 ] to [ 4, 0, 5 ]
      *
-     *		transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 3, 2 ] ), 4 );
-     *		// transformed array has one range, which is equal to original range
+     * transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 3, 2 ] ), 4 );
+     * // transformed array has one range, which is equal to original range
      *
-     *		transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 3, 2 ] ), 4, true );
-     *		// transformed array has two ranges: from [ 2, 7 ] to [ 3, 2 ] and from [ 3, 6 ] to [ 4, 0, 1 ]
+     * transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 3, 2 ] ), 4, true );
+     * // transformed array has two ranges: from [ 2, 7 ] to [ 3, 2 ] and from [ 3, 6 ] to [ 4, 0, 1 ]
+     * ```
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/position~Position} insertPosition Position where nodes are inserted.
-     * @param {Number} howMany How many nodes are inserted.
-     * @param {Boolean} [spread] Flag indicating whether this {~Range range} should be spread if insertion
+     * @param insertPosition Position where nodes are inserted.
+     * @param howMany How many nodes are inserted.
+     * @param spread Flag indicating whether this {~Range range} should be spread if insertion
      * was inside the range. Defaults to `false`.
-     * @returns {Array.<module:engine/model/range~Range>} Result of the transformation.
+     * @returns Result of the transformation.
      */
     _getTransformedByInsertion(insertPosition, howMany, spread = false) {
         if (spread && this.containsPosition(insertPosition)) {
@@ -701,12 +665,11 @@ export default class Range extends TypeCheckable {
      * {@link ~Range range} by moving `howMany` nodes from `sourcePosition` to `targetPosition`.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/position~Position} sourcePosition Position from which nodes are moved.
-     * @param {module:engine/model/position~Position} targetPosition Position to where nodes are moved.
-     * @param {Number} howMany How many nodes are moved.
-     * @param {Boolean} [spread=false] Whether the range should be spread if the move points inside the range.
-     * @returns {Array.<module:engine/model/range~Range>} Result of the transformation.
+     * @param sourcePosition Position from which nodes are moved.
+     * @param targetPosition Position to where nodes are moved.
+     * @param howMany How many nodes are moved.
+     * @param spread Whether the range should be spread if the move points inside the range.
+     * @returns  Result of the transformation.
      */
     _getTransformedByMove(sourcePosition, targetPosition, howMany, spread = false) {
         // Special case for transforming a collapsed range. Just transform it like a position.
@@ -773,10 +736,9 @@ export default class Range extends TypeCheckable {
      * If the deleted range contains transformed range, `null` will be returned.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/position~Position} deletionPosition Position from which nodes are removed.
-     * @param {Number} howMany How many nodes are removed.
-     * @returns {module:engine/model/range~Range|null} Result of the transformation.
+     * @param deletionPosition Position from which nodes are removed.
+     * @param howMany How many nodes are removed.
+     * @returns Result of the transformation.
      */
     _getTransformedByDeletion(deletePosition, howMany) {
         let newStart = this.start._getTransformedByDeletion(deletePosition, howMany);
@@ -797,10 +759,8 @@ export default class Range extends TypeCheckable {
      * given `shift`. If `shift` is a negative value, shifted position is treated as the beginning of the range.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/position~Position} position Beginning of the range.
-     * @param {Number} shift How long the range should be.
-     * @returns {module:engine/model/range~Range}
+     * @param position Beginning of the range.
+     * @param shift How long the range should be.
      */
     static _createFromPositionAndShift(position, shift) {
         const start = position;
@@ -812,9 +772,7 @@ export default class Range extends TypeCheckable {
      * that element and ends after the last child of that element.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/element~Element} element Element which is a parent for the range.
-     * @returns {module:engine/model/range~Range}
+     * @param element Element which is a parent for the range.
      */
     static _createIn(element) {
         return new this(Position._createAt(element, 0), Position._createAt(element, element.maxOffset));
@@ -823,9 +781,6 @@ export default class Range extends TypeCheckable {
      * Creates a range that starts before given {@link module:engine/model/item~Item model item} and ends after it.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/item~Item} item
-     * @returns {module:engine/model/range~Range}
      */
     static _createOn(item) {
         return this._createFromPositionAndShift(Position._createBefore(item), item.offsetSize);
@@ -837,15 +792,16 @@ export default class Range extends TypeCheckable {
      * The first range from the array is a reference range. If other ranges start or end on the exactly same position where
      * the reference range, they get combined into one range.
      *
-     *		[  ][]  [    ][ ][             ][ ][]  [  ]  // Passed ranges, shown sorted
-     *		[    ]                                       // The result of the function if the first range was a reference range.
-     *	            [                           ]        // The result of the function if the third-to-seventh range was a reference range.
-     *	                                           [  ]  // The result of the function if the last range was a reference range.
+     * ```
+     * [  ][]  [    ][ ][             ][ ][]  [  ]  // Passed ranges, shown sorted
+     * [    ]                                       // The result of the function if the first range was a reference range.
+     *         [                           ]        // The result of the function if the third-to-seventh range was a reference range.
+     *                                        [  ]  // The result of the function if the last range was a reference range.
+     * ```
      *
      * @internal
-     * @protected
-     * @param {Array.<module:engine/model/range~Range>} ranges Ranges to combine.
-     * @returns {module:engine/model/range~Range} Combined range.
+     * @param ranges Ranges to combine.
+     * @returns Combined range.
      */
     static _createFromRanges(ranges) {
         if (ranges.length === 0) {
@@ -904,28 +860,16 @@ export default class Range extends TypeCheckable {
     /**
      * Creates a `Range` instance from given plain object (i.e. parsed JSON string).
      *
-     * @param {Object} json Plain object to be converted to `Range`.
-     * @param {module:engine/model/document~Document} doc Document object that will be range owner.
-     * @returns {module:engine/model/range~Range} `Range` instance created using given plain object.
+     * @param json Plain object to be converted to `Range`.
+     * @param doc Document object that will be range owner.
+     * @returns `Range` instance created using given plain object.
      */
     static fromJSON(json, doc) {
         return new this(Position.fromJSON(json.start, doc), Position.fromJSON(json.end, doc));
     }
 }
-/**
- * Checks whether this object is of the given.
- *
- *		range.is( 'range' ); // -> true
- *		range.is( 'model:range' ); // -> true
- *
- *		range.is( 'view:range' ); // -> false
- *		range.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.
 Range.prototype.is = function (type) {
     return type === 'range' || type === 'model:range';
 };