@ckeditor/ckeditor5-engine 35.3.2 → 36.0.0

package/src/model/writer.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
  */
 /**
@@ -21,8 +21,7 @@ import Position from './position';
 import Range from './range';
 import RootElement from './rootelement';
 import Text from './text';
-import toMap from '@ckeditor/ckeditor5-utils/src/tomap';
-import CKEditorError, { logWarning } from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+import { CKEditorError, logWarning, toMap } from '@ckeditor/ckeditor5-utils';
 /**
  * The model can only be modified by using the writer. It should be used whenever you want to create a node, modify
  * child nodes, attributes or text, set the selection's position and its attributes.
@@ -51,34 +50,22 @@ export default class Writer {
      * **Note:** It is not recommended to use it directly. Use {@link module:engine/model/model~Model#change `Model#change()`} or
      * {@link module:engine/model/model~Model#enqueueChange `Model#enqueueChange()`} instead.
      *
-     * @protected
-     * @param {module:engine/model/model~Model} model
-     * @param {module:engine/model/batch~Batch} batch
+     * @internal
      */
     constructor(model, batch) {
-        /**
-         * Instance of the model on which this writer operates.
-         *
-         * @readonly
-         * @type {module:engine/model/model~Model}
-         */
         this.model = model;
-        /**
-         * The batch to which this writer will add changes.
-         *
-         * @readonly
-         * @type {module:engine/model/batch~Batch}
-         */
         this.batch = batch;
     }
     /**
      * Creates a new {@link module:engine/model/text~Text text node}.
      *
-     *		writer.createText( 'foo' );
-     *		writer.createText( 'foo', { bold: true } );
+     * ```ts
+     * writer.createText( 'foo' );
+     * writer.createText( 'foo', { bold: true } );
+     * ```
      *
-     * @param {String} data Text data.
-     * @param {Object} [attributes] Text attributes.
+     * @param data Text data.
+     * @param attributes Text attributes.
      * @returns {module:engine/model/text~Text} Created text node.
      */
     createText(data, attributes) {
@@ -87,12 +74,14 @@ export default class Writer {
     /**
      * Creates a new {@link module:engine/model/element~Element element}.
      *
-     *		writer.createElement( 'paragraph' );
-     *		writer.createElement( 'paragraph', { alignment: 'center' } );
+     * ```ts
+     * writer.createElement( 'paragraph' );
+     * writer.createElement( 'paragraph', { alignment: 'center' } );
+     * ```
      *
-     * @param {String} name Name of the element.
-     * @param {Object} [attributes] Elements attributes.
-     * @returns {module:engine/model/element~Element} Created element.
+     * @param name Name of the element.
+     * @param attributes Elements attributes.
+     * @returns Created element.
      */
     createElement(name, attributes) {
         return new Element(name, attributes);
@@ -100,7 +89,7 @@ export default class Writer {
     /**
      * Creates a new {@link module:engine/model/documentfragment~DocumentFragment document fragment}.
      *
-     * @returns {module:engine/model/documentfragment~DocumentFragment} Created document fragment.
+     * @returns Created document fragment.
      */
     createDocumentFragment() {
         return new DocumentFragment();
@@ -109,8 +98,8 @@ export default class Writer {
      * Creates a copy of the element and returns it. Created element has the same name and attributes as the original element.
      * If clone is deep, the original element's children are also cloned. If not, then empty element is returned.
      *
-     * @param {module:engine/model/element~Element} element The element to clone.
-     * @param {Boolean} [deep=true] If set to `true` clones element and all its children recursively. When set to `false`,
+     * @param element The element to clone.
+     * @param deep If set to `true` clones element and all its children recursively. When set to `false`,
      * element will be cloned without any child.
      */
     cloneElement(element, deep = true) {
@@ -119,23 +108,31 @@ export default class Writer {
     /**
      * Inserts item on given position.
      *
-     *		const paragraph = writer.createElement( 'paragraph' );
-     *		writer.insert( paragraph, position );
+     * ```ts
+     * const paragraph = writer.createElement( 'paragraph' );
+     * writer.insert( paragraph, position );
+     * ```
      *
      * Instead of using position you can use parent and offset:
      *
-     *		const text = writer.createText( 'foo' );
-     *		writer.insert( text, paragraph, 5 );
+     * ```ts
+     * const text = writer.createText( 'foo' );
+     * writer.insert( text, paragraph, 5 );
+     * ```
      *
      * You can also use `end` instead of the offset to insert at the end:
      *
-     *		const text = writer.createText( 'foo' );
-     *		writer.insert( text, paragraph, 'end' );
+     * ```ts
+     * const text = writer.createText( 'foo' );
+     * writer.insert( text, paragraph, 'end' );
+     * ```
      *
      * Or insert before or after another element:
      *
-     *		const paragraph = writer.createElement( 'paragraph' );
-     *		writer.insert( paragraph, anotherParagraph, 'after' );
+     * ```ts
+     * const paragraph = writer.createElement( 'paragraph' );
+     * writer.insert( paragraph, anotherParagraph, 'after' );
+     * ```
      *
      * These parameters works the same way as {@link #createPositionAt `writer.createPositionAt()`}.
      *
@@ -150,11 +147,8 @@ export default class Writer {
      * **Note:** For a paste-like content insertion mechanism see
      * {@link module:engine/model/model~Model#insertContent `model.insertContent()`}.
      *
-     * @param {module:engine/model/item~Item|module:engine/model/documentfragment~DocumentFragment} item Item or document
-     * fragment to insert.
-     * @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
-     * second parameter is a {@link module:engine/model/item~Item model item}.
+     * @param item Item or document fragment to insert.
+     * @param offset Offset or one of the flags. Used only when second parameter is a {@link module:engine/model/item~Item model item}.
      */
     insert(item, itemOrPosition, offset = 0) {
         this._assertWriterUsedCorrectly();
@@ -211,30 +205,6 @@ export default class Writer {
             }
         }
     }
-    /**
-     * Creates and inserts text on given position. You can optionally set text attributes:
-     *
-     *		writer.insertText( 'foo', position );
-     *		writer.insertText( 'foo', { bold: true }, position );
-     *
-     * Instead of using position you can use parent and offset or define that text should be inserted at the end
-     * or before or after other node:
-     *
-     *		// Inserts 'foo' in paragraph, at offset 5:
-     *		writer.insertText( 'foo', paragraph, 5 );
-     *		// Inserts 'foo' at the end of a paragraph:
-     *		writer.insertText( 'foo', paragraph, 'end' );
-     *		// Inserts 'foo' after an image:
-     *		writer.insertText( 'foo', image, 'after' );
-     *
-     * These parameters work in the same way as {@link #createPositionAt `writer.createPositionAt()`}.
-     *
-     * @param {String} dattexta Text data.
-     * @param {Object} [attributes] Text attributes.
-     * @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
-     * third parameter is a {@link module:engine/model/item~Item model item}.
-     */
     insertText(text, attributes, // Too complicated when not using `any`.
     itemOrPosition, // Too complicated when not using `any`.
     offset // Too complicated when not using `any`.
@@ -246,30 +216,6 @@ export default class Writer {
             this.insert(this.createText(text, attributes), itemOrPosition, offset);
         }
     }
-    /**
-     * Creates and inserts element on given position. You can optionally set attributes:
-     *
-     *		writer.insertElement( 'paragraph', position );
-     *		writer.insertElement( 'paragraph', { alignment: 'center' }, position );
-     *
-     * Instead of using position you can use parent and offset or define that text should be inserted at the end
-     * or before or after other node:
-     *
-     *		// Inserts paragraph in the root at offset 5:
-     *		writer.insertElement( 'paragraph', root, 5 );
-     *		// Inserts paragraph at the end of a blockquote:
-     *		writer.insertElement( 'paragraph', blockquote, 'end' );
-     *		// Inserts after an image:
-     *		writer.insertElement( 'paragraph', image, 'after' );
-     *
-     * These parameters works the same way as {@link #createPositionAt `writer.createPositionAt()`}.
-     *
-     * @param {String} name Name of the element.
-     * @param {Object} [attributes] Elements attributes.
-     * @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
-     * third parameter is a {@link module:engine/model/item~Item model item}.
-     */
     insertElement(name, attributes, // Too complicated when not using `any`.
     itemOrPositionOrOffset, // Too complicated when not using `any`.
     offset // Too complicated when not using `any`.
@@ -284,31 +230,21 @@ export default class Writer {
     /**
      * Inserts item at the end of the given parent.
      *
-     *		const paragraph = writer.createElement( 'paragraph' );
-     *		writer.append( paragraph, root );
+     * ```ts
+     * const paragraph = writer.createElement( 'paragraph' );
+     * writer.append( paragraph, root );
+     * ```
      *
      * Note that if the item already has parent it will be removed from the previous parent.
      *
      * If you want to move {@link module:engine/model/range~Range range} instead of an
      * {@link module:engine/model/item~Item item} use {@link module:engine/model/writer~Writer#move `Writer#move()`}.
      *
-     * @param {module:engine/model/item~Item|module:engine/model/documentfragment~DocumentFragment}
-     * item Item or document fragment to insert.
-     * @param {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment} parent
+     * @param item Item or document fragment to insert.
      */
     append(item, parent) {
         this.insert(item, parent, 'end');
     }
-    /**
-     * Creates text node and inserts it at the end of the parent. You can optionally set text attributes:
-     *
-     *		writer.appendText( 'foo', paragraph );
-     *		writer.appendText( 'foo', { bold: true }, paragraph );
-     *
-     * @param {String} text Text data.
-     * @param {Object} [attributes] Text attributes.
-     * @param {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment} parent
-     */
     appendText(text, attributes, parent) {
         if (attributes instanceof DocumentFragment || attributes instanceof Element) {
             this.insert(this.createText(text), attributes, 'end');
@@ -317,16 +253,6 @@ export default class Writer {
             this.insert(this.createText(text, attributes), parent, 'end');
         }
     }
-    /**
-     * Creates element and inserts it at the end of the parent. You can optionally set attributes:
-     *
-     *		writer.appendElement( 'paragraph', root );
-     *		writer.appendElement( 'paragraph', { alignment: 'center' }, root );
-     *
-     * @param {String} name Name of the element.
-     * @param {Object} [attributes] Elements attributes.
-     * @param {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment} parent
-     */
     appendElement(name, attributes, parent) {
         if (attributes instanceof DocumentFragment || attributes instanceof Element) {
             this.insert(this.createElement(name), attributes, 'end');
@@ -339,10 +265,9 @@ export default class Writer {
      * Sets value of the attribute with given key on a {@link module:engine/model/item~Item model item}
      * or on a {@link module:engine/model/range~Range range}.
      *
-     * @param {String} key Attribute key.
-     * @param {*} value Attribute new value.
-     * @param {module:engine/model/item~Item|module:engine/model/range~Range} itemOrRange
-     * Model item or range on which the attribute will be set.
+     * @param key Attribute key.
+     * @param value Attribute new value.
+     * @param itemOrRange Model item or range on which the attribute will be set.
      */
     setAttribute(key, value, itemOrRange) {
         this._assertWriterUsedCorrectly();
@@ -360,14 +285,15 @@ export default class Writer {
      * Sets values of attributes on a {@link module:engine/model/item~Item model item}
      * or on a {@link module:engine/model/range~Range range}.
      *
-     *		writer.setAttributes( {
-     *			bold: true,
-     *			italic: true
-     *		}, range );
+     * ```ts
+     * writer.setAttributes( {
+     * 	bold: true,
+     * 	italic: true
+     * }, range );
+     * ```
      *
-     * @param {Object} attributes Attributes keys and values.
-     * @param {module:engine/model/item~Item|module:engine/model/range~Range} itemOrRange
-     * Model item or range on which the attributes will be set.
+     * @param attributes Attributes keys and values.
+     * @param itemOrRange Model item or range on which the attributes will be set.
      */
     setAttributes(attributes, itemOrRange) {
         for (const [key, val] of toMap(attributes)) {
@@ -378,9 +304,8 @@ export default class Writer {
      * Removes an attribute with given key from a {@link module:engine/model/item~Item model item}
      * or from a {@link module:engine/model/range~Range range}.
      *
-     * @param {String} key Attribute key.
-     * @param {module:engine/model/item~Item|module:engine/model/range~Range} itemOrRange
-     * Model item or range from which the attribute will be removed.
+     * @param key Attribute key.
+     * @param itemOrRange Model item or range from which the attribute will be removed.
      */
     removeAttribute(key, itemOrRange) {
         this._assertWriterUsedCorrectly();
@@ -397,8 +322,7 @@ export default class Writer {
     /**
      * Removes all attributes from all elements in the range or from the given item.
      *
-     * @param {module:engine/model/item~Item|module:engine/model/range~Range} itemOrRange
-     * Model item or range from which all attributes will be removed.
+     * @param itemOrRange Model item or range from which all attributes will be removed.
      */
     clearAttributes(itemOrRange) {
         this._assertWriterUsedCorrectly();
@@ -419,17 +343,21 @@ export default class Writer {
     /**
      * Moves all items in the source range to the target position.
      *
-     *		writer.move( sourceRange, targetPosition );
+     * ```ts
+     * writer.move( sourceRange, targetPosition );
+     * ```
      *
      * Instead of the target position you can use parent and offset or define that range should be moved to the end
      * or before or after chosen item:
      *
-     *		// Moves all items in the range to the paragraph at offset 5:
-     *		writer.move( sourceRange, paragraph, 5 );
-     *		// Moves all items in the range to the end of a blockquote:
-     *		writer.move( sourceRange, blockquote, 'end' );
-     *		// Moves all items in the range to a position after an image:
-     *		writer.move( sourceRange, image, 'after' );
+     * ```ts
+     * // Moves all items in the range to the paragraph at offset 5:
+     * writer.move( sourceRange, paragraph, 5 );
+     * // Moves all items in the range to the end of a blockquote:
+     * writer.move( sourceRange, blockquote, 'end' );
+     * // Moves all items in the range to a position after an image:
+     * writer.move( sourceRange, image, 'after' );
+     * ```
      *
      * These parameters works the same way as {@link #createPositionAt `writer.createPositionAt()`}.
      *
@@ -438,10 +366,8 @@ export default class Writer {
      * but you can not move items from document fragment to the document or from one detached element to another. Use
      * {@link module:engine/model/writer~Writer#insert} in such cases.
      *
-     * @param {module:engine/model/range~Range} range Source range.
-     * @param {module:engine/model/item~Item|module:engine/model/position~Position} itemOrPosition
-     * @param {Number|'end'|'before'|'after'} [offset] Offset or one of the flags. Used only when
-     * second parameter is a {@link module:engine/model/item~Item model item}.
+     * @param range Source range.
+     * @param offset Offset or one of the flags. Used only when second parameter is a {@link module:engine/model/item~Item model item}.
      */
     move(range, itemOrPosition, offset) {
         this._assertWriterUsedCorrectly();
@@ -485,7 +411,7 @@ export default class Writer {
     /**
      * Removes given model {@link module:engine/model/item~Item item} or {@link module:engine/model/range~Range range}.
      *
-     * @param {module:engine/model/item~Item|module:engine/model/range~Range} itemOrRange Model item or range to remove.
+     * @param itemOrRange Model item or range to remove.
      */
     remove(itemOrRange) {
         this._assertWriterUsedCorrectly();
@@ -503,7 +429,7 @@ export default class Writer {
      * Node before and after the position have to be an element. Otherwise `writer-merge-no-element-before` or
      * `writer-merge-no-element-after` error will be thrown.
      *
-     * @param {module:engine/model/position~Position} position Position between merged elements.
+     * @param position Position between merged elements.
      */
     merge(position) {
         this._assertWriterUsedCorrectly();
@@ -537,11 +463,9 @@ export default class Writer {
     /**
      * Shortcut for {@link module:engine/model/model~Model#createPositionFromPath `Model#createPositionFromPath()`}.
      *
-     * @param {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment} root Root of the position.
-     * @param {Array.<Number>} path Position path. See {@link module:engine/model/position~Position#path}.
-     * @param {module:engine/model/position~PositionStickiness} [stickiness='toNone'] Position stickiness.
-     * See {@link module:engine/model/position~PositionStickiness}.
-     * @returns {module:engine/model/position~Position}
+     * @param root Root of the position.
+     * @param path Position path. See {@link module:engine/model/position~Position#path}.
+     * @param stickiness Position stickiness. See {@link module:engine/model/position~PositionStickiness}.
      */
     createPositionFromPath(root, path, stickiness) {
         return this.model.createPositionFromPath(root, path, stickiness);
@@ -549,10 +473,7 @@ export default class Writer {
     /**
      * Shortcut for {@link module:engine/model/model~Model#createPositionAt `Model#createPositionAt()`}.
      *
-     * @param {module:engine/model/item~Item|module:engine/model/position~Position} itemOrPosition
-     * @param {Number|'end'|'before'|'after'} [offset] Offset or one of the flags. Used only when
-     * first parameter is a {@link module:engine/model/item~Item model item}.
-     * @returns {module:engine/model/position~Position}
+     * @param offset Offset or one of the flags. Used only when first parameter is a {@link module:engine/model/item~Item model item}.
      */
     createPositionAt(itemOrPosition, offset) {
         return this.model.createPositionAt(itemOrPosition, offset);
@@ -560,8 +481,7 @@ export default class Writer {
     /**
      * Shortcut for {@link module:engine/model/model~Model#createPositionAfter `Model#createPositionAfter()`}.
      *
-     * @param {module:engine/model/item~Item} item Item after which the position should be placed.
-     * @returns {module:engine/model/position~Position}
+     * @param item Item after which the position should be placed.
      */
     createPositionAfter(item) {
         return this.model.createPositionAfter(item);
@@ -569,8 +489,7 @@ export default class Writer {
     /**
      * Shortcut for {@link module:engine/model/model~Model#createPositionBefore `Model#createPositionBefore()`}.
      *
-     * @param {module:engine/model/item~Item} item Item after which the position should be placed.
-     * @returns {module:engine/model/position~Position}
+     * @param item Item after which the position should be placed.
      */
     createPositionBefore(item) {
         return this.model.createPositionBefore(item);
@@ -578,9 +497,8 @@ export default class Writer {
     /**
      * Shortcut for {@link module:engine/model/model~Model#createRange `Model#createRange()`}.
      *
-     * @param {module:engine/model/position~Position} start Start position.
-     * @param {module:engine/model/position~Position} [end] End position. If not set, range will be collapsed at `start` position.
-     * @returns {module:engine/model/range~Range}
+     * @param start Start position.
+     * @param end End position. If not set, range will be collapsed at `start` position.
      */
     createRange(start, end) {
         return this.model.createRange(start, end);
@@ -588,8 +506,7 @@ export default class Writer {
     /**
      * Shortcut for {@link module:engine/model/model~Model#createRangeIn `Model#createRangeIn()`}.
      *
-     * @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.
      */
     createRangeIn(element) {
         return this.model.createRangeIn(element);
@@ -597,20 +514,13 @@ export default class Writer {
     /**
      * Shortcut for {@link module:engine/model/model~Model#createRangeOn `Model#createRangeOn()`}.
      *
-     * @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.
      */
     createRangeOn(element) {
         return this.model.createRangeOn(element);
     }
     /**
      * Shortcut for {@link module:engine/model/model~Model#createSelection `Model#createSelection()`}.
-     *
-     * @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.
-     * @returns {module:engine/model/selection~Selection}
      */
     createSelection(...args) {
         return this.model.createSelection(...args);
@@ -618,8 +528,7 @@ export default class Writer {
     /**
      * Performs merge action in a detached tree.
      *
-     * @private
-     * @param {module:engine/model/position~Position} position Position between merged elements.
+     * @param position Position between merged elements.
      */
     _mergeDetached(position) {
         const nodeBefore = position.nodeBefore;
@@ -630,8 +539,7 @@ export default class Writer {
     /**
      * Performs merge action in a non-detached tree.
      *
-     * @private
-     * @param {module:engine/model/position~Position} position Position between merged elements.
+     * @param position Position between merged elements.
      */
     _merge(position) {
         const targetPosition = Position._createAt(position.nodeBefore, 'end');
@@ -646,8 +554,8 @@ export default class Writer {
     /**
      * Renames the given element.
      *
-     * @param {module:engine/model/element~Element} element The element to rename.
-     * @param {String} newName New element name.
+     * @param element The element to rename.
+     * @param newName New element name.
      */
     rename(element, newName) {
         this._assertWriterUsedCorrectly();
@@ -671,12 +579,11 @@ export default class Writer {
      * The element needs to have a parent. It cannot be a root element nor a document fragment.
      * The `writer-split-element-no-parent` error will be thrown if you try to split an element with no parent.
      *
-     * @param {module:engine/model/position~Position} position Position of split.
-     * @param {module:engine/model/node~Node} [limitElement] Stop splitting when this element will be reached.
-     * @returns {Object} result Split result.
-     * @returns {module:engine/model/position~Position} result.position Position between split elements.
-     * @returns {module:engine/model/range~Range} result.range Range that stars from the end of the first split element and ends
-     * at the beginning of the first copy element.
+     * @param position Position of split.
+     * @param limitElement Stop splitting when this element will be reached.
+     * @returns Split result with properties:
+     * * `position` - Position between split elements.
+     * * `range` - Range that stars from the end of the first split element and ends at the beginning of the first copy element.
      */
     split(position, limitElement) {
         this._assertWriterUsedCorrectly();
@@ -732,8 +639,8 @@ export default class Writer {
      * **Note:** range to wrap should be a "flat range" (see {@link module:engine/model/range~Range#isFlat `Range#isFlat`}).
      * If not, an error will be thrown.
      *
-     * @param {module:engine/model/range~Range} range Range to wrap.
-     * @param {module:engine/model/element~Element|String} elementOrString Element or name of element to wrap the range with.
+     * @param range Range to wrap.
+     * @param elementOrString Element or name of element to wrap the range with.
      */
     wrap(range, elementOrString) {
         this._assertWriterUsedCorrectly();
@@ -771,7 +678,7 @@ export default class Writer {
      * Unwraps children of the given element – all its children are moved before it and then the element is removed.
      * Throws error if you try to unwrap an element which does not have a parent.
      *
-     * @param {module:engine/model/element~Element} element Element to unwrap.
+     * @param element Element to unwrap.
      */
     unwrap(element) {
         this._assertWriterUsedCorrectly();
@@ -804,26 +711,31 @@ export default class Writer {
      *
      * Create marker directly base on marker's name:
      *
-     *		addMarker( markerName, { range, usingOperation: false } );
+     * ```ts
+     * addMarker( markerName, { range, usingOperation: false } );
+     * ```
      *
      * Create marker using operation:
      *
-     *		addMarker( markerName, { range, usingOperation: true } );
+     * ```ts
+     * addMarker( markerName, { range, usingOperation: true } );
+     * ```
      *
      * Create marker that affects the editor data:
      *
-     *		addMarker( markerName, { range, usingOperation: false, affectsData: true } );
+     * ```ts
+     * addMarker( markerName, { range, usingOperation: false, affectsData: true } );
+     * ```
      *
      * Note: For efficiency reasons, it's best to create and keep as little markers as possible.
      *
      * @see module:engine/model/markercollection~Marker
-     * @param {String} name Name of a marker to create - must be unique.
-     * @param {Object} options
-     * @param {Boolean} options.usingOperation Flag indicating that the marker should be added by MarkerOperation.
+     * @param name Name of a marker to create - must be unique.
+     * @param options.usingOperation Flag indicating that the marker should be added by MarkerOperation.
      * See {@link module:engine/model/markercollection~Marker#managedUsingOperations}.
-     * @param {module:engine/model/range~Range} options.range Marker range.
-     * @param {Boolean} [options.affectsData=false] Flag indicating that the marker changes the editor data.
-     * @returns {module:engine/model/markercollection~Marker} Marker that was set.
+     * @param options.range Marker range.
+     * @param options.affectsData Flag indicating that the marker changes the editor data.
+     * @returns Marker that was set.
      */
     addMarker(name, options) {
         this._assertWriterUsedCorrectly();
@@ -883,29 +795,37 @@ export default class Writer {
      *
      * Update marker directly base on marker's name:
      *
-     *		updateMarker( markerName, { range } );
+     * ```ts
+     * updateMarker( markerName, { range } );
+     * ```
      *
      * Update marker using operation:
      *
-     *		updateMarker( marker, { range, usingOperation: true } );
-     *		updateMarker( markerName, { range, usingOperation: true } );
+     * ```ts
+     * updateMarker( marker, { range, usingOperation: true } );
+     * updateMarker( markerName, { range, usingOperation: true } );
+     * ```
      *
      * Change marker's option (start using operations to manage it):
      *
-     *		updateMarker( marker, { usingOperation: true } );
+     * ```ts
+     * updateMarker( marker, { usingOperation: true } );
+     * ```
      *
      * Change marker's option (inform the engine, that the marker does not affect the data anymore):
      *
-     *		updateMarker( markerName, { affectsData: false } );
+     * ```ts
+     * updateMarker( markerName, { affectsData: false } );
+     * ```
      *
      * @see module:engine/model/markercollection~Marker
-     * @param {String|module:engine/model/markercollection~Marker} markerOrName Name of a marker to update, or a marker instance.
-     * @param {Object} [options] If options object is not defined then marker will be refreshed by triggering
+     * @param markerOrName Name of a marker to update, or a marker instance.
+     * @param options If options object is not defined then marker will be refreshed by triggering
      * downcast conversion for this marker with the same data.
-     * @param {module:engine/model/range~Range} [options.range] Marker range to update.
-     * @param {Boolean} [options.usingOperation] Flag indicated whether the marker should be added by MarkerOperation.
+     * @param options.range Marker range to update.
+     * @param options.usingOperation Flag indicated whether the marker should be added by MarkerOperation.
      * See {@link module:engine/model/markercollection~Marker#managedUsingOperations}.
-     * @param {Boolean} [options.affectsData] Flag indicating that the marker changes the editor data.
+     * @param options.affectsData Flag indicating that the marker changes the editor data.
      */
     updateMarker(markerOrName, options) {
         this._assertWriterUsedCorrectly();
@@ -928,7 +848,7 @@ export default class Writer {
              * instead.
              *
              * @error writer-updatemarker-reconvert-using-editingcontroller
-             * @param {String} markerName The name of the updated marker.
+             * @param markerName The name of the updated marker.
              */
             logWarning('writer-updatemarker-reconvert-using-editingcontroller', { markerName });
             this.model.markers._refresh(currentMarker);
@@ -977,7 +897,7 @@ export default class Writer {
      * The marker is removed accordingly to how it has been created, so if the marker was created using operation,
      * it will be destroyed using operation.
      *
-     * @param {module:engine/model/markercollection~Marker|String} markerOrName Marker or marker name to remove.
+     * @param markerOrName Marker or marker name to remove.
      */
     removeMarker(markerOrName) {
         this._assertWriterUsedCorrectly();
@@ -1002,52 +922,55 @@ export default class Writer {
      * Sets the document's selection (ranges and direction) to the specified location based on the given
      * {@link module:engine/model/selection~Selectable selectable} or creates an empty selection if no arguments were passed.
      *
-     *		// Sets selection to the given range.
-     *		const range = writer.createRange( start, end );
-     *		writer.setSelection( range );
+     * ```ts
+     * // Sets selection to the given range.
+     * const range = writer.createRange( start, end );
+     * writer.setSelection( range );
      *
-     *		// Sets selection to given ranges.
-     *		const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
-     *		writer.setSelection( ranges );
+     * // Sets selection to given ranges.
+     * const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
+     * writer.setSelection( ranges );
      *
-     *		// Sets selection to other selection.
-     *		const otherSelection = writer.createSelection();
-     *		writer.setSelection( otherSelection );
+     * // Sets selection to other selection.
+     * const otherSelection = writer.createSelection();
+     * writer.setSelection( otherSelection );
      *
-     *		// Sets selection to the given document selection.
-     *		const documentSelection = model.document.selection;
-     *		writer.setSelection( documentSelection );
+     * // Sets selection to the given document selection.
+     * const documentSelection = model.document.selection;
+     * writer.setSelection( documentSelection );
      *
-     *		// Sets collapsed selection at the given position.
-     *		const position = writer.createPosition( root, path );
-     *		writer.setSelection( position );
+     * // Sets collapsed selection at the given position.
+     * const position = writer.createPosition( root, path );
+     * writer.setSelection( position );
      *
-     *		// Sets collapsed selection at the position of the given node and an offset.
-     *		writer.setSelection( paragraph, offset );
+     * // Sets collapsed selection at the position of the given node and an offset.
+     * writer.setSelection( paragraph, offset );
+     * ```
      *
      * Creates a range inside an {@link module:engine/model/element~Element element} which starts before the first child of
      * that element and ends after the last child of that element.
      *
-     *		writer.setSelection( paragraph, 'in' );
+     * ```ts
+     * writer.setSelection( paragraph, 'in' );
+     * ```
      *
      * Creates a range on an {@link module:engine/model/item~Item item} which starts before the item and ends just after the item.
      *
-     *		writer.setSelection( paragraph, 'on' );
+     * ```ts
+     * writer.setSelection( paragraph, 'on' );
      *
-     *		// Removes all selection's ranges.
-     *		writer.setSelection( null );
+     * // Removes all selection's ranges.
+     * writer.setSelection( null );
+     * ```
      *
      * `Writer#setSelection()` allow passing additional options (`backward`) as the last argument.
      *
-     *		// Sets selection as backward.
-     *		writer.setSelection( range, { backward: true } );
+     * ```ts
+     * // Sets selection as backward.
+     * writer.setSelection( range, { backward: true } );
+     * ```
      *
      * Throws `writer-incorrect-use` error when the writer is used outside the `change()` block.
-     *
-     * @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.
      */
     setSelection(...args) {
         this._assertWriterUsedCorrectly();
@@ -1059,33 +982,13 @@ export default class Writer {
      * The location can be specified in the same form as
      * {@link #createPositionAt `writer.createPositionAt()`} parameters.
      *
-     * @param {module:engine/model/item~Item|module:engine/model/position~Position} itemOrPosition
-     * @param {Number|'end'|'before'|'after'} [offset=0] Offset or one of the flags. Used only when
-     * first parameter is a {@link module:engine/model/item~Item model item}.
+     * @param itemOrPosition
+     * @param offset Offset or one of the flags. Used only when first parameter is a {@link module:engine/model/item~Item model item}.
      */
     setSelectionFocus(itemOrPosition, offset) {
         this._assertWriterUsedCorrectly();
         this.model.document.selection._setFocus(itemOrPosition, offset);
     }
-    /**
-     * Sets attribute(s) on the selection. If attribute with the same key already is set, it's value is overwritten.
-     *
-     * Using key and value pair:
-     *
-     * 	writer.setSelectionAttribute( 'italic', true );
-     *
-     * Using key-value object:
-     *
-     * 	writer.setSelectionAttribute( { italic: true, bold: false } );
-     *
-     * Using iterable object:
-     *
-     * 	writer.setSelectionAttribute( new Map( [ [ 'italic', true ] ] ) );
-     *
-     * @param {String|Object|Iterable.<*>} keyOrObjectOrIterable Key of the attribute to set
-     * or object / iterable of key => value attribute pairs.
-     * @param {*} [value] Attribute value.
-     */
     setSelectionAttribute(keyOrObjectOrIterable, value) {
         this._assertWriterUsedCorrectly();
         if (typeof keyOrObjectOrIterable === 'string') {
@@ -1102,13 +1005,17 @@ export default class Writer {
      *
      * Remove one attribute:
      *
-     *		writer.removeSelectionAttribute( 'italic' );
+     * ```ts
+     * writer.removeSelectionAttribute( 'italic' );
+     * ```
      *
      * Remove multiple attributes:
      *
-     *		writer.removeSelectionAttribute( [ 'italic', 'bold' ] );
+     * ```ts
+     * writer.removeSelectionAttribute( [ 'italic', 'bold' ] );
+     * ```
      *
-     * @param {String|Iterable.<String>} keyOrIterableOfKeys Key of the attribute to remove or an iterable of attribute keys to remove.
+     * @param keyOrIterableOfKeys Key of the attribute to remove or an iterable of attribute keys to remove.
      */
     removeSelectionAttribute(keyOrIterableOfKeys) {
         this._assertWriterUsedCorrectly();
@@ -1131,7 +1038,9 @@ export default class Writer {
      *
      * For the following model fragment:
      *
-     *		<$text bold="true" linkHref="url">bar[]</$text><$text bold="true">biz</$text>
+     * ```xml
+     * <$text bold="true" linkHref="url">bar[]</$text><$text bold="true">biz</$text>
+     * ```
      *
      * * Default gravity: selection will have the `bold` and `linkHref` attributes.
      * * Overridden gravity: selection will have `bold` attribute.
@@ -1139,7 +1048,7 @@ export default class Writer {
      * **Note**: It returns an unique identifier which is required to restore the gravity. It guarantees the symmetry
      * of the process.
      *
-     * @returns {String} The unique id which allows restoring the gravity.
+     * @returns The unique id which allows restoring the gravity.
      */
     overrideSelectionGravity() {
         return this.model.document.selection._overrideGravity();
@@ -1151,15 +1060,14 @@ export default class Writer {
      * {@link ~Writer#overrideSelectionGravity}. Note that the gravity remains overridden as long as won't be restored
      * the same number of times it was overridden.
      *
-     * @param {String} uid The unique id returned by {@link ~Writer#overrideSelectionGravity}.
+     * @param uid The unique id returned by {@link ~Writer#overrideSelectionGravity}.
      */
     restoreSelectionGravity(uid) {
         this.model.document.selection._restoreGravity(uid);
     }
     /**
-     * @private
-     * @param {String} key Key of the attribute to remove.
-     * @param {*} value Attribute value.
+     * @param key Key of the attribute to remove.
+     * @param value Attribute value.
      */
     _setSelectionAttribute(key, value) {
         const selection = this.model.document.selection;
@@ -1171,8 +1079,7 @@ export default class Writer {
         selection._setAttribute(key, value);
     }
     /**
-     * @private
-     * @param {String} key Key of the attribute to remove.
+     * @param key Key of the attribute to remove.
      */
     _removeSelectionAttribute(key) {
         const selection = this.model.document.selection;
@@ -1185,8 +1092,6 @@ export default class Writer {
     }
     /**
      * Throws `writer-detached-writer-tries-to-modify-model` error when the writer is used outside of the `change()` block.
-     *
-     * @private
      */
     _assertWriterUsedCorrectly() {
         /**
@@ -1207,10 +1112,8 @@ export default class Writer {
      * and applies a marker operation with the new marker range equal to the current range. Thanks to this, the marker range
      * can be later correctly processed during undo.
      *
-     * @private
-     * @param {'move'|'merge'} type Writer action type.
-     * @param {module:engine/model/position~Position|module:engine/model/range~Range} positionOrRange Position or range
-     * where the writer action happens.
+     * @param type Writer action type.
+     * @param positionOrRange Position or range where the writer action happens.
      */
     _addOperationForAffectedMarkers(type, positionOrRange) {
         for (const marker of this.model.markers) {
@@ -1260,18 +1163,14 @@ export default class Writer {
         }
     }
 }
-// Sets given attribute to each node in given range. When attribute value is null then attribute will be removed.
-//
-// Because attribute operation needs to have the same attribute value on the whole range, this function splits
-// the range into smaller parts.
-//
-// Given `range` must be flat.
-//
-// @private
-// @param {module:engine/model/writer~Writer} writer
-// @param {String} key Attribute key.
-// @param {*} value Attribute new value.
-// @param {module:engine/model/range~Range} range Model range on which the attribute will be set.
+/**
+ * Sets given attribute to each node in given range. When attribute value is null then attribute will be removed.
+ *
+ * Because attribute operation needs to have the same attribute value on the whole range, this function splits
+ * the range into smaller parts.
+ *
+ * Given `range` must be flat.
+ */
 function setAttributeOnRange(writer, key, value, range) {
     const model = writer.model;
     const doc = model.document;
@@ -1311,13 +1210,9 @@ function setAttributeOnRange(writer, key, value, range) {
         model.applyOperation(operation);
     }
 }
-// Sets given attribute to the given node. When attribute value is null then attribute will be removed.
-//
-// @private
-// @param {module:engine/model/writer~Writer} writer
-// @param {String} key Attribute key.
-// @param {*} value Attribute new value.
-// @param {module:engine/model/item~Item} item Model item on which the attribute will be set.
+/**
+ * Sets given attribute to the given node. When attribute value is null then attribute will be removed.
+ */
 function setAttributeOnItem(writer, key, value, item) {
     const model = writer.model;
     const doc = model.document;
@@ -1339,14 +1234,9 @@ function setAttributeOnItem(writer, key, value, item) {
         model.applyOperation(operation);
     }
 }
-// Creates and applies marker operation to {@link module:engine/model/operation/operation~Operation operation}.
-//
-// @private
-// @param {module:engine/model/writer~Writer} writer
-// @param {String} name Marker name.
-// @param {module:engine/model/range~Range} oldRange Marker range before the change.
-// @param {module:engine/model/range~Range} newRange Marker range after the change.
-// @param {Boolean} affectsData
+/**
+ * Creates and applies marker operation to {@link module:engine/model/operation/operation~Operation operation}.
+ */
 function applyMarkerOperation(writer, name, oldRange, newRange, affectsData) {
     const model = writer.model;
     const doc = model.document;
@@ -1354,14 +1244,15 @@ function applyMarkerOperation(writer, name, oldRange, newRange, affectsData) {
     writer.batch.addOperation(operation);
     model.applyOperation(operation);
 }
-// Creates `MoveOperation` or `DetachOperation` that removes `howMany` nodes starting from `position`.
-// The operation will be applied on given model instance and added to given operation instance.
-//
-// @private
-// @param {module:engine/model/position~Position} position Position from which nodes are removed.
-// @param {Number} howMany Number of nodes to remove.
-// @param {Batch} batch Batch to which the operation will be added.
-// @param {module:engine/model/model~Model} model Model instance on which operation will be applied.
+/**
+ * Creates `MoveOperation` or `DetachOperation` that removes `howMany` nodes starting from `position`.
+ * The operation will be applied on given model instance and added to given operation instance.
+ *
+ * @param position Position from which nodes are removed.
+ * @param howMany Number of nodes to remove.
+ * @param batch Batch to which the operation will be added.
+ * @param model Model instance on which operation will be applied.
+ */
 function applyRemoveOperation(position, howMany, batch, model) {
     let operation;
     if (position.root.document) {
@@ -1375,13 +1266,15 @@ function applyRemoveOperation(position, howMany, batch, model) {
     batch.addOperation(operation);
     model.applyOperation(operation);
 }
-// Returns `true` if both root elements are the same element or both are documents root elements.
-//
-// Elements in the same tree can be moved (for instance you can move element form one documents root to another, or
-// within the same document fragment), but when element supposed to be moved from document fragment to the document, or
-// to another document it should be removed and inserted to avoid problems with OT. This is because features like undo or
-// collaboration may track changes on the document but ignore changes on detached fragments and should not get
-// unexpected `move` operation.
+/**
+ * Returns `true` if both root elements are the same element or both are documents root elements.
+ *
+ * Elements in the same tree can be moved (for instance you can move element form one documents root to another, or
+ * within the same document fragment), but when element supposed to be moved from document fragment to the document, or
+ * to another document it should be removed and inserted to avoid problems with OT. This is because features like undo or
+ * collaboration may track changes on the document but ignore changes on detached fragments and should not get
+ * unexpected `move` operation.
+ */
 function isSameTree(rootA, rootB) {
     // If it is the same root this is the same tree.
     if (rootA === rootB) {