@ckeditor/ckeditor5-engine 35.3.2 → 36.0.0

package/src/model/documentselection.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/documentselection
  */
@@ -11,11 +10,7 @@ import LiveRange from './liverange';
 import Selection from './selection';
 import Text from './text';
 import TextProxy from './textproxy';
-import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
-import Collection from '@ckeditor/ckeditor5-utils/src/collection';
-import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
-import toMap from '@ckeditor/ckeditor5-utils/src/tomap';
-import uid from '@ckeditor/ckeditor5-utils/src/uid';
+import { CKEditorError, Collection, EmitterMixin, toMap, uid } from '@ckeditor/ckeditor5-utils';
 const storePrefix = 'selection:';
 /**
  * `DocumentSelection` is a special selection which is used as the
@@ -40,33 +35,23 @@ const storePrefix = 'selection:';
  * that are inside {@link module:engine/model/documentfragment~DocumentFragment document fragment}.
  * If you need to represent a selection in document fragment,
  * use {@link module:engine/model/selection~Selection Selection class} instead.
- *
- * @mixes module:utils/emittermixin~EmitterMixin
  */
 export default class DocumentSelection extends EmitterMixin(TypeCheckable) {
     /**
      * Creates an empty live selection for given {@link module:engine/model/document~Document}.
      *
-     * @param {module:engine/model/document~Document} doc Document which owns this selection.
+     * @param doc Document which owns this selection.
      */
     constructor(doc) {
         super();
-        /**
-         * Selection used internally by that class (`DocumentSelection` is a proxy to that selection).
-         *
-         * @protected
-         */
         this._selection = new LiveSelection(doc);
         this._selection.delegate('change:range').to(this);
         this._selection.delegate('change:attribute').to(this);
         this._selection.delegate('change:marker').to(this);
     }
     /**
-     * Returns whether the selection is collapsed. Selection is collapsed when there is exactly one range which is
+     * Describes whether the selection is collapsed. Selection is collapsed when there is exactly one range which is
      * collapsed.
-     *
-     * @readonly
-     * @type {Boolean}
      */
     get isCollapsed() {
         return this._selection.isCollapsed;
@@ -80,8 +65,6 @@ export default class DocumentSelection extends EmitterMixin(TypeCheckable) {
      * Is set to `null` if there are no ranges in selection.
      *
      * @see #focus
-     * @readonly
-     * @type {module:engine/model/position~Position|null}
      */
     get anchor() {
         return this._selection.anchor;
@@ -92,17 +75,12 @@ export default class DocumentSelection extends EmitterMixin(TypeCheckable) {
      * Is set to `null` if there are no ranges in selection.
      *
      * @see #anchor
-     * @readonly
-     * @type {module:engine/model/position~Position|null}
      */
     get focus() {
         return this._selection.focus;
     }
     /**
-     * Returns number of ranges in selection.
-     *
-     * @readonly
-     * @type {Number}
+     * Number of ranges in selection.
      */
     get rangeCount() {
         return this._selection.rangeCount;
@@ -110,9 +88,6 @@ export default class DocumentSelection extends EmitterMixin(TypeCheckable) {
     /**
      * Describes whether `Documentselection` has own range(s) set, or if it is defaulted to
      * {@link module:engine/model/document~Document#_getDefaultRange document's default range}.
-     *
-     * @readonly
-     * @type {Boolean}
      */
     get hasOwnRange() {
         return this._selection.hasOwnRange;
@@ -131,9 +106,6 @@ export default class DocumentSelection extends EmitterMixin(TypeCheckable) {
      * Describes whether the gravity is overridden (using {@link module:engine/model/writer~Writer#overrideSelectionGravity}) or not.
      *
      * Note that the gravity remains overridden as long as will not be restored the same number of times as it was overridden.
-     *
-     * @readonly
-     * @returns {Boolean}
      */
     get isGravityOverridden() {
         return this._selection.isGravityOverridden;
@@ -143,9 +115,6 @@ export default class DocumentSelection extends EmitterMixin(TypeCheckable) {
      * Marker is a selection marker when selection range is inside the marker range.
      *
      * **Note**: Only markers from {@link ~DocumentSelection#observeMarkers observed markers groups} are collected.
-     *
-     * @readonly
-     * @type {module:utils/collection~Collection}
      */
     get markers() {
         return this._selection.markers;
@@ -154,15 +123,12 @@ export default class DocumentSelection extends EmitterMixin(TypeCheckable) {
      * Used for the compatibility with the {@link module:engine/model/selection~Selection#isEqual} method.
      *
      * @internal
-     * @protected
      */
     get _ranges() {
         return this._selection._ranges;
     }
     /**
      * Returns an iterable that iterates over copies of selection ranges.
-     *
-     * @returns {Iterable.<module:engine/model/range~Range>}
      */
     getRanges() {
         return this._selection.getRanges();
@@ -173,8 +139,6 @@ export default class DocumentSelection 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() {
         return this._selection.getFirstPosition();
@@ -185,8 +149,6 @@ export default class DocumentSelection 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() {
         return this._selection.getLastPosition();
@@ -198,8 +160,6 @@ export default class DocumentSelection 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() {
         return this._selection.getFirstRange();
@@ -211,8 +171,6 @@ export default class DocumentSelection 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() {
         return this._selection.getLastRange();
@@ -227,40 +185,48 @@ export default class DocumentSelection 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>
+     * ```
+     * <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>
+     * ```
+     * <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>]
+     * ```
+     * [<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>
+     * ```
+     * <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>}
+     * ```
+     * <paragraph>[a</paragraph>
+     * <paragraph>b</paragraph>
+     * <paragraph>]c</paragraph> // this block will not be returned
+     * ```
      */
     getSelectedBlocks() {
         return this._selection.getSelectedBlocks();
@@ -269,8 +235,6 @@ export default class DocumentSelection 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() {
         return this._selection.getSelectedElement();
@@ -282,9 +246,6 @@ export default class DocumentSelection 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) {
         return this._selection.containsEntireContent(element);
@@ -297,8 +258,6 @@ export default class DocumentSelection extends EmitterMixin(TypeCheckable) {
     }
     /**
      * Returns iterable that iterates over this selection's attribute keys.
-     *
-     * @returns {Iterable.<String>}
      */
     getAttributeKeys() {
         return this._selection.getAttributeKeys();
@@ -308,8 +267,6 @@ export default class DocumentSelection 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._selection.getAttributes();
@@ -317,8 +274,8 @@ export default class DocumentSelection 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._selection.getAttribute(key);
@@ -326,8 +283,8 @@ export default class DocumentSelection 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._selection.hasAttribute(key);
@@ -345,7 +302,7 @@ export default class DocumentSelection extends EmitterMixin(TypeCheckable) {
      *
      * See also {@link module:engine/model/markercollection~MarkerCollection#getMarkersGroup `MarkerCollection#getMarkersGroup()`}.
      *
-     * @param {String} prefixOrName The marker group prefix or marker name.
+     * @param prefixOrName The marker group prefix or marker name.
      */
     observeMarkers(prefixOrName) {
         this._selection.observeMarkers(prefixOrName);
@@ -359,9 +316,7 @@ export default class DocumentSelection extends EmitterMixin(TypeCheckable) {
      *
      * @see module:engine/model/writer~Writer#setSelectionFocus
      * @internal
-     * @protected
-     * @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
+     * @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) {
@@ -374,11 +329,6 @@ export default class DocumentSelection extends EmitterMixin(TypeCheckable) {
      *
      * @see module:engine/model/writer~Writer#setSelection
      * @internal
-     * @protected
-     * @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.
      */
     _setTo(...args) {
         this._selection.setTo(...args);
@@ -389,9 +339,8 @@ export default class DocumentSelection extends EmitterMixin(TypeCheckable) {
      *
      * @see module:engine/model/writer~Writer#setSelectionAttribute
      * @internal
-     * @protected
-     * @param {String} key Key of the attribute to set.
-     * @param {*} value Attribute value.
+     * @param key Key of the attribute to set.
+     * @param value Attribute value.
      */
     _setAttribute(key, value) {
         this._selection.setAttribute(key, value);
@@ -404,8 +353,7 @@ export default class DocumentSelection extends EmitterMixin(TypeCheckable) {
      *
      * @see module:engine/model/writer~Writer#removeSelectionAttribute
      * @internal
-     * @protected
-     * @param {String} key Key of the attribute to remove.
+     * @param key Key of the attribute to remove.
      */
     _removeAttribute(key) {
         this._selection.removeAttribute(key);
@@ -413,8 +361,7 @@ export default class DocumentSelection extends EmitterMixin(TypeCheckable) {
     /**
      * Returns an iterable that iterates through all selection attributes stored in current selection's parent.
      *
-     * @protected
-     * @returns {Iterable.<*>}
+     * @internal
      */
     _getStoredAttributes() {
         return this._selection.getStoredAttributes();
@@ -431,8 +378,7 @@ export default class DocumentSelection extends EmitterMixin(TypeCheckable) {
      *
      * @see module:engine/model/writer~Writer#overrideSelectionGravity
      * @internal
-     * @protected
-     * @returns {String} The unique id which allows restoring the gravity.
+     * @returns The unique id which allows restoring the gravity.
      */
     _overrideGravity() {
         return this._selection.overrideGravity();
@@ -446,8 +392,7 @@ export default class DocumentSelection extends EmitterMixin(TypeCheckable) {
      *
      * @see module:engine/model/writer~Writer#restoreSelectionGravity
      * @internal
-     * @protected
-     * @param {String} uid The unique id returned by {@link #_overrideGravity}.
+     * @param uid The unique id returned by {@link #_overrideGravity}.
      */
     _restoreGravity(uid) {
         this._selection.restoreGravity(uid);
@@ -456,9 +401,8 @@ export default class DocumentSelection extends EmitterMixin(TypeCheckable) {
      * Generates and returns an attribute key for selection attributes store, basing on original attribute key.
      *
      * @internal
-     * @protected
-     * @param {String} key Attribute key to convert.
-     * @returns {String} Converted attribute key, applicable for selection store.
+     * @param key Attribute key to convert.
+     * @returns Converted attribute key, applicable for selection store.
      */
     static _getStoreAttributeKey(key) {
         return storePrefix + key;
@@ -466,98 +410,74 @@ export default class DocumentSelection extends EmitterMixin(TypeCheckable) {
     /**
      * Checks whether the given attribute key is an attribute stored on an element.
      *
-     * @protected
-     * @param {String} key
-     * @returns {Boolean}
+     * @internal
      */
     static _isStoreAttributeKey(key) {
         return key.startsWith(storePrefix);
     }
 }
-/**
- * Checks whether this object is of the given type.
- *
- *		selection.is( 'selection' ); // -> true
- *		selection.is( 'documentSelection' ); // -> true
- *		selection.is( 'model:selection' ); // -> true
- *		selection.is( 'model:documentSelection' ); // -> true
- *
- *		selection.is( 'view:selection' ); // -> false
- *		selection.is( 'element' ); // -> false
- *		selection.is( 'node' ); // -> 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.
 DocumentSelection.prototype.is = function (type) {
     return type === 'selection' ||
         type == 'model:selection' ||
         type == 'documentSelection' ||
         type == 'model:documentSelection';
 };
-// `LiveSelection` is used internally by {@link module:engine/model/documentselection~DocumentSelection} and shouldn't be used directly.
-//
-// LiveSelection` is automatically updated upon changes in the {@link module:engine/model/document~Document document}
-// to always contain valid ranges. Its attributes are inherited from the text unless set explicitly.
-//
-// Differences between {@link module:engine/model/selection~Selection} and `LiveSelection` are:
-// * there is always a range in `LiveSelection` - even if no ranges were added there is a "default range"
-// present in the selection,
-// * ranges added to this selection updates automatically when the document changes,
-// * attributes of `LiveSelection` are updated automatically according to selection ranges.
-//
-// @extends module:engine/model/selection~Selection
-//
+/**
+ * `LiveSelection` is used internally by {@link module:engine/model/documentselection~DocumentSelection} and shouldn't be used directly.
+ *
+ * LiveSelection` is automatically updated upon changes in the {@link module:engine/model/document~Document document}
+ * to always contain valid ranges. Its attributes are inherited from the text unless set explicitly.
+ *
+ * Differences between {@link module:engine/model/selection~Selection} and `LiveSelection` are:
+ * * there is always a range in `LiveSelection` - even if no ranges were added there is a "default range"
+ * present in the selection,
+ * * ranges added to this selection updates automatically when the document changes,
+ * * attributes of `LiveSelection` are updated automatically according to selection ranges.
+ */
 class LiveSelection extends Selection {
-    // Creates an empty live selection for given {@link module:engine/model/document~Document}.
-    // @param {module:engine/model/document~Document} doc Document which owns this selection.
+    /**
+     * Creates an empty live selection for given {@link module:engine/model/document~Document}.
+     *
+     * @param doc Document which owns this selection.
+     */
     constructor(doc) {
         super();
-        // List of selection markers.
-        // Marker is a selection marker when selection range is inside the marker range.
-        //
-        // @type {module:utils/collection~Collection}
+        /**
+         * List of selection markers.
+         * Marker is a selection marker when selection range is inside the marker range.
+         */
         this.markers = new Collection({ idProperty: 'name' });
-        // Document which owns this selection.
-        //
-        // @protected
-        // @member {module:engine/model/model~Model}
-        this._model = doc.model;
-        // Document which owns this selection.
-        //
-        // @protected
-        // @member {module:engine/model/document~Document}
-        this._document = doc;
-        // Keeps mapping of attribute name to priority with which the attribute got modified (added/changed/removed)
-        // last time. Possible values of priority are: `'low'` and `'normal'`.
-        //
-        // Priorities are used by internal `LiveSelection` mechanisms. All attributes set using `LiveSelection`
-        // attributes API are set with `'normal'` priority.
-        //
-        // @private
-        // @member {Map} module:engine/model/liveselection~LiveSelection#_attributePriority
+        /**
+         * Keeps mapping of attribute name to priority with which the attribute got modified (added/changed/removed)
+         * last time. Possible values of priority are: `'low'` and `'normal'`.
+         *
+         * Priorities are used by internal `LiveSelection` mechanisms. All attributes set using `LiveSelection`
+         * attributes API are set with `'normal'` priority.
+         */
         this._attributePriority = new Map();
-        // Position to which the selection should be set if the last selection range was moved to the graveyard.
-        // @private
-        // @member {module:engine/model/position~Position} module:engine/model/liveselection~LiveSelection#_selectionRestorePosition
+        /**
+         * Position to which the selection should be set if the last selection range was moved to the graveyard.
+         */
         this._selectionRestorePosition = null;
-        // Flag that informs whether the selection ranges have changed. It is changed on true when `LiveRange#change:range` event is fired.
-        // @private
-        // @member {Array} module:engine/model/liveselection~LiveSelection#_hasChangedRange
+        /**
+         * Flag that informs whether the selection ranges have changed. It is changed on true when `LiveRange#change:range` event is fired.
+         */
         this._hasChangedRange = false;
-        // Each overriding gravity adds an UID to the set and each removal removes it.
-        // Gravity is overridden when there's at least one UID in the set.
-        // Gravity is restored when the set is empty.
-        // This is to prevent conflicts when gravity is overridden by more than one feature at the same time.
-        // @private
-        // @type {Set}
+        /**
+         * Each overriding gravity adds an UID to the set and each removal removes it.
+         * Gravity is overridden when there's at least one UID in the set.
+         * Gravity is restored when the set is empty.
+         * This is to prevent conflicts when gravity is overridden by more than one feature at the same time.
+         */
         this._overriddenGravityRegister = new Set();
-        // Prefixes of marker names that should affect `LiveSelection#markers` collection.
-        // @private
-        // @type {Set}
+        /**
+         * Prefixes of marker names that should affect `LiveSelection#markers` collection.
+         */
         this._observedMarkers = new Set();
+        this._model = doc.model;
+        this._document = doc;
         // Ensure selection is correct after each operation.
         this.listenTo(this._model, 'applyOperation', (evt, args) => {
             const operation = args[0];
@@ -602,23 +522,23 @@ class LiveSelection extends Selection {
     get rangeCount() {
         return this._ranges.length ? this._ranges.length : 1;
     }
-    // Describes whether `LiveSelection` has own range(s) set, or if it is defaulted to
-    // {@link module:engine/model/document~Document#_getDefaultRange document's default range}.
-    //
-    // @readonly
-    // @type {Boolean}
+    /**
+     * Describes whether `LiveSelection` has own range(s) set, or if it is defaulted to
+     * {@link module:engine/model/document~Document#_getDefaultRange document's default range}.
+     */
     get hasOwnRange() {
         return this._ranges.length > 0;
     }
-    // When set to `true` then selection attributes on node before the caret won't be taken
-    // into consideration while updating selection attributes.
-    //
-    // @protected
-    // @type {Boolean}
+    /**
+     * When set to `true` then selection attributes on node before the caret won't be taken
+     * into consideration while updating selection attributes.
+     */
     get isGravityOverridden() {
         return !!this._overriddenGravityRegister.size;
     }
-    // Unbinds all events previously bound by live selection.
+    /**
+     * Unbinds all events previously bound by live selection.
+     */
     destroy() {
         for (let i = 0; i < this._ranges.length; i++) {
             this._ranges[i].detach();
@@ -680,7 +600,7 @@ class LiveSelection extends Selection {
              * UID obtained from the {@link module:engine/model/writer~Writer#overrideSelectionGravity} to restore.
              *
              * @error document-selection-gravity-wrong-restore
-             * @param {String} uid The unique identifier returned by
+             * @param uid The unique identifier returned by
              * {@link module:engine/model/documentselection~DocumentSelection#_overrideGravity}.
              */
             throw new CKEditorError('document-selection-gravity-wrong-restore', this, { uid });
@@ -717,18 +637,17 @@ class LiveSelection extends Selection {
                  * starts or ends at incorrect position.
                  *
                  * @error document-selection-wrong-position
-                 * @param {module:engine/model/range~Range} range
+                 * @param range
                  */
                 throw new CKEditorError('document-selection-wrong-position', this, { range });
             }
         }
     }
-    // Prepares given range to be added to selection. Checks if it is correct,
-    // converts it to {@link module:engine/model/liverange~LiveRange LiveRange}
-    // and sets listeners listening to the range's change event.
-    //
-    // @private
-    // @param {module:engine/model/range~Range} range
+    /**
+     * Prepares given range to be added to selection. Checks if it is correct,
+     * converts it to {@link module:engine/model/liverange~LiveRange LiveRange}
+     * and sets listeners listening to the range's change event.
+     */
     _prepareRange(range) {
         this._checkRange(range);
         if (range.root == this._document.graveyard) {
@@ -819,11 +738,9 @@ class LiveSelection extends Selection {
             this.fire('change:marker', { oldMarkers, directChange: false });
         }
     }
-    // Updates this selection attributes according to its ranges and the {@link module:engine/model/document~Document model document}.
-    //
-    // @protected
-    // @param {Boolean} clearAll
-    // @fires change:attribute
+    /**
+     * Updates this selection attributes according to its ranges and the {@link module:engine/model/document~Document model document}.
+     */
     _updateAttributes(clearAll) {
         const newAttributes = toMap(this._getSurroundingAttributes());
         const oldAttributes = toMap(this.getAttributes());
@@ -862,15 +779,10 @@ class LiveSelection extends Selection {
             this.fire('change:attribute', { attributeKeys: changed, directChange: false });
         }
     }
-    // Internal method for setting `LiveSelection` attribute. Supports attribute priorities (through `directChange`
-    // parameter).
-    //
-    // @private
-    // @param {String} key Attribute key.
-    // @param {*} value Attribute value.
-    // @param {Boolean} [directChange=true] `true` if the change is caused by `Selection` API, `false` if change
-    // is caused by `Batch` API.
-    // @returns {Boolean} Whether value has changed.
+    /**
+     * Internal method for setting `LiveSelection` attribute. Supports attribute priorities (through `directChange`
+     * parameter).
+     */
     _setAttribute(key, value, directChange = true) {
         const priority = directChange ? 'normal' : 'low';
         if (priority == 'low' && this._attributePriority.get(key) == 'normal') {
@@ -887,18 +799,13 @@ class LiveSelection extends Selection {
         this._attributePriority.set(key, priority);
         return true;
     }
-    // Internal method for removing `LiveSelection` attribute. Supports attribute priorities (through `directChange`
-    // parameter).
-    //
-    // NOTE: Even if attribute is not present in the selection but is provided to this method, it's priority will
-    // be changed according to `directChange` parameter.
-    //
-    // @private
-    // @param {String} key Attribute key.
-    // @param {Boolean} [directChange=true] `true` if the change is caused by `Selection` API, `false` if change
-    // is caused by `Batch` API.
-    // @returns {Boolean} Whether attribute was removed. May not be true if such attributes didn't exist or the
-    // existing attribute had higher priority.
+    /**
+     * Internal method for removing `LiveSelection` attribute. Supports attribute priorities (through `directChange`
+     * parameter).
+     *
+     * NOTE: Even if attribute is not present in the selection but is provided to this method, it's priority will
+     * be changed according to `directChange` parameter.
+     */
     _removeAttribute(key, directChange = true) {
         const priority = directChange ? 'normal' : 'low';
         if (priority == 'low' && this._attributePriority.get(key) == 'normal') {
@@ -914,12 +821,10 @@ class LiveSelection extends Selection {
         this._attrs.delete(key);
         return true;
     }
-    // Internal method for setting multiple `LiveSelection` attributes. Supports attribute priorities (through
-    // `directChange` parameter).
-    //
-    // @private
-    // @param {Map.<String,*>} attrs Iterable object containing attributes to be set.
-    // @returns {Set.<String>} Changed attribute keys.
+    /**
+     * Internal method for setting multiple `LiveSelection` attributes. Supports attribute priorities (through
+     * `directChange` parameter).
+     */
     _setAttributesTo(attrs) {
         const changed = new Set();
         for (const [oldKey, oldValue] of this.getAttributes()) {
@@ -939,10 +844,9 @@ class LiveSelection extends Selection {
         }
         return changed;
     }
-    // Returns an iterable that iterates through all selection attributes stored in current selection's parent.
-    //
-    // @public
-    // @returns {Iterable.<*>}
+    /**
+     * Returns an iterable that iterates through all selection attributes stored in current selection's parent.
+     */
     *getStoredAttributes() {
         const selectionParent = this.getFirstPosition().parent;
         if (this.isCollapsed && selectionParent.isEmpty) {
@@ -954,12 +858,11 @@ class LiveSelection extends Selection {
             }
         }
     }
-    // Checks model text nodes that are closest to the selection's first position and returns attributes of first
-    // found element. If there are no text nodes in selection's first position parent, it returns selection
-    // attributes stored in that parent.
-    //
-    // @private
-    // @returns {Iterable.<*>} Collection of attributes.
+    /**
+     * Checks model text nodes that are closest to the selection's first position and returns attributes of first
+     * found element. If there are no text nodes in selection's first position parent, it returns selection
+     * attributes stored in that parent.
+     */
     _getSurroundingAttributes() {
         const position = this.getFirstPosition();
         const schema = this._model.schema;
@@ -1016,10 +919,10 @@ class LiveSelection extends Selection {
         }
         return attrs;
     }
-    // Fixes the selection after all its ranges got removed.
-    //
-    // @private
-    // @param {module:engine/model/position~Position} deletionPosition Position where the deletion happened.
+    /**
+     * Fixes the selection after all its ranges got removed.
+     * @param deletionPosition Position where the deletion happened.
+     */
     _fixGraveyardSelection(deletionPosition) {
         // Find a range that is a correct selection range and is closest to the position where the deletion happened.
         const selectionRange = this._model.schema.getNearestSelectionRange(deletionPosition);
@@ -1031,22 +934,20 @@ class LiveSelection extends Selection {
         // If nearest valid selection range cannot be found don't add any range. Selection will be set to the default range.
     }
 }
-// Helper function for {@link module:engine/model/liveselection~LiveSelection#_updateAttributes}.
-//
-// It takes model item, checks whether it is a text node (or text proxy) and, if so, returns it's attributes. If not, returns `null`.
-//
-// @param {module:engine/model/item~Item|null}  node
-// @returns {Boolean}
+/**
+ * Helper function for {@link module:engine/model/liveselection~LiveSelection#_updateAttributes}.
+ *
+ * It takes model item, checks whether it is a text node (or text proxy) and, if so, returns it's attributes. If not, returns `null`.
+ */
 function getAttrsIfCharacter(node) {
     if (node instanceof TextProxy || node instanceof Text) {
         return node.getAttributes();
     }
     return null;
 }
-// Removes selection attributes from element which is not empty anymore.
-//
-// @param {module:engine/model/model~Model} model
-// @param {module:engine/model/batch~Batch} batch
+/**
+ * Removes selection attributes from element which is not empty anymore.
+ */
 function clearAttributesStoredInElement(model, batch) {
     const differ = model.document.differ;
     for (const entry of differ.getChanges()) {