@ckeditor/ckeditor5-engine 35.3.2 → 36.0.0

package/src/model/model.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,54 +21,20 @@ import getSelectedContent from './utils/getselectedcontent';
 import insertContent from './utils/insertcontent';
 import insertObject from './utils/insertobject';
 import modifySelection from './utils/modifyselection';
-import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
-import { Observable } from '@ckeditor/ckeditor5-utils/src/observablemixin';
+import { CKEditorError, ObservableMixin } from '@ckeditor/ckeditor5-utils';
 // @if CK_DEBUG_ENGINE // const { dumpTrees } = require( '../dev-utils/utils' );
 // @if CK_DEBUG_ENGINE // const { OperationReplayer } = require( '../dev-utils/operationreplayer' ).default;
 /**
  * Editor's data model. Read about the model in the
  * {@glink framework/guides/architecture/editing-engine engine architecture guide}.
- *
- * @mixes module:utils/observablemixin~ObservableMixin
  */
-export default class Model extends Observable {
+export default class Model extends ObservableMixin() {
     constructor() {
         super();
-        /**
-         * Model's marker collection.
-         *
-         * @readonly
-         * @member {module:engine/model/markercollection~MarkerCollection}
-         */
         this.markers = new MarkerCollection();
-        /**
-         * Model's document.
-         *
-         * @readonly
-         * @member {module:engine/model/document~Document}
-         */
         this.document = new Document(this);
-        /**
-         * Model's schema.
-         *
-         * @readonly
-         * @member {module:engine/model/schema~Schema}
-         */
         this.schema = new Schema();
-        /**
-         * All callbacks added by {@link module:engine/model/model~Model#change} or
-         * {@link module:engine/model/model~Model#enqueueChange} methods waiting to be executed.
-         *
-         * @private
-         * @type {Array.<Function>}
-         */
         this._pendingChanges = [];
-        /**
-         * The last created and currently used writer instance.
-         *
-         * @private
-         * @member {module:engine/model/writer~Writer}
-         */
         this._currentWriter = null;
         ['insertContent', 'insertObject', 'deleteContent', 'modifySelection', 'getSelectedContent', 'applyOperation']
             .forEach(methodName => this.decorate(methodName));
@@ -138,34 +104,40 @@ export default class Model extends Observable {
      * the {@link module:engine/model/document~Document#selection document's selection}, and
      * {@link module:engine/model/model~Model#markers model markers}.
      *
-     *		model.change( writer => {
-     *			writer.insertText( 'foo', paragraph, 'end' );
-     *		} );
+     * ```ts
+     * model.change( writer => {
+     * 	writer.insertText( 'foo', paragraph, 'end' );
+     * } );
+     * ```
      *
      * All changes inside the change block use the same {@link module:engine/model/batch~Batch} so they are combined
      * into a single undo step.
      *
-     *		model.change( writer => {
-     *			writer.insertText( 'foo', paragraph, 'end' ); // foo.
+     * ```ts
+     * model.change( writer => {
+     * 	writer.insertText( 'foo', paragraph, 'end' ); // foo.
      *
-     *			model.change( writer => {
-     *				writer.insertText( 'bar', paragraph, 'end' ); // foobar.
-     *			} );
+     * 	model.change( writer => {
+     * 		writer.insertText( 'bar', paragraph, 'end' ); // foobar.
+     * 	} );
      *
-     * 			writer.insertText( 'bom', paragraph, 'end' ); // foobarbom.
-     *		} );
+     * 	writer.insertText( 'bom', paragraph, 'end' ); // foobarbom.
+     * } );
+     * ```
      *
      * The callback of the `change()` block is executed synchronously.
      *
      * You can also return a value from the change block.
      *
-     *		const img = model.change( writer => {
-     *			return writer.createElement( 'img' );
-     *		} );
+     * ```ts
+     * const img = model.change( writer => {
+     * 	return writer.createElement( 'img' );
+     * } );
+     * ```
      *
      * @see #enqueueChange
-     * @param {Function} callback Callback function which may modify the model.
-     * @returns {*} Value returned by the callback.
+     * @typeParam TReturn The return type of the provided callback.
+     * @param callback Callback function which may modify the model.
      */
     change(callback) {
         try {
@@ -185,49 +157,6 @@ export default class Model extends Observable {
             CKEditorError.rethrowUnexpectedError(err, this);
         }
     }
-    /**
-     * The `enqueueChange()` method performs similar task as the {@link #change `change()` method}, with two major differences.
-     *
-     * First, the callback of `enqueueChange()` is executed when all other enqueued changes are done. It might be executed
-     * immediately if it is not nested in any other change block, but if it is nested in another (enqueue)change block,
-     * it will be delayed and executed after the outermost block.
-     *
-     *		model.change( writer => {
-     *			console.log( 1 );
-     *
-     *			model.enqueueChange( writer => {
-     *				console.log( 2 );
-     *			} );
-     *
-     * 			console.log( 3 );
-     *		} ); // Will log: 1, 3, 2.
-     *
-     * In addition to that, the changes enqueued with `enqueueChange()` will be converted separately from the changes
-     * done in the outer `change()` block.
-     *
-     * Second, it lets you define the {@link module:engine/model/batch~Batch} into which you want to add your changes.
-     * By default, a new batch with the default {@link module:engine/model/batch~Batch#constructor batch type} is created.
-     * In the sample above, the `change` and `enqueueChange` blocks will use a different batch (and a different
-     * {@link module:engine/model/writer~Writer} instance since each of them operates on a separate batch).
-     *
-     *		model.enqueueChange( { isUndoable: false }, writer => {
-     *			writer.insertText( 'foo', paragraph, 'end' );
-     *		} );
-     *
-     * When using the `enqueueChange()` block you can also add some changes to the batch you used before.
-     *
-     *		model.enqueueChange( batch, writer => {
-     *			writer.insertText( 'foo', paragraph, 'end' );
-     *		} );
-     *
-     * In order to make a nested `enqueueChange()` create a single undo step together with the changes done in the outer `change()`
-     * block, you can obtain the batch instance from the  {@link module:engine/model/writer~Writer#batch writer} of the outer block.
-     *
-     * @param {module:engine/model/batch~Batch|Object} [batchOrType] A batch or a
-     * {@link module:engine/model/batch~Batch#constructor batch type} that should be used in the callback. If not defined, a new batch with
-     * the default type will be created.
-     * @param {Function} callback Callback function which may modify the model.
-     */
     enqueueChange(batchOrType, callback) {
         try {
             if (!batchOrType) {
@@ -252,7 +181,7 @@ export default class Model extends Observable {
         }
     }
     /**
-     * {@link module:utils/observablemixin~ObservableMixin#decorate Decorated} function for applying
+     * {@link module:utils/observablemixin~Observable#decorate Decorated} function for applying
      * {@link module:engine/model/operation/operation~Operation operations} to the model.
      *
      * This is a low-level way of changing the model. It is exposed for very specific use cases (like the undo feature).
@@ -260,7 +189,7 @@ export default class Model extends Observable {
      * See also {@glink framework/guides/architecture/editing-engine#changing-the-model Changing the model} section
      * of the {@glink framework/guides/architecture/editing-engine Editing architecture} guide.
      *
-     * @param {module:engine/model/operation/operation~Operation} operation The operation to apply.
+     * @param operation The operation to apply.
      */
     applyOperation(operation) {
         // @if CK_DEBUG_ENGINE // console.log( 'Applying ' + operation );
@@ -317,104 +246,112 @@ export default class Model extends Observable {
      *
      * Using `insertContent()` with a manually created model structure:
      *
-     *		// Let's create a document fragment containing such content as:
-     *		//
-     *		// <paragraph>foo</paragraph>
-     *		// <blockQuote>
-     *		//    <paragraph>bar</paragraph>
-     *		// </blockQuote>
-     *		const docFrag = editor.model.change( writer => {
-     *			const p1 = writer.createElement( 'paragraph' );
-     *			const p2 = writer.createElement( 'paragraph' );
-     *			const blockQuote = writer.createElement( 'blockQuote' );
-     *			const docFrag = writer.createDocumentFragment();
-     *
-     *			writer.append( p1, docFrag );
-     *			writer.append( blockQuote, docFrag );
-     *			writer.append( p2, blockQuote );
-     *			writer.insertText( 'foo', p1 );
-     *			writer.insertText( 'bar', p2 );
-     *
-     *			return docFrag;
-     *		} );
-     *
-     *		// insertContent() does not have to be used in a change() block. It can, though,
-     *		// so this code could be moved to the callback defined above.
-     *		editor.model.insertContent( docFrag );
+     * ```ts
+     * // Let's create a document fragment containing such content as:
+     * //
+     * // <paragraph>foo</paragraph>
+     * // <blockQuote>
+     * //    <paragraph>bar</paragraph>
+     * // </blockQuote>
+     * const docFrag = editor.model.change( writer => {
+     * 	const p1 = writer.createElement( 'paragraph' );
+     * 	const p2 = writer.createElement( 'paragraph' );
+     * 	const blockQuote = writer.createElement( 'blockQuote' );
+     * 	const docFrag = writer.createDocumentFragment();
+     *
+     * 	writer.append( p1, docFrag );
+     * 	writer.append( blockQuote, docFrag );
+     * 	writer.append( p2, blockQuote );
+     * 	writer.insertText( 'foo', p1 );
+     * 	writer.insertText( 'bar', p2 );
+     *
+     * 	return docFrag;
+     * } );
+     *
+     * // insertContent() does not have to be used in a change() block. It can, though,
+     * // so this code could be moved to the callback defined above.
+     * editor.model.insertContent( docFrag );
+     * ```
      *
      * Using `insertContent()` with an HTML string converted to a model document fragment (similar to the pasting mechanism):
      *
-     *		// You can create your own HtmlDataProcessor instance or use editor.data.processor
-     *		// if you have not overridden the default one (which is the HtmlDataProcessor instance).
-     *		const htmlDP = new HtmlDataProcessor( viewDocument );
-     *
-     *		// Convert an HTML string to a view document fragment:
-     *		const viewFragment = htmlDP.toView( htmlString );
-     *
-     *		// Convert the view document fragment to a model document fragment
-     *		// in the context of $root. This conversion takes the schema into
-     *		// account so if, for example, the view document fragment contained a bare text node,
-     *		// this text node cannot be a child of $root, so it will be automatically
-     *		// wrapped with a <paragraph>. You can define the context yourself (in the second parameter),
-     *		// and e.g. convert the content like it would happen in a <paragraph>.
-     *		// Note: The clipboard feature uses a custom context called $clipboardHolder
-     *		// which has a loosened schema.
-     *		const modelFragment = editor.data.toModel( viewFragment );
-     *
-     *		editor.model.insertContent( modelFragment );
+     * ```ts
+     * // You can create your own HtmlDataProcessor instance or use editor.data.processor
+     * // if you have not overridden the default one (which is the HtmlDataProcessor instance).
+     * const htmlDP = new HtmlDataProcessor( viewDocument );
+     *
+     * // Convert an HTML string to a view document fragment:
+     * const viewFragment = htmlDP.toView( htmlString );
+     *
+     * // Convert the view document fragment to a model document fragment
+     * // in the context of $root. This conversion takes the schema into
+     * // account so if, for example, the view document fragment contained a bare text node,
+     * // this text node cannot be a child of $root, so it will be automatically
+     * // wrapped with a <paragraph>. You can define the context yourself (in the second parameter),
+     * // and e.g. convert the content like it would happen in a <paragraph>.
+     * // Note: The clipboard feature uses a custom context called $clipboardHolder
+     * // which has a loosened schema.
+     * const modelFragment = editor.data.toModel( viewFragment );
+     *
+     * editor.model.insertContent( modelFragment );
+     * ```
      *
      * By default this method will use the document selection but it can also be used with a position, range or selection instance.
      *
-     *		// Insert text at the current document selection position.
-     *		editor.model.change( writer => {
-     *			editor.model.insertContent( writer.createText( 'x' ) );
-     *		} );
+     * ```ts
+     * // Insert text at the current document selection position.
+     * editor.model.change( writer => {
+     * 	editor.model.insertContent( writer.createText( 'x' ) );
+     * } );
      *
-     *		// Insert text at a given position - the document selection will not be modified.
-     *		editor.model.change( writer => {
-     *			editor.model.insertContent( writer.createText( 'x' ), doc.getRoot(), 2 );
+     * // Insert text at a given position - the document selection will not be modified.
+     * editor.model.change( writer => {
+     * 	editor.model.insertContent( writer.createText( 'x' ), doc.getRoot(), 2 );
      *
-     *			// Which is a shorthand for:
-     *			editor.model.insertContent( writer.createText( 'x' ), writer.createPositionAt( doc.getRoot(), 2 ) );
-     *		} );
+     * 	// Which is a shorthand for:
+     * 	editor.model.insertContent( writer.createText( 'x' ), writer.createPositionAt( doc.getRoot(), 2 ) );
+     * } );
+     * ```
      *
      * If you want the document selection to be moved to the inserted content, use the
      * {@link module:engine/model/writer~Writer#setSelection `setSelection()`} method of the writer after inserting
      * the content:
      *
-     *		editor.model.change( writer => {
-     *			const paragraph = writer.createElement( 'paragraph' );
+     * ```ts
+     * editor.model.change( writer => {
+     * 	const paragraph = writer.createElement( 'paragraph' );
      *
-     *			// Insert an empty paragraph at the beginning of the root.
-     *			editor.model.insertContent( paragraph, writer.createPositionAt( editor.model.document.getRoot(), 0 ) );
+     * 	// Insert an empty paragraph at the beginning of the root.
+     * 	editor.model.insertContent( paragraph, writer.createPositionAt( editor.model.document.getRoot(), 0 ) );
      *
-     *			// Move the document selection to the inserted paragraph.
-     *			writer.setSelection( paragraph, 'in' );
-     *		} );
+     * 	// Move the document selection to the inserted paragraph.
+     * 	writer.setSelection( paragraph, 'in' );
+     * } );
+     * ```
      *
      * If an instance of the {@link module:engine/model/selection~Selection model selection} is passed as `selectable`,
      * the new content will be inserted at the passed selection (instead of document selection):
      *
-     *		editor.model.change( writer => {
-     *			// Create a selection in a paragraph that will be used as a place of insertion.
-     *			const selection = writer.createSelection( paragraph, 'in' );
+     * ```ts
+     * editor.model.change( writer => {
+     * 	// Create a selection in a paragraph that will be used as a place of insertion.
+     * 	const selection = writer.createSelection( paragraph, 'in' );
      *
-     *			// Insert the new text at the created selection.
-     *			editor.model.insertContent( writer.createText( 'x' ), selection );
+     * 	// Insert the new text at the created selection.
+     * 	editor.model.insertContent( writer.createText( 'x' ), selection );
      *
-     *			// insertContent() modifies the passed selection instance so it can be used to set the document selection.
-     *			// Note: This is not necessary when you passed the document selection to insertContent().
-     *			writer.setSelection( selection );
-     *		} );
+     * 	// insertContent() modifies the passed selection instance so it can be used to set the document selection.
+     * 	// Note: This is not necessary when you passed the document selection to insertContent().
+     * 	writer.setSelection( selection );
+     * } );
+     * ```
      *
      * @fires insertContent
-     * @param {module:engine/model/documentfragment~DocumentFragment|module:engine/model/item~Item} content The content to insert.
-     * @param {module:engine/model/selection~Selectable} [selectable=model.document.selection]
-     * The selection into which the content should be inserted. If not provided the current model document selection will be used.
-     * @param {Number|'before'|'end'|'after'|'on'|'in'} [placeOrOffset] To be used when a model item was passed as `selectable`.
+     * @param content The content to insert.
+     * @param selectable The selection into which the content should be inserted.
+     * If not provided the current model document selection will be used.
+     * @param placeOrOffset To be used when a model item was passed as `selectable`.
      * This param defines a position in relation to that item.
-     * @returns {module:engine/model/range~Range} Range which contains all the performed changes. This is a range that, if removed,
-     * would return the model to the state before the insertion. If no changes were preformed by `insertContent`, returns a range collapsed
      * at the insertion position.
      */
     insertContent(content, selectable, placeOrOffset) {
@@ -447,56 +384,60 @@ export default class Model extends Observable {
      *
      * Use the following code to insert an object at the current selection and keep the selection on the inserted element:
      *
-     *		const rawHtmlEmbedElement = writer.createElement( 'rawHtml' );
+     * ```ts
+     * const rawHtmlEmbedElement = writer.createElement( 'rawHtml' );
      *
-     *		model.insertObject( rawHtmlEmbedElement, null, null, {
-     *			setSelection: 'on'
-     *		} );
+     * model.insertObject( rawHtmlEmbedElement, null, null, {
+     * 	setSelection: 'on'
+     * } );
+     * ```
      *
      * Use the following code to insert an object at the current selection and nudge the selection after the inserted object:
      *
-     *		const pageBreakElement = writer.createElement( 'pageBreak' );
+     * ```ts
+     * const pageBreakElement = writer.createElement( 'pageBreak' );
      *
-     *		model.insertObject( pageBreakElement, null, null, {
-     *			setSelection: 'after'
-     *		} );
+     * model.insertObject( pageBreakElement, null, null, {
+     * 	setSelection: 'after'
+     * } );
+     * ```
      *
      * Use the following code to insert an object at the current selection and avoid splitting the content (non-destructive insertion):
      *
-     *		const tableElement = writer.createElement( 'table' );
+     * ```ts
+     * const tableElement = writer.createElement( 'table' );
      *
-     *		model.insertObject( tableElement, null, null, {
-     *			findOptimalPosition: 'auto'
-     *		} );
+     * model.insertObject( tableElement, null, null, {
+     * 	findOptimalPosition: 'auto'
+     * } );
+     * ```
      *
      * Use the following code to insert an object at the specific range (also: replace the content of the range):
      *
-     *		const tableElement = writer.createElement( 'table' );
-     *		const range = model.createRangeOn( model.document.getRoot().getChild( 1 ) );
+     * ```ts
+     * const tableElement = writer.createElement( 'table' );
+     * const range = model.createRangeOn( model.document.getRoot().getChild( 1 ) );
      *
-     *		model.insertObject( tableElement, range );
+     * model.insertObject( tableElement, range );
+     * ```
      *
-     * @param {module:engine/model/element~Element} object An object to be inserted into the model document.
-     * @param {module:engine/model/selection~Selectable} [selectable=model.document.selection]
-     * A selectable where the content should be inserted. If not specified, the current
+     * @param object An object to be inserted into the model document.
+     * @param selectable A selectable where the content should be inserted. If not specified, the current
      * {@link module:engine/model/document~Document#selection document selection} will be used instead.
-     * @param {Number|'before'|'end'|'after'|'on'|'in'} placeOrOffset Specifies the exact place or offset for the insertion to take place,
-     * relative to `selectable`.
-     * @param {Object} [options] Additional options.
-     * @param {'auto'|'before'|'after'} [options.findOptimalPosition] An option that, when set, adjusts the insertion position (relative to
+     * @param placeOrOffset Specifies the exact place or offset for the insertion to take place, relative to `selectable`.
+     * @param options Additional options.
+     * @param options.findOptimalPosition An option that, when set, adjusts the insertion position (relative to
      * `selectable` and `placeOrOffset`) so that the content of `selectable` is not split upon insertion (a.k.a. non-destructive insertion).
      * * When `'auto'`, the algorithm will decide whether to insert the object before or after `selectable` to avoid content splitting.
      * * When `'before'`, the closest position before `selectable` will be used that will not result in content splitting.
      * * When `'after'`, the closest position after `selectable` will be used that will not result in content splitting.
      *
      * Note that this option only works for block objects. Inline objects are inserted into text and do not split blocks.
-     * @param {'on'|'after'} [options.setSelection] An option that, when set, moves the
+     * @param options.setSelection An option that, when set, moves the
      * {@link module:engine/model/document~Document#selection document selection} after inserting the object.
      * * When `'on'`, the document selection will be set on the inserted object.
      * * When `'after'`, the document selection will move to the closest text node after the inserted object. If there is no
      * such text node, a paragraph will be created and the document selection will be moved inside it.
-     * @returns {module:engine/model/range~Range} A range which contains all the performed changes. This is a range that, if removed,
-     * would return the model to the state before the insertion. If no changes were preformed by `insertObject()`, returns a range collapsed
      * at the insertion position.
      */
     insertObject(object, selectable, placeOrOffset, options) {
@@ -514,10 +455,8 @@ export default class Model extends Observable {
      * That needs to be done in order to ensure that other features which use `deleteContent()` will work well with tables.
      *
      * @fires deleteContent
-     * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
-     * Selection of which the content should be deleted.
-     * @param {Object} [options]
-     * @param {Boolean} [options.leaveUnmerged=false] Whether to merge elements after removing the content of the selection.
+     * @param selection Selection of which the content should be deleted.
+     * @param options.leaveUnmerged Whether to merge elements after removing the content of the selection.
      *
      * For example `<heading1>x[x</heading1><paragraph>y]y</paragraph>` will become:
      *
@@ -527,7 +466,7 @@ export default class Model extends Observable {
      * Note: {@link module:engine/model/schema~Schema#isObject object} and {@link module:engine/model/schema~Schema#isLimit limit}
      * elements will not be merged.
      *
-     * @param {Boolean} [options.doNotResetEntireContent=false] Whether to skip replacing the entire content with a
+     * @param options.doNotResetEntireContent Whether to skip replacing the entire content with a
      * paragraph when the entire content was selected.
      *
      * For example `<heading1>[x</heading1><paragraph>y]</paragraph>` will become:
@@ -535,7 +474,7 @@ export default class Model extends Observable {
      * * `<paragraph>^</paragraph>` with the option disabled (`doNotResetEntireContent == false`)
      * * `<heading1>^</heading1>` with enabled (`doNotResetEntireContent == true`)
      *
-     * @param {Boolean} [options.doNotAutoparagraph=false] Whether to create a paragraph if after content deletion selection is moved
+     * @param options.doNotAutoparagraph Whether to create a paragraph if after content deletion selection is moved
      * to a place where text cannot be inserted.
      *
      * For example `<paragraph>x</paragraph>[<imageBlock src="foo.jpg"></imageBlock>]` will become:
@@ -547,7 +486,7 @@ export default class Model extends Observable {
      *
      * `[<imageBlock src="foo.jpg"></imageBlock>]` -> `<paragraph>[]</paragraph>`.
      *
-     * @param {'forward'|'backward'} [options.direction='backward'] The direction in which the content is being consumed.
+     * @param options.direction The direction in which the content is being consumed.
      * Deleting backward corresponds to using the <kbd>Backspace</kbd> key, while deleting content forward corresponds to
      * the <kbd>Shift</kbd>+<kbd>Backspace</kbd> keystroke.
      */
@@ -577,12 +516,10 @@ export default class Model extends Observable {
      * **Note:** if you extend a forward selection in a backward direction you will in fact shrink it.
      *
      * @fires modifySelection
-     * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
-     * The selection to modify.
-     * @param {Object} [options]
-     * @param {'forward'|'backward'} [options.direction='forward'] The direction in which the selection should be modified.
-     * @param {'character'|'codePoint'|'word'} [options.unit='character'] The unit by which selection should be modified.
-     * @param {Boolean} [options.treatEmojiAsSingleUnit=false] Whether multi-characer emoji sequences should be handled as single unit.
+     * @param selection The selection to modify.
+     * @param options.direction The direction in which the selection should be modified.
+     * @param options.unit The unit by which selection should be modified.
+     * @param options.treatEmojiAsSingleUnit Whether multi-characer emoji sequences should be handled as single unit.
      */
     modifySelection(selection, options) {
         modifySelection(this, selection, options);
@@ -595,8 +532,8 @@ export default class Model extends Observable {
      * ```html
      * <paragraph>x</paragraph>
      * <blockQuote>
-     *	<paragraph>y</paragraph>
-     *	<heading1>fir[st</heading1>
+     * 	<paragraph>y</paragraph>
+     * 	<heading1>fir[st</heading1>
      * </blockQuote>
      * <paragraph>se]cond</paragraph>
      * <paragraph>z</paragraph>
@@ -606,15 +543,13 @@ export default class Model extends Observable {
      *
      * ```html
      * <blockQuote>
-     *	<heading1>st</heading1>
+     * 	<heading1>st</heading1>
      * </blockQuote>
      * <paragraph>se</paragraph>
      * ```
      *
      * @fires getSelectedContent
-     * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
-     * The selection of which content will be returned.
-     * @returns {module:engine/model/documentfragment~DocumentFragment}
+     * @param selection The selection of which content will be returned.
      */
     getSelectedContent(selection) {
         return getSelectedContent(this, selection);
@@ -635,11 +570,9 @@ export default class Model extends Observable {
      * However, a range containing an `<imageBlock></imageBlock>` (which would normally be marked in the schema as an object element)
      * is considered non-empty.
      *
-     * @param {module:engine/model/range~Range|module:engine/model/element~Element} rangeOrElement Range or element to check.
-     * @param {Object} [options]
-     * @param {Boolean} [options.ignoreWhitespaces] Whether text node with whitespaces only should be considered empty.
-     * @param {Boolean} [options.ignoreMarkers] Whether markers should be ignored.
-     * @returns {Boolean}
+     * @param rangeOrElement Range or element to check.
+     * @param options.ignoreWhitespaces Whether text node with whitespaces only should be considered empty.
+     * @param options.ignoreMarkers Whether markers should be ignored.
      */
     hasContent(rangeOrElement, options = {}) {
         const range = rangeOrElement instanceof ModelRange ? rangeOrElement : ModelRange._createIn(rangeOrElement);
@@ -678,11 +611,9 @@ export default class Model extends Observable {
      * Note: This method is also available as
      * {@link module:engine/model/writer~Writer#createPositionFromPath `Writer#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 new ModelPosition(root, path, stickiness);
@@ -704,9 +635,8 @@ export default class Model extends Observable {
      * Note: This method is also available as
      * {@link module:engine/model/writer~Writer#createPositionAt `Writer#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}.
+     * @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}.
      */
     createPositionAt(itemOrPosition, offset) {
         return ModelPosition._createAt(itemOrPosition, offset);
@@ -717,8 +647,7 @@ export default class Model extends Observable {
      * Note: This method is also available as
      * {@link module:engine/model/writer~Writer#createPositionAfter `Writer#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 ModelPosition._createAfter(item);
@@ -729,8 +658,7 @@ export default class Model extends Observable {
      * Note: This method is also available as
      * {@link module:engine/model/writer~Writer#createPositionBefore `Writer#createPositionBefore()`}.
      *
-     * @param {module:engine/model/item~Item} item Item before which the position should be placed.
-     * @returns {module:engine/model/position~Position}
+     * @param item Item before which the position should be placed.
      */
     createPositionBefore(item) {
         return ModelPosition._createBefore(item);
@@ -741,14 +669,14 @@ export default class Model extends Observable {
      * Note: This method is also available as
      * {@link module:engine/model/writer~Writer#createRange `Writer#createRange()`}:
      *
-     *		model.change( writer => {
-     *			const range = writer.createRange( start, end );
-     *		} );
+     * ```ts
+     * model.change( writer => {
+     * 	const range = writer.createRange( start, end );
+     * } );
+     * ```
      *
-     * @param {module:engine/model/position~Position} start Start position.
-     * @param {module:engine/model/position~Position} [end] End position. If not set, the range will be collapsed
-     * to the `start` position.
-     * @returns {module:engine/model/range~Range}
+     * @param start Start position.
+     * @param end End position. If not set, the range will be collapsed to the `start` position.
      */
     createRange(start, end) {
         return new ModelRange(start, end);
@@ -760,12 +688,13 @@ export default class Model extends Observable {
      * Note: This method is also available as
      * {@link module:engine/model/writer~Writer#createRangeIn `Writer#createRangeIn()`}:
      *
-     *		model.change( writer => {
-     *			const range = writer.createRangeIn( paragraph );
-     *		} );
+     * ```ts
+     * model.change( writer => {
+     * 	const range = writer.createRangeIn( paragraph );
+     * } );
+     * ```
      *
-     * @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 ModelRange._createIn(element);
@@ -776,12 +705,13 @@ export default class Model extends Observable {
      * Note: This method is also available on `writer` instance as
      * {@link module:engine/model/writer~Writer#createRangeOn `Writer.createRangeOn()`}:
      *
-     *		model.change( writer => {
-     *			const range = writer.createRangeOn( paragraph );
-     *		} );
+     * ```ts
+     * model.change( writer => {
+     * 	const range = writer.createRangeOn( paragraph );
+     * } );
+     * ```
      *
-     * @param {module:engine/model/item~Item} item
-     * @returns {module:engine/model/range~Range}
+     * @param item
      */
     createRangeOn(item) {
         return ModelRange._createOn(item);
@@ -793,53 +723,49 @@ export default class Model extends Observable {
      * Note: This method is also available as
      * {@link module:engine/model/writer~Writer#createSelection `Writer#createSelection()`}.
      *
-     *		// Creates empty selection without ranges.
-     *		const selection = writer.createSelection();
+     * ```ts
+     * // Creates empty selection without ranges.
+     * const selection = writer.createSelection();
      *
-     *		// Creates selection at the given range.
-     *		const range = writer.createRange( start, end );
-     *		const selection = writer.createSelection( range );
+     * // Creates selection at the given range.
+     * const range = writer.createRange( start, end );
+     * const selection = writer.createSelection( range );
      *
-     *		// Creates selection at the given ranges
-     *		const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
-     *		const selection = writer.createSelection( ranges );
+     * // Creates selection at the given ranges
+     * const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
+     * const selection = writer.createSelection( ranges );
      *
-     *		// Creates selection from the other selection.
-     *		// Note: It doesn't copies selection attributes.
-     *		const otherSelection = writer.createSelection();
-     *		const selection = writer.createSelection( otherSelection );
+     * // Creates selection from the other selection.
+     * // Note: It doesn't copies selection attributes.
+     * const otherSelection = writer.createSelection();
+     * const selection = writer.createSelection( otherSelection );
      *
-     *		// Creates selection from the given document selection.
-     *		// Note: It doesn't copies selection attributes.
-     *		const documentSelection = model.document.selection;
-     *		const selection = writer.createSelection( documentSelection );
+     * // Creates selection from the given document selection.
+     * // Note: It doesn't copies selection attributes.
+     * const documentSelection = model.document.selection;
+     * const selection = writer.createSelection( documentSelection );
      *
-     *		// Creates selection at the given position.
-     *		const position = writer.createPositionFromPath( root, path );
-     *		const selection = writer.createSelection( position );
+     * // Creates selection at the given position.
+     * const position = writer.createPositionFromPath( root, path );
+     * const selection = writer.createSelection( position );
      *
-     *		// Creates selection at the given offset in the given element.
-     *		const paragraph = writer.createElement( 'paragraph' );
-     *		const selection = writer.createSelection( paragraph, offset );
+     * // Creates selection at the given offset in the given element.
+     * const paragraph = writer.createElement( 'paragraph' );
+     * const selection = writer.createSelection( paragraph, offset );
      *
-     *		// Creates a range inside an {@link module:engine/model/element~Element element} which starts before the
-     *		// first child of that element and ends after the last child of that element.
-     *		const selection = writer.createSelection( paragraph, 'in' );
+     * // Creates a range inside an {@link module:engine/model/element~Element element} which starts before the
+     * // first child of that element and ends after the last child of that element.
+     * const selection = writer.createSelection( paragraph, 'in' );
      *
-     *		// Creates a range on an {@link module:engine/model/item~Item item} which starts before the item and ends
-     *		// just after the item.
-     *		const selection = writer.createSelection( paragraph, 'on' );
+     * // Creates a range on an {@link module:engine/model/item~Item item} which starts before the item and ends
+     * // just after the item.
+     * const selection = writer.createSelection( paragraph, 'on' );
      *
-     *		// Additional options (`'backward'`) can be specified as the last argument.
+     * // Additional options (`'backward'`) can be specified as the last argument.
      *
-     *		// Creates backward selection.
-     *		const selection = writer.createSelection( range, { backward: true } );
-     *
-     * @param {module:engine/model/selection~Selectable} selectable
-     * @param {Number|'before'|'end'|'after'|'on'|'in'} [optionsOrPlaceOrOffset] 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}
+     * // Creates backward selection.
+     * const selection = writer.createSelection( range, { backward: true } );
+     * ```
      */
     createSelection(...args) {
         return new ModelSelection(...args);
@@ -852,8 +778,7 @@ export default class Model extends Observable {
      * * {@link #change `change()`},
      * * {@link #enqueueChange `enqueueChange()`}.
      *
-     * @param {Object} [type] {@link module:engine/model/batch~Batch#constructor The type} of the batch.
-     * @returns {module:engine/model/batch~Batch}
+     * @param type {@link module:engine/model/batch~Batch#constructor The type} of the batch.
      */
     createBatch(type) {
         return new Batch(type);
@@ -863,8 +788,7 @@ export default class Model extends Observable {
      *
      * This is an alias for {@link module:engine/model/operation/operationfactory~OperationFactory.fromJSON `OperationFactory.fromJSON()`}.
      *
-     * @param {Object} json Deserialized JSON object.
-     * @returns {module:engine/model/operation/operation~Operation}
+     * @param json Deserialized JSON object.
      */
     createOperationFromJSON(json) {
         return OperationFactory.fromJSON(json, this.document);
@@ -880,8 +804,6 @@ export default class Model extends Observable {
      * Common part of {@link module:engine/model/model~Model#change} and {@link module:engine/model/model~Model#enqueueChange}
      * which calls callbacks and returns array of values returned by these callbacks.
      *
-     * @private
-     * @returns {Array.<*>} Array of values returned by callbacks.
      */
     _runPendingChanges() {
         const ret = [];