@ckeditor/ckeditor5-engine 35.3.2 → 36.0.0

package/src/model/operation/transform.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
  */
 import InsertOperation from './insertoperation';
@@ -13,7 +13,7 @@ import SplitOperation from './splitoperation';
 import NoOperation from './nooperation';
 import Range from '../range';
 import Position from '../position';
-import compareArrays from '@ckeditor/ckeditor5-utils/src/comparearrays';
+import { compareArrays } from '@ckeditor/ckeditor5-utils';
 const transformations = new Map();
 /**
  * @module engine/model/operation/transform
@@ -31,10 +31,7 @@ const transformations = new Map();
  * The `transformationFunction` should return transformation result, which is an array with one or multiple
  * {@link module:engine/model/operation/operation~Operation operation} instances.
  *
- * @protected
- * @param {Function} OperationA
- * @param {Function} OperationB
- * @param {Function} transformationFunction Function to use for transforming.
+ * @param transformationFunction Function to use for transforming.
  */
 function setTransformation(OperationA, OperationB, transformationFunction) {
     let aGroup = transformations.get(OperationA);
@@ -51,10 +48,7 @@ function setTransformation(OperationA, OperationB, transformationFunction) {
  * is returned. This means that if no transformation was set, the `OperationA` instance will not change when transformed
  * by the `OperationB` instance.
  *
- * @private
- * @param {Function} OperationA
- * @param {Function} OperationB
- * @returns {Function} Function set to transform an instance of `OperationA` by an instance of `OperationB`.
+ * @returns Function set to transform an instance of `OperationA` by an instance of `OperationB`.
  */
 function getTransformation(OperationA, OperationB) {
     const aGroup = transformations.get(OperationA);
@@ -65,10 +59,6 @@ function getTransformation(OperationA, OperationB) {
 }
 /**
  * A transformation function that only clones operation to transform, without changing it.
- *
- * @private
- * @param {module:engine/model/operation/operation~Operation} a Operation to transform.
- * @returns {Array.<module:engine/model/operation/operation~Operation>}
  */
 function noUpdateTransformation(a) {
     return [a];
@@ -76,10 +66,10 @@ function noUpdateTransformation(a) {
 /**
  * Transforms operation `a` by operation `b`.
  *
- * @param {module:engine/model/operation/operation~Operation} a Operation to be transformed.
- * @param {module:engine/model/operation/operation~Operation} b Operation to transform by.
- * @param {module:engine/model/operation/transform~TransformationContext} [context] Transformation context for this transformation.
- * @returns {Array.<module:engine/model/operation/operation~Operation>} Transformation result.
+ * @param a Operation to be transformed.
+ * @param b Operation to transform by.
+ * @param context Transformation context for this transformation.
+ * @returns Transformation result.
  */
 export function transform(a, b, context = {}) {
     const transformationFunction = getTransformation(a.constructor, b.constructor);
@@ -123,22 +113,17 @@ export function transform(a, b, context = {}) {
  * * transformed `operationsA` start from `9` and there are `3` of them, so the last will have `baseVersion` equal to `11`,
  * * transformed `operationsB` start from `7` and there are `5` of them, so the last will have `baseVersion` equal to `11`.
  *
- * @param {Array.<module:engine/model/operation/operation~Operation>} operationsA
- * @param {Array.<module:engine/model/operation/operation~Operation>} operationsB
- * @param {Object} options Additional transformation options.
- * @param {module:engine/model/document~Document} options.document Document which the operations change.
- * @param {Boolean} [options.useRelations=false] Whether during transformation relations should be used (used during undo for
- * better conflict resolution).
- * @param {Boolean} [options.padWithNoOps=false] Whether additional {@link module:engine/model/operation/nooperation~NoOperation}s
+ * @param operationsA
+ * @param operationsB
+ * @param options Additional transformation options.
+ * @param options.document Document which the operations change.
+ * @param options.useRelations Whether during transformation relations should be used (used during undo for better conflict resolution).
+ * @param options.padWithNoOps Whether additional {@link module:engine/model/operation/nooperation~NoOperation}s
  * should be added to the transformation results to force the same last base version for both transformed sets (in case
  * if some operations got broken into multiple operations during transformation).
- * @param {Boolean} [options.forceWeakRemove] If set to `false`, remove operation will be always stronger than move operation,
+ * @param options.forceWeakRemove If set to `false`, remove operation will be always stronger than move operation,
  * so the removed nodes won't end up back in the document root. When set to `true`, context data will be used.
- * @returns {Object} Transformation result.
- * @returns {Array.<module:engine/model/operation/operation~Operation>} return.operationsA Transformed `operationsA`.
- * @returns {Array.<module:engine/model/operation/operation~Operation>} return.operationsB Transformed `operationsB`.
- * @returns {Map} return.originalOperations A map that links transformed operations to original operations. The keys are the transformed
- * operations and the values are the original operations from the input (`operationsA` and `operationsB`).
+ * @returns Transformation result.
  */
 export function transformSets(operationsA, operationsB, options) {
     // Create new arrays so the originally passed arguments are not changed.
@@ -349,16 +334,20 @@ export function transformSets(operationsA, operationsB, options) {
     updateBaseVersions(operationsB, data.nextBaseVersionA);
     return { operationsA, operationsB, originalOperations };
 }
-// Gathers additional data about operations processed during transformation. Can be used to obtain contextual information
-// about two operations that are about to be transformed. This contextual information can be used for better conflict resolution.
+/**
+ * Gathers additional data about operations processed during transformation. Can be used to obtain contextual information
+ * about two operations that are about to be transformed. This contextual information can be used for better conflict resolution.
+ */
 class ContextFactory {
-    // Creates `ContextFactory` instance.
-    //
-    // @param {module:engine/model/document~Document} document Document which the operations change.
-    // @param {Boolean} useRelations Whether during transformation relations should be used (used during undo for
-    // better conflict resolution).
-    // @param {Boolean} [forceWeakRemove=false] If set to `false`, remove operation will be always stronger than move operation,
-    // so the removed nodes won't end up back in the document root. When set to `true`, context data will be used.
+    /**
+     * Creates `ContextFactory` instance.
+     *
+     * @param document Document which the operations change.
+     * @param useRelations Whether during transformation relations should be used (used during undo for
+     * better conflict resolution).
+     * @param forceWeakRemove If set to `false`, remove operation will be always stronger than move operation,
+     * so the removed nodes won't end up back in the document root. When set to `true`, context data will be used.
+     */
     constructor(document, useRelations, forceWeakRemove = false) {
         // For each operation that is created during transformation process, we keep a reference to the original operation
         // which it comes from. The original operation works as a kind of "identifier". Every contextual information
@@ -376,36 +365,34 @@ class ContextFactory {
         // we keep relations between them.
         this._relations = new Map();
     }
-    // Sets "original operation" for given operations.
-    //
-    // During transformation process, operations are cloned, then changed, then processed again, sometimes broken into two
-    // or multiple operations. When gathering additional data it is important that all operations can be somehow linked
-    // so a cloned and transformed "version" still kept track of the data assigned earlier to it.
-    //
-    // The original operation object will be used as such an universal linking id. Throughout the transformation process
-    // all cloned operations will refer to "the original operation" when storing and reading additional data.
-    //
-    // If `takeFrom` is not set, each operation from `operations` array will be assigned itself as "the original operation".
-    // This should be used as an initialization step.
-    //
-    // If `takeFrom` is set, each operation from `operations` will be assigned the same original operation as assigned
-    // for `takeFrom` operation. This should be used to update original operations. It should be used in a way that
-    // `operations` are the result of `takeFrom` transformation to ensure proper "original operation propagation".
-    //
-    // @param {Array.<module:engine/model/operation/operation~Operation>} operations
-    // @param {module:engine/model/operation/operation~Operation|null} [takeFrom=null]
+    /**
+     * Sets "original operation" for given operations.
+     *
+     * During transformation process, operations are cloned, then changed, then processed again, sometimes broken into two
+     * or multiple operations. When gathering additional data it is important that all operations can be somehow linked
+     * so a cloned and transformed "version" still kept track of the data assigned earlier to it.
+     *
+     * The original operation object will be used as such an universal linking id. Throughout the transformation process
+     * all cloned operations will refer to "the original operation" when storing and reading additional data.
+     *
+     * If `takeFrom` is not set, each operation from `operations` array will be assigned itself as "the original operation".
+     * This should be used as an initialization step.
+     *
+     * If `takeFrom` is set, each operation from `operations` will be assigned the same original operation as assigned
+     * for `takeFrom` operation. This should be used to update original operations. It should be used in a way that
+     * `operations` are the result of `takeFrom` transformation to ensure proper "original operation propagation".
+     */
     setOriginalOperations(operations, takeFrom = null) {
         const originalOperation = takeFrom ? this.originalOperations.get(takeFrom) : null;
         for (const operation of operations) {
             this.originalOperations.set(operation, originalOperation || operation);
         }
     }
-    // Saves a relation between operations `opA` and `opB`.
-    //
-    // Relations are then later used to help solve conflicts when operations are transformed.
-    //
-    // @param {module:engine/model/operation/operation~Operation} opA
-    // @param {module:engine/model/operation/operation~Operation} opB
+    /**
+     * Saves a relation between operations `opA` and `opB`.
+     *
+     * Relations are then later used to help solve conflicts when operations are transformed.
+     */
     updateRelation(opA, opB) {
         // The use of relations is described in a bigger detail in transformation functions.
         //
@@ -507,11 +494,9 @@ class ContextFactory {
             }
         }
     }
-    // Evaluates and returns contextual information about two given operations `opA` and `opB` which are about to be transformed.
-    //
-    // @param {module:engine/model/operation/operation~Operation} opA
-    // @param {module:engine/model/operation/operation~Operation} opB
-    // @returns {module:engine/model/operation/transform~TransformationContext}
+    /**
+     * Evaluates and returns contextual information about two given operations `opA` and `opB` which are about to be transformed.
+     */
     getContext(opA, opB, aIsStrong) {
         return {
             aIsStrong,
@@ -522,12 +507,11 @@ class ContextFactory {
             forceWeakRemove: this._forceWeakRemove
         };
     }
-    // Returns whether given operation `op` has already been undone.
-    //
-    // Information whether an operation was undone gives more context when making a decision when two operations are in conflict.
-    //
-    // @param {module:engine/model/operation/operation~Operation} op
-    // @returns {Boolean}
+    /**
+     * Returns whether given operation `op` has already been undone.
+     *
+     * Information whether an operation was undone gives more context when making a decision when two operations are in conflict.
+     */
     _wasUndone(op) {
         // For `op`, get its original operation. After all, if `op` is a clone (or even transformed clone) of another
         // operation, literally `op` couldn't be undone. It was just generated. If anything, it was the operation it origins
@@ -536,30 +520,28 @@ class ContextFactory {
         // And check with the document if the original operation was undone.
         return originalOp.wasUndone || this._history.isUndoneOperation(originalOp);
     }
-    // Returns a relation between `opA` and an operation which is undone by `opB`. This can be `String` value if a relation
-    // was set earlier or `null` if there was no relation between those operations.
-    //
-    // This is a little tricky to understand, so let's compare it to `ContextFactory#_wasUndone`.
-    //
-    // When `wasUndone( opB )` is used, we check if the `opB` has already been undone. It is obvious, that the
-    // undoing operation must happen after the undone operation. So, essentially, we have `opB`, we take document history,
-    // we look forward in the future and ask if in that future `opB` was undone.
-    //
-    // Relations is a backward process to `wasUndone()`.
-    //
-    // Long story short - using relations is asking what happened in the past. Looking back. This time we have an undoing
-    // operation `opB` which has undone some other operation. When there is a transformation `opA` x `opB` and there is
-    // a conflict to solve and `opB` is an undoing operation, we can look back in the history and see what was a relation
-    // between `opA` and the operation which `opB` undone. Basing on that relation from the past, we can now make
-    // a better decision when resolving a conflict between two operations, because we know more about the context of
-    // those two operations.
-    //
-    // This is why this function does not return a relation directly between `opA` and `opB` because we need to look
-    // back to search for a meaningful contextual information.
-    //
-    // @param {module:engine/model/operation/operation~Operation} opA
-    // @param {module:engine/model/operation/operation~Operation} opB
-    // @returns {String|null}
+    /**
+     * Returns a relation between `opA` and an operation which is undone by `opB`. This can be `String` value if a relation
+     * was set earlier or `null` if there was no relation between those operations.
+     *
+     * This is a little tricky to understand, so let's compare it to `ContextFactory#_wasUndone`.
+     *
+     * When `wasUndone( opB )` is used, we check if the `opB` has already been undone. It is obvious, that the
+     * undoing operation must happen after the undone operation. So, essentially, we have `opB`, we take document history,
+     * we look forward in the future and ask if in that future `opB` was undone.
+     *
+     * Relations is a backward process to `wasUndone()`.
+     *
+     * Long story short - using relations is asking what happened in the past. Looking back. This time we have an undoing
+     * operation `opB` which has undone some other operation. When there is a transformation `opA` x `opB` and there is
+     * a conflict to solve and `opB` is an undoing operation, we can look back in the history and see what was a relation
+     * between `opA` and the operation which `opB` undone. Basing on that relation from the past, we can now make
+     * a better decision when resolving a conflict between two operations, because we know more about the context of
+     * those two operations.
+     *
+     * This is why this function does not return a relation directly between `opA` and `opB` because we need to look
+     * back to search for a meaningful contextual information.
+     */
     _getRelation(opA, opB) {
         // Get the original operation. Similarly as in `wasUndone()` it is used as an universal identifier for stored data.
         const origB = this.originalOperations.get(opB);
@@ -576,12 +558,9 @@ class ContextFactory {
         }
         return null;
     }
-    // Helper function for `ContextFactory#updateRelations`.
-    //
-    // @private
-    // @param {module:engine/model/operation/operation~Operation} opA
-    // @param {module:engine/model/operation/operation~Operation} opB
-    // @param {String} relation
+    /**
+     * Helper function for `ContextFactory#updateRelations`.
+     */
     _setRelation(opA, opB, relation) {
         // As always, setting is for original operations, not the clones/transformed operations.
         const origA = this.originalOperations.get(opA);
@@ -601,9 +580,8 @@ class ContextFactory {
  * The function simply sets `baseVersion` as a base version of the first passed operation and then increments it for
  * each following operation in `operations`.
  *
- * @private
- * @param {Array.<module:engine/model/operation/operation~Operation>} operations Operations to update.
- * @param {Number} baseVersion Base version to set for the first operation in `operations`.
+ * @param operations Operations to update.
+ * @param baseVersion Base version to set for the first operation in `operations`.
  */
 function updateBaseVersions(operations, baseVersion) {
     for (const operation of operations) {
@@ -612,10 +590,6 @@ function updateBaseVersions(operations, baseVersion) {
 }
 /**
  * Adds `howMany` instances of {@link module:engine/model/operation/nooperation~NoOperation} to `operations` set.
- *
- * @private
- * @param {Array.<module:engine/model/operation/operation~Operation>} operations
- * @param {Number} howMany
  */
 function padWithNoOps(operations, howMany) {
     for (let i = 0; i < howMany; i++) {
@@ -730,12 +704,6 @@ setTransformation(AttributeOperation, InsertOperation, (a, b) => {
  *
  * For given `insertOperation` it checks the inserted node if it has an attribute `key` set to a value different
  * than `newValue`. If so, it generates an `AttributeOperation` which changes the value of `key` attribute to `newValue`.
- *
- * @private
- * @param {module:engine/model/operation/insertoperation~InsertOperation} insertOperation
- * @param {String} key
- * @param {*} newValue
- * @returns {module:engine/model/operation/attributeoperation~AttributeOperation|null}
  */
 function _getComplementaryAttributeOperations(insertOperation, key, newValue) {
     const nodes = insertOperation.nodes;
@@ -774,20 +742,17 @@ setTransformation(AttributeOperation, MoveOperation, (a, b) => {
     // Create `AttributeOperation`s out of the ranges.
     return ranges.map(range => new AttributeOperation(range, a.key, a.oldValue, a.newValue, a.baseVersion));
 });
-// Helper function for `AttributeOperation` x `MoveOperation` transformation.
-//
-// Takes the passed `range` and transforms it by move operation `moveOp` in a specific way. Only top-level nodes of `range`
-// are considered to be in the range. If move operation moves nodes deep from inside of the range, those nodes won't
-// be included in the result. In other words, top-level nodes of the ranges from the result are exactly the same as
-// top-level nodes of the original `range`.
-//
-// This is important for `AttributeOperation` because, for its range, it changes only the top-level nodes. So we need to
-// track only how those nodes have been affected by `MoveOperation`.
-//
-// @private
-// @param {module:engine/model/range~Range} range
-// @param {module:engine/model/operation/moveoperation~MoveOperation} moveOp
-// @returns {Array.<module:engine/model/range~Range>}
+/**
+ * Helper function for `AttributeOperation` x `MoveOperation` transformation.
+ *
+ * Takes the passed `range` and transforms it by move operation `moveOp` in a specific way. Only top-level nodes of `range`
+ * are considered to be in the range. If move operation moves nodes deep from inside of the range, those nodes won't
+ * be included in the result. In other words, top-level nodes of the ranges from the result are exactly the same as
+ * top-level nodes of the original `range`.
+ *
+ * This is important for `AttributeOperation` because, for its range, it changes only the top-level nodes. So we need to
+ * track only how those nodes have been affected by `MoveOperation`.
+ */
 function _breakRangeByMoveOperation(range, moveOp) {
     const moveRange = Range._createFromPositionAndShift(moveOp.sourcePosition, moveOp.howMany);
     // We are transforming `range` (original range) by `moveRange` (range moved by move operation). As usual when it comes to
@@ -1963,28 +1928,22 @@ setTransformation(SplitOperation, SplitOperation, (a, b, context) => {
     a.insertionPosition = SplitOperation.getInsertionPosition(a.splitPosition);
     return [a];
 });
-// Checks whether `MoveOperation` `targetPosition` is inside a node from the moved range of the other `MoveOperation`.
-//
-// @private
-// @param {module:engine/model/operation/moveoperation~MoveOperation} a
-// @param {module:engine/model/operation/moveoperation~MoveOperation} b
-// @returns {Boolean}
+/**
+ * Checks whether `MoveOperation` `targetPosition` is inside a node from the moved range of the other `MoveOperation`.
+ */
 function _moveTargetIntoMovedRange(a, b) {
     return a.targetPosition._getTransformedByDeletion(b.sourcePosition, b.howMany) === null;
 }
-// Helper function for `MoveOperation` x `MoveOperation` transformation. Converts given ranges and target position to
-// move operations and returns them.
-//
-// Ranges and target position will be transformed on-the-fly when generating operations.
-//
-// Given `ranges` should be in the order of how they were in the original transformed operation.
-//
-// Given `targetPosition` is the target position of the first range from `ranges`.
-//
-// @private
-// @param {Array.<module:engine/model/range~Range>} ranges
-// @param {module:engine/model/position~Position} targetPosition
-// @returns {Array.<module:engine/model/operation/moveoperation~MoveOperation>}
+/**
+ * Helper function for `MoveOperation` x `MoveOperation` transformation. Converts given ranges and target position to
+ * move operations and returns them.
+ *
+ * Ranges and target position will be transformed on-the-fly when generating operations.
+ *
+ * Given `ranges` should be in the order of how they were in the original transformed operation.
+ *
+ * Given `targetPosition` is the target position of the first range from `ranges`.
+ */
 function _makeMoveOperationsFromRanges(ranges, targetPosition) {
     // At this moment we have some ranges and a target position, to which those ranges should be moved.
     // Order in `ranges` array is the go-to order of after transformation.

package/src/model/operation/utils.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
  */
 /**
@@ -9,24 +9,14 @@ import Node from '../node';
 import Range from '../range';
 import Text from '../text';
 import TextProxy from '../textproxy';
-import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
-import isIterable from '@ckeditor/ckeditor5-utils/src/isiterable';
-/**
- * Contains functions used for composing model tree by {@link module:engine/model/operation/operation~Operation operations}.
- * Those functions are built on top of {@link module:engine/model/node~Node node}, and it's child classes', APIs.
- *
- * @protected
- * @namespace utils
- */
+import { CKEditorError, isIterable } from '@ckeditor/ckeditor5-utils';
 /**
  * Inserts given nodes at given position.
  *
  * @internal
- * @protected
- * @function module:engine/model/operation/utils~utils.insert
- * @param {module:engine/model/position~Position} position Position at which nodes should be inserted.
- * @param {module:engine/model/node~NodeSet} normalizedNodes Nodes to insert.
- * @returns {module:engine/model/range~Range} Range spanning over inserted elements.
+ * @param position Position at which nodes should be inserted.
+ * @param normalizedNodes Nodes to insert.
+ * @returns Range spanning over inserted elements.
  */
 export function _insert(position, nodes) {
     const normalizedNodes = _normalizeNodes(nodes);
@@ -48,10 +38,7 @@ export function _insert(position, nodes) {
  * Removed nodes in given range. Only {@link module:engine/model/range~Range#isFlat flat} ranges are accepted.
  *
  * @internal
- * @protected
- * @function module:engine/model/operation/utils~utils._remove
- * @param {module:engine/model/range~Range} range Range containing nodes to remove.
- * @returns {Array.<module:engine/model/node~Node>}
+ * @param range Range containing nodes to remove.
  */
 export function _remove(range) {
     if (!range.isFlat) {
@@ -77,11 +64,9 @@ export function _remove(range) {
  * Moves nodes in given range to given target position. Only {@link module:engine/model/range~Range#isFlat flat} ranges are accepted.
  *
  * @internal
- * @protected
- * @function module:engine/model/operation/utils~utils.move
- * @param {module:engine/model/range~Range} sourceRange Range containing nodes to move.
- * @param {module:engine/model/position~Position} targetPosition Position to which nodes should be moved.
- * @returns {module:engine/model/range~Range} Range containing moved nodes.
+ * @param sourceRange Range containing nodes to move.
+ * @param targetPosition Position to which nodes should be moved.
+ * @returns Range containing moved nodes.
  */
 export function _move(sourceRange, targetPosition) {
     if (!sourceRange.isFlat) {
@@ -102,11 +87,9 @@ export function _move(sourceRange, targetPosition) {
  * Sets given attribute on nodes in given range. The attributes are only set on top-level nodes of the range, not on its children.
  *
  * @internal
- * @protected
- * @function module:engine/model/operation/utils~utils._setAttribute
- * @param {module:engine/model/range~Range} range Range containing nodes that should have the attribute set. Must be a flat range.
- * @param {String} key Key of attribute to set.
- * @param {*} value Attribute value.
+ * @param range Range containing nodes that should have the attribute set. Must be a flat range.
+ * @param key Key of attribute to set.
+ * @param value Attribute value.
  */
 export function _setAttribute(range, key, value) {
     // Range might start or end in text nodes, so we have to split them.
@@ -134,10 +117,9 @@ export function _setAttribute(range, key, value) {
  * Normalizes given object or an array of objects to an array of {@link module:engine/model/node~Node nodes}. See
  * {@link module:engine/model/node~NodeSet NodeSet} for details on how normalization is performed.
  *
- * @protected
- * @function module:engine/model/operation/utils~utils.normalizeNodes
- * @param {module:engine/model/node~NodeSet} nodes Objects to normalize.
- * @returns {Array.<module:engine/model/node~Node>} Normalized nodes.
+ * @internal
+ * @param nodes Objects to normalize.
+ * @returns Normalized nodes.
  */
 export function _normalizeNodes(nodes) {
     const normalized = [];
@@ -171,14 +153,15 @@ export function _normalizeNodes(nodes) {
     }
     return normalized;
 }
-// Checks if nodes before and after given index in given element are {@link module:engine/model/text~Text text nodes} and
-// merges them into one node if they have same attributes.
-//
-// Merging is done by removing two text nodes and inserting a new text node containing data from both merged text nodes.
-//
-// @private
-// @param {module:engine/model/element~Element} element Parent element of nodes to merge.
-// @param {Number} index Index between nodes to merge.
+/**
+ * Checks if nodes before and after given index in given element are {@link module:engine/model/text~Text text nodes} and
+ * merges them into one node if they have same attributes.
+ *
+ * Merging is done by removing two text nodes and inserting a new text node containing data from both merged text nodes.
+ *
+ * @param element Parent element of nodes to merge.
+ * @param index Index between nodes to merge.
+ */
 function _mergeNodesAtIndex(element, index) {
     const nodeBefore = element.getChild(index - 1);
     const nodeAfter = element.getChild(index);
@@ -192,11 +175,12 @@ function _mergeNodesAtIndex(element, index) {
         element._insertChild(index - 1, mergedNode);
     }
 }
-// Checks if given position is in a text node, and if so, splits the text node in two text nodes, each of them
-// containing a part of original text node.
-//
-// @private
-// @param {module:engine/model/position~Position} position Position at which node should be split.
+/**
+ * Checks if given position is in a text node, and if so, splits the text node in two text nodes, each of them
+ * containing a part of original text node.
+ *
+ * @param position Position at which node should be split.
+ */
 function _splitNodeAtPosition(position) {
     const textNode = position.textNode;
     const element = position.parent;
@@ -209,12 +193,13 @@ function _splitNodeAtPosition(position) {
         element._insertChild(index, [firstPart, secondPart]);
     }
 }
-// Checks whether two given nodes have same attributes.
-//
-// @private
-// @param {module:engine/model/node~Node} nodeA Node to check.
-// @param {module:engine/model/node~Node} nodeB Node to check.
-// @returns {Boolean} `true` if nodes have same attributes, `false` otherwise.
+/**
+ * Checks whether two given nodes have same attributes.
+ *
+ * @param nodeA Node to check.
+ * @param nodeB Node to check.
+ * @returns `true` if nodes have same attributes, `false` otherwise.
+ */
 function _haveSameAttributes(nodeA, nodeB) {
     const iteratorA = nodeA.getAttributes();
     const iteratorB = nodeB.getAttributes();