@ckeditor/ckeditor5-engine 35.3.2 → 36.0.0

package/src/model/schema.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
  */
 /**
@@ -10,8 +10,7 @@ import Position from './position';
 import Range from './range';
 import Text from './text';
 import TreeWalker from './treewalker';
-import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
-import { Observable } from '@ckeditor/ckeditor5-utils/src/observablemixin';
+import { CKEditorError, ObservableMixin } from '@ckeditor/ckeditor5-utils';
 /**
  * The model's schema. It defines the allowed and disallowed structures of nodes as well as nodes' attributes.
  * The schema is usually defined by the features and based on them, the editing framework and features
@@ -23,11 +22,9 @@ import { Observable } from '@ckeditor/ckeditor5-utils/src/observablemixin';
  *
  * * The {@glink framework/guides/architecture/editing-engine#schema schema section} of the
  * {@glink framework/guides/architecture/editing-engine Introduction to the Editing engine architecture} guide.
- * * The {@glink framework/guides/deep-dive/schema Schema deep dive} guide.
- *
- * @mixes module:utils/observablemixin~ObservableMixin
+ * * The {@glink framework/guides/deep-dive/schema Schema deep-dive guide}.
  */
-export default class Schema extends Observable {
+export default class Schema extends ObservableMixin() {
     /**
      * Creates a schema instance.
      */
@@ -36,9 +33,6 @@ export default class Schema extends Observable {
         this._sourceDefinitions = {};
         /**
          * A dictionary containing attribute properties.
-         *
-         * @private
-         * @member {Object.<String,AttributeProperties>}
          */
         this._attributeProperties = {};
         this.decorate('checkChild');
@@ -54,12 +48,11 @@ export default class Schema extends Observable {
     /**
      * Registers a schema item. Can only be called once for every item name.
      *
-     *		schema.register( 'paragraph', {
-     *			inheritAllFrom: '$block'
-     *		} );
-     *
-     * @param {String} itemName
-     * @param {module:engine/model/schema~SchemaItemDefinition} definition
+     * ```ts
+     * schema.register( 'paragraph', {
+     * 	inheritAllFrom: '$block'
+     * } );
+     * ```
      */
     register(itemName, definition) {
         if (this._sourceDefinitions[itemName]) {
@@ -97,23 +90,22 @@ export default class Schema extends Observable {
      * Extending properties such as `allowIn` will add more items to the existing properties,
      * while redefining properties such as `isBlock` will override the previously defined ones.
      *
-     *		schema.register( 'foo', {
-     *			allowIn: '$root',
-     *			isBlock: true;
-     *		} );
-     *		schema.extend( 'foo', {
-     *			allowIn: 'blockQuote',
-     *			isBlock: false
-     *		} );
-     *
-     *		schema.getDefinition( 'foo' );
-     *		//	{
-     *		//		allowIn: [ '$root', 'blockQuote' ],
-     *		// 		isBlock: false
-     *		//	}
-     *
-     * @param {String} itemName
-     * @param {module:engine/model/schema~SchemaItemDefinition} definition
+     * ```ts
+     * schema.register( 'foo', {
+     * 	allowIn: '$root',
+     * 	isBlock: true;
+     * } );
+     * schema.extend( 'foo', {
+     * 	allowIn: 'blockQuote',
+     * 	isBlock: false
+     * } );
+     *
+     * schema.getDefinition( 'foo' );
+     * //	{
+     * //		allowIn: [ '$root', 'blockQuote' ],
+     * // 		isBlock: false
+     * //	}
+     * ```
      */
     extend(itemName, definition) {
         if (!this._sourceDefinitions[itemName]) {
@@ -140,8 +132,6 @@ export default class Schema extends Observable {
      * checking a list of all block elements, etc).
      * Use specific methods (such as {@link #checkChild `checkChild()`} or {@link #isLimit `isLimit()`})
      * in other cases.
-     *
-     * @returns {Object.<String,module:engine/model/schema~SchemaCompiledItemDefinition>}
      */
     getDefinitions() {
         if (!this._compiledDefinitions) {
@@ -156,9 +146,6 @@ export default class Schema extends Observable {
      * checking a list of all block elements, etc).
      * Use specific methods (such as {@link #checkChild `checkChild()`} or {@link #isLimit `isLimit()`})
      * in other cases.
-     *
-     * @param {module:engine/model/item~Item|module:engine/model/schema~SchemaContextItem|String} item
-     * @returns {module:engine/model/schema~SchemaCompiledItemDefinition}
      */
     getDefinition(item) {
         let itemName;
@@ -177,12 +164,11 @@ export default class Schema extends Observable {
     /**
      * Returns `true` if the given item is registered in the schema.
      *
-     *		schema.isRegistered( 'paragraph' ); // -> true
-     *		schema.isRegistered( editor.model.document.getRoot() ); // -> true
-     *		schema.isRegistered( 'foo' ); // -> false
-     *
-     * @param {module:engine/model/item~Item|module:engine/model/schema~SchemaContextItem|String} item
-     * @returns {Boolean}
+     * ```ts
+     * schema.isRegistered( 'paragraph' ); // -> true
+     * schema.isRegistered( editor.model.document.getRoot() ); // -> true
+     * schema.isRegistered( 'foo' ); // -> false
+     * ```
      */
     isRegistered(item) {
         return !!this.getDefinition(item);
@@ -191,17 +177,16 @@ export default class Schema extends Observable {
      * Returns `true` if the given item is defined to be
      * a block by the {@link module:engine/model/schema~SchemaItemDefinition}'s `isBlock` property.
      *
-     *		schema.isBlock( 'paragraph' ); // -> true
-     *		schema.isBlock( '$root' ); // -> false
+     * ```ts
+     * schema.isBlock( 'paragraph' ); // -> true
+     * schema.isBlock( '$root' ); // -> false
      *
-     *		const paragraphElement = writer.createElement( 'paragraph' );
-     *		schema.isBlock( paragraphElement ); // -> true
+     * const paragraphElement = writer.createElement( 'paragraph' );
+     * schema.isBlock( paragraphElement ); // -> true
+     * ```
      *
      * See the {@glink framework/guides/deep-dive/schema#block-elements Block elements} section of
-     * the {@glink framework/guides/deep-dive/schema Schema deep dive} guide for more details.
-     *
-     * @param {module:engine/model/item~Item|module:engine/model/schema~SchemaContextItem|String} item
-     * @returns {Boolean}
+     * the {@glink framework/guides/deep-dive/schema Schema deep-dive guide} for more details.
      */
     isBlock(item) {
         const def = this.getDefinition(item);
@@ -216,16 +201,15 @@ export default class Schema extends Observable {
      * {@link module:engine/model/schema~SchemaItemDefinition#isObject `isObject`} property
      * was set to `true`.
      *
-     *		schema.isLimit( 'paragraph' ); // -> false
-     *		schema.isLimit( '$root' ); // -> true
-     *		schema.isLimit( editor.model.document.getRoot() ); // -> true
-     *		schema.isLimit( 'imageBlock' ); // -> true
+     * ```ts
+     * schema.isLimit( 'paragraph' ); // -> false
+     * schema.isLimit( '$root' ); // -> true
+     * schema.isLimit( editor.model.document.getRoot() ); // -> true
+     * schema.isLimit( 'imageBlock' ); // -> true
+     * ```
      *
      * See the {@glink framework/guides/deep-dive/schema#limit-elements Limit elements} section of
-     * the {@glink framework/guides/deep-dive/schema Schema deep dive} guide for more details.
-     *
-     * @param {module:engine/model/item~Item|module:engine/model/schema~SchemaContextItem|String} item
-     * @returns {Boolean}
+     * the {@glink framework/guides/deep-dive/schema Schema deep-dive guide} for more details.
      */
     isLimit(item) {
         const def = this.getDefinition(item);
@@ -242,17 +226,16 @@ export default class Schema extends Observable {
      * {@link module:engine/model/schema~SchemaItemDefinition#isObject `isObject`} property
      * was set to `true`.
      *
-     *		schema.isObject( 'paragraph' ); // -> false
-     *		schema.isObject( 'imageBlock' ); // -> true
+     * ```ts
+     * schema.isObject( 'paragraph' ); // -> false
+     * schema.isObject( 'imageBlock' ); // -> true
      *
-     *		const imageElement = writer.createElement( 'imageBlock' );
-     *		schema.isObject( imageElement ); // -> true
+     * const imageElement = writer.createElement( 'imageBlock' );
+     * schema.isObject( imageElement ); // -> true
+     * ```
      *
      * See the {@glink framework/guides/deep-dive/schema#object-elements Object elements} section of
-     * the {@glink framework/guides/deep-dive/schema Schema deep dive} guide for more details.
-     *
-     * @param {module:engine/model/item~Item|module:engine/model/schema~SchemaContextItem|String} item
-     * @returns {Boolean}
+     * the {@glink framework/guides/deep-dive/schema Schema deep-dive guide} for more details.
      */
     isObject(item) {
         const def = this.getDefinition(item);
@@ -267,17 +250,16 @@ export default class Schema extends Observable {
      * Returns `true` if the given item is defined to be
      * an inline element by the {@link module:engine/model/schema~SchemaItemDefinition}'s `isInline` property.
      *
-     *		schema.isInline( 'paragraph' ); // -> false
-     *		schema.isInline( 'softBreak' ); // -> true
+     * ```ts
+     * schema.isInline( 'paragraph' ); // -> false
+     * schema.isInline( 'softBreak' ); // -> true
      *
-     *		const text = writer.createText( 'foo' );
-     *		schema.isInline( text ); // -> true
+     * const text = writer.createText( 'foo' );
+     * schema.isInline( text ); // -> true
+     * ```
      *
      * See the {@glink framework/guides/deep-dive/schema#inline-elements Inline elements} section of
-     * the {@glink framework/guides/deep-dive/schema Schema deep dive} guide for more details.
-     *
-     * @param {module:engine/model/item~Item|module:engine/model/schema~SchemaContextItem|String} item
-     * @returns {Boolean}
+     * the {@glink framework/guides/deep-dive/schema Schema deep-dive guide} for more details.
      */
     isInline(item) {
         const def = this.getDefinition(item);
@@ -287,19 +269,18 @@ export default class Schema extends Observable {
      * Returns `true` if the given item is defined to be
      * a selectable element by the {@link module:engine/model/schema~SchemaItemDefinition}'s `isSelectable` property.
      *
-     *		schema.isSelectable( 'paragraph' ); // -> false
-     *		schema.isSelectable( 'heading1' ); // -> false
-     *		schema.isSelectable( 'imageBlock' ); // -> true
-     *		schema.isSelectable( 'tableCell' ); // -> true
+     * ```ts
+     * schema.isSelectable( 'paragraph' ); // -> false
+     * schema.isSelectable( 'heading1' ); // -> false
+     * schema.isSelectable( 'imageBlock' ); // -> true
+     * schema.isSelectable( 'tableCell' ); // -> true
      *
-     *		const text = writer.createText( 'foo' );
-     *		schema.isSelectable( text ); // -> false
+     * const text = writer.createText( 'foo' );
+     * schema.isSelectable( text ); // -> false
+     * ```
      *
      * See the {@glink framework/guides/deep-dive/schema#selectable-elements Selectable elements section} of
-     * the {@glink framework/guides/deep-dive/schema Schema deep dive} guide for more details.
-     *
-     * @param {module:engine/model/item~Item|module:engine/model/schema~SchemaContextItem|String} item
-     * @returns {Boolean}
+     * the {@glink framework/guides/deep-dive/schema Schema deep-dive guide} for more details.
      */
     isSelectable(item) {
         const def = this.getDefinition(item);
@@ -312,19 +293,18 @@ export default class Schema extends Observable {
      * Returns `true` if the given item is defined to be
      * a content by the {@link module:engine/model/schema~SchemaItemDefinition}'s `isContent` property.
      *
-     *		schema.isContent( 'paragraph' ); // -> false
-     *		schema.isContent( 'heading1' ); // -> false
-     *		schema.isContent( 'imageBlock' ); // -> true
-     *		schema.isContent( 'horizontalLine' ); // -> true
+     * ```ts
+     * schema.isContent( 'paragraph' ); // -> false
+     * schema.isContent( 'heading1' ); // -> false
+     * schema.isContent( 'imageBlock' ); // -> true
+     * schema.isContent( 'horizontalLine' ); // -> true
      *
-     *		const text = writer.createText( 'foo' );
-     *		schema.isContent( text ); // -> true
+     * const text = writer.createText( 'foo' );
+     * schema.isContent( text ); // -> true
+     * ```
      *
      * See the {@glink framework/guides/deep-dive/schema#content-elements Content elements section} of
-     * the {@glink framework/guides/deep-dive/schema Schema deep dive} guide for more details.
-     *
-     * @param {module:engine/model/item~Item|module:engine/model/schema~SchemaContextItem|String} item
-     * @returns {Boolean}
+     * the {@glink framework/guides/deep-dive/schema Schema deep-dive guide} for more details.
      */
     isContent(item) {
         const def = this.getDefinition(item);
@@ -336,12 +316,14 @@ export default class Schema extends Observable {
     /**
      * Checks whether the given node (`child`) can be a child of the given context.
      *
-     *		schema.checkChild( model.document.getRoot(), paragraph ); // -> false
+     * ```ts
+     * schema.checkChild( model.document.getRoot(), paragraph ); // -> false
      *
-     *		schema.register( 'paragraph', {
-     *			allowIn: '$root'
-     *		} );
-     *		schema.checkChild( model.document.getRoot(), paragraph ); // -> true
+     * schema.register( 'paragraph', {
+     * 	allowIn: '$root'
+     * } );
+     * schema.checkChild( model.document.getRoot(), paragraph ); // -> true
+     * ```
      *
      * Note: When verifying whether the given node can be a child of the given context, the
      * schema also verifies the entire context &mdash; from its root to its last element. Therefore, it is possible
@@ -349,9 +331,8 @@ export default class Schema extends Observable {
      * It happens if one of the context's elements does not allow its child.
      *
      * @fires checkChild
-     * @param {module:engine/model/schema~SchemaContextDefinition} context The context in which the child will be checked.
-     * @param {module:engine/model/node~Node|String} def The child to check.
-     * @returns {Boolean}
+     * @param context The context in which the child will be checked.
+     * @param def The child to check.
      */
     checkChild(context, def) {
         // Note: context and child are already normalized here to a SchemaContext and SchemaCompiledItemDefinition.
@@ -364,17 +345,17 @@ export default class Schema extends Observable {
      * Checks whether the given attribute can be applied in the given context (on the last
      * item of the context).
      *
-     *		schema.checkAttribute( textNode, 'bold' ); // -> false
+     * ```ts
+     * schema.checkAttribute( textNode, 'bold' ); // -> false
      *
-     *		schema.extend( '$text', {
-     *			allowAttributes: 'bold'
-     *		} );
-     *		schema.checkAttribute( textNode, 'bold' ); // -> true
+     * schema.extend( '$text', {
+     * 	allowAttributes: 'bold'
+     * } );
+     * schema.checkAttribute( textNode, 'bold' ); // -> true
+     * ```
      *
      * @fires checkAttribute
-     * @param {module:engine/model/schema~SchemaContextDefinition} context The context in which the attribute will be checked.
-     * @param {String} attributeName
-     * @returns {Boolean}
+     * @param context The context in which the attribute will be checked.
      */
     checkAttribute(context, attributeName) {
         const def = this.getDefinition(context.last);
@@ -394,10 +375,8 @@ export default class Schema extends Observable {
      * Instead of elements, you can pass the instance of the {@link module:engine/model/position~Position} class as the
      * `positionOrBaseElement`. It means that the elements before and after the position will be checked whether they can be merged.
      *
-     * @param {module:engine/model/position~Position|module:engine/model/element~Element} positionOrBaseElement The position or base
-     * element to which the `elementToMerge` will be merged.
-     * @param {module:engine/model/element~Element} elementToMerge The element to merge. Required if `positionOrBaseElement` is an element.
-     * @returns {Boolean}
+     * @param positionOrBaseElement The position or base element to which the `elementToMerge` will be merged.
+     * @param elementToMerge The element to merge. Required if `positionOrBaseElement` is an element.
      */
     checkMerge(positionOrBaseElement, elementToMerge) {
         if (positionOrBaseElement instanceof Position) {
@@ -440,28 +419,32 @@ export default class Schema extends Observable {
      *
      * Example:
      *
-     *		// Disallow heading1 directly inside a blockQuote.
-     *		schema.addChildCheck( ( context, childDefinition ) => {
-     *			if ( context.endsWith( 'blockQuote' ) && childDefinition.name == 'heading1' ) {
-     *				return false;
-     *			}
-     *		} );
+     * ```ts
+     * // Disallow heading1 directly inside a blockQuote.
+     * schema.addChildCheck( ( context, childDefinition ) => {
+     * 	if ( context.endsWith( 'blockQuote' ) && childDefinition.name == 'heading1' ) {
+     * 		return false;
+     * 	}
+     * } );
+     * ```
      *
      * Which translates to:
      *
-     *		schema.on( 'checkChild', ( evt, args ) => {
-     *			const context = args[ 0 ];
-     *			const childDefinition = args[ 1 ];
-     *
-     *			if ( context.endsWith( 'blockQuote' ) && childDefinition && childDefinition.name == 'heading1' ) {
-     *				// Prevent next listeners from being called.
-     *				evt.stop();
-     *				// Set the checkChild()'s return value.
-     *				evt.return = false;
-     *			}
-     *		}, { priority: 'high' } );
-     *
-     * @param {Function} callback The callback to be called. It is called with two parameters:
+     * ```ts
+     * schema.on( 'checkChild', ( evt, args ) => {
+     * 	const context = args[ 0 ];
+     * 	const childDefinition = args[ 1 ];
+     *
+     * 	if ( context.endsWith( 'blockQuote' ) && childDefinition && childDefinition.name == 'heading1' ) {
+     * 		// Prevent next listeners from being called.
+     * 		evt.stop();
+     * 		// Set the checkChild()'s return value.
+     * 		evt.return = false;
+     * 	}
+     * }, { priority: 'high' } );
+     * ```
+     *
+     * @param callback The callback to be called. It is called with two parameters:
      * {@link module:engine/model/schema~SchemaContext} (context) instance and
      * {@link module:engine/model/schema~SchemaCompiledItemDefinition} (child-to-check definition).
      * The callback may return `true/false` to override `checkChild()`'s return value. If it does not return
@@ -495,28 +478,32 @@ export default class Schema extends Observable {
      *
      * Example:
      *
-     *		// Disallow bold on $text inside heading1.
-     *		schema.addAttributeCheck( ( context, attributeName ) => {
-     *			if ( context.endsWith( 'heading1 $text' ) && attributeName == 'bold' ) {
-     *				return false;
-     *			}
-     *		} );
+     * ```ts
+     * // Disallow bold on $text inside heading1.
+     * schema.addAttributeCheck( ( context, attributeName ) => {
+     * 	if ( context.endsWith( 'heading1 $text' ) && attributeName == 'bold' ) {
+     * 		return false;
+     * 	}
+     * } );
+     * ```
      *
      * Which translates to:
      *
-     *		schema.on( 'checkAttribute', ( evt, args ) => {
-     *			const context = args[ 0 ];
-     *			const attributeName = args[ 1 ];
-     *
-     *			if ( context.endsWith( 'heading1 $text' ) && attributeName == 'bold' ) {
-     *				// Prevent next listeners from being called.
-     *				evt.stop();
-     *				// Set the checkAttribute()'s return value.
-     *				evt.return = false;
-     *			}
-     *		}, { priority: 'high' } );
-     *
-     * @param {Function} callback The callback to be called. It is called with two parameters:
+     * ```ts
+     * schema.on( 'checkAttribute', ( evt, args ) => {
+     * 	const context = args[ 0 ];
+     * 	const attributeName = args[ 1 ];
+     *
+     * 	if ( context.endsWith( 'heading1 $text' ) && attributeName == 'bold' ) {
+     * 		// Prevent next listeners from being called.
+     * 		evt.stop();
+     * 		// Set the checkAttribute()'s return value.
+     * 		evt.return = false;
+     * 	}
+     * }, { priority: 'high' } );
+     * ```
+     *
+     * @param callback The callback to be called. It is called with two parameters:
      * {@link module:engine/model/schema~SchemaContext} (context) instance and attribute name.
      * The callback may return `true/false` to override `checkAttribute()`'s return value. If it does not return
      * a boolean value, the default algorithm (or other callbacks) will define `checkAttribute()`'s return value.
@@ -535,38 +522,44 @@ export default class Schema extends Observable {
      * {@link module:engine/model/schema~AttributeProperties `AttributeProperties#isFormatting` property} is
      * used to mark formatting attributes (like `bold` or `italic`).
      *
-     *		// Mark bold as a formatting attribute.
-     *		schema.setAttributeProperties( 'bold', {
-     *			isFormatting: true
-     *		} );
+     * ```ts
+     * // Mark bold as a formatting attribute.
+     * schema.setAttributeProperties( 'bold', {
+     * 	isFormatting: true
+     * } );
      *
-     *		// Override code not to be considered a formatting markup.
-     *		schema.setAttributeProperties( 'code', {
-     *			isFormatting: false
-     *		} );
+     * // Override code not to be considered a formatting markup.
+     * schema.setAttributeProperties( 'code', {
+     * 	isFormatting: false
+     * } );
+     * ```
      *
      * Properties are not limited to members defined in the
      * {@link module:engine/model/schema~AttributeProperties `AttributeProperties` type} and you can also use custom properties:
      *
-     *		schema.setAttributeProperties( 'blockQuote', {
-     *			customProperty: 'value'
-     *		} );
+     * ```ts
+     * schema.setAttributeProperties( 'blockQuote', {
+     * 	customProperty: 'value'
+     * } );
+     * ```
      *
      * Subsequent calls with the same attribute will extend its custom properties:
      *
-     *		schema.setAttributeProperties( 'blockQuote', {
-     *			one: 1
-     *		} );
+     * ```ts
+     * schema.setAttributeProperties( 'blockQuote', {
+     * 	one: 1
+     * } );
      *
-     *		schema.setAttributeProperties( 'blockQuote', {
-     *			two: 2
-     *		} );
+     * schema.setAttributeProperties( 'blockQuote', {
+     * 	two: 2
+     * } );
      *
-     *		console.log( schema.getAttributeProperties( 'blockQuote' ) );
-     *		// Logs: { one: 1, two: 2 }
+     * console.log( schema.getAttributeProperties( 'blockQuote' ) );
+     * // Logs: { one: 1, two: 2 }
+     * ```
      *
-     * @param {String} attributeName A name of the attribute to receive the properties.
-     * @param {module:engine/model/schema~AttributeProperties} properties A dictionary of properties.
+     * @param attributeName A name of the attribute to receive the properties.
+     * @param properties A dictionary of properties.
      */
     setAttributeProperties(attributeName, properties) {
         this._attributeProperties[attributeName] = Object.assign(this.getAttributeProperties(attributeName), properties);
@@ -574,8 +567,7 @@ export default class Schema extends Observable {
     /**
      * Returns properties associated with a given model attribute. See {@link #setAttributeProperties `setAttributeProperties()`}.
      *
-     * @param {String} attributeName A name of the attribute.
-     * @returns {module:engine/model/schema~AttributeProperties}
+     * @param attributeName A name of the attribute.
      */
     getAttributeProperties(attributeName) {
         return this._attributeProperties[attributeName] || {};
@@ -584,11 +576,8 @@ export default class Schema extends Observable {
      * Returns the lowest {@link module:engine/model/schema~Schema#isLimit limit element} containing the entire
      * selection/range/position or the root otherwise.
      *
-     * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection|
-     * module:engine/model/range~Range|module:engine/model/position~Position} selectionOrRangeOrPosition
-     * The selection/range/position to check.
-     * @returns {module:engine/model/element~Element} The lowest limit element containing
-     * the entire `selectionOrRangeOrPosition`.
+     * @param selectionOrRangeOrPosition The selection/range/position to check.
+     * @returns The lowest limit element containing the entire `selectionOrRangeOrPosition`.
      */
     getLimitElement(selectionOrRangeOrPosition) {
         let element;
@@ -626,10 +615,8 @@ export default class Schema extends Observable {
      * * if the selection is collapsed, then checks if on the selection position there's a text with the
      * specified attribute allowed.
      *
-     * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
-     * Selection which will be checked.
-     * @param {String} attribute The name of the attribute to check.
-     * @returns {Boolean}
+     * @param selection Selection which will be checked.
+     * @param attribute The name of the attribute to check.
      */
     checkAttributeInSelection(selection, attribute) {
         if (selection.isCollapsed) {
@@ -659,9 +646,9 @@ export default class Schema extends Observable {
     /**
      * Transforms the given set of ranges into a set of ranges where the given attribute is allowed (and can be applied).
      *
-     * @param {Iterable.<module:engine/model/range~Range>} ranges Ranges to be validated.
-     * @param {String} attribute The name of the attribute to check.
-     * @returns {Iterable.<module:engine/model/range~Range>} Ranges in which the attribute is allowed.
+     * @param ranges Ranges to be validated.
+     * @param attribute The name of the attribute to check.
+     * @returns Ranges in which the attribute is allowed.
      */
     *getValidRanges(ranges, attribute) {
         ranges = convertToMinimalFlatRanges(ranges);
@@ -685,9 +672,9 @@ export default class Schema extends Observable {
      *
      * When valid selection range cannot be found, `null` is returned.
      *
-     * @param {module:engine/model/position~Position} position Reference position where new selection range should be looked for.
-     * @param {'both'|'forward'|'backward'} [direction='both'] Search direction.
-     * @returns {module:engine/model/range~Range|null} Nearest selection range or `null` if one cannot be found.
+     * @param position Reference position where new selection range should be looked for.
+     * @param direction Search direction.
+     * @returns Nearest selection range or `null` if one cannot be found.
      */
     getNearestSelectionRange(position, direction = 'both') {
         // Return collapsed range if provided position is valid.
@@ -729,9 +716,9 @@ export default class Schema extends Observable {
      * as long as a {@link module:engine/model/schema~Schema#isLimit limit element}, an
      * {@link module:engine/model/schema~Schema#isObject object element} or a topmost ancestor is not reached.
      *
-     * @param {module:engine/model/position~Position} position The position that the search will start from.
-     * @param {module:engine/model/node~Node|String} node The node for which an allowed parent should be found or its name.
-     * @returns {module:engine/model/element~Element|null} element Allowed parent or null if nothing was found.
+     * @param position The position that the search will start from.
+     * @param node The node for which an allowed parent should be found or its name.
+     * @returns Allowed parent or null if nothing was found.
      */
     findAllowedParent(position, node) {
         let parent = position.parent;
@@ -750,9 +737,9 @@ export default class Schema extends Observable {
     /**
      * Sets attributes allowed by the schema on a given node.
      *
-     * @param {module:engine/model/node~Node} node A node to set attributes on.
-     * @param {Object} attributes Attributes keys and values.
-     * @param {module:engine/model/writer~Writer} writer An instance of the model writer.
+     * @param node A node to set attributes on.
+     * @param attributes Attributes keys and values.
+     * @param writer An instance of the model writer.
      */
     setAllowedAttributes(node, attributes, writer) {
         const model = writer.model;
@@ -765,8 +752,7 @@ export default class Schema extends Observable {
     /**
      * Removes attributes disallowed by the schema.
      *
-     * @param {Iterable.<module:engine/model/node~Node>} nodes Nodes that will be filtered.
-     * @param {module:engine/model/writer~Writer} writer
+     * @param nodes Nodes that will be filtered.
      */
     removeDisallowedAttributes(nodes, writer) {
         for (const node of nodes) {
@@ -791,12 +777,12 @@ export default class Schema extends Observable {
     /**
      * Gets attributes of a node that have a given property.
      *
-     * @param {module:engine/model/node~Node} node Node to get attributes from.
-     * @param {String} propertyName Name of the property that attribute must have to return it.
-     * @param {Boolean|Symbol|String|Number|Object|null|undefined} propertyValue Desired value of the property that we want to check.
+     * @param node Node to get attributes from.
+     * @param propertyName Name of the property that attribute must have to return it.
+     * @param propertyValue Desired value of the property that we want to check.
      * When `undefined` attributes will be returned if they have set a given property no matter what the value is. If specified it will
      * return attributes which given property's value is equal to this parameter.
-     * @returns {Object} Object with attributes' names as key and attributes' values as value.
+     * @returns Object with attributes' names as key and attributes' values as value.
      */
     getAttributesWithProperty(node, propertyName, propertyValue) {
         const attributes = {};
@@ -813,22 +799,13 @@ export default class Schema extends Observable {
     }
     /**
      * Creates an instance of the schema context.
-     *
-     * @param {module:engine/model/schema~SchemaContextDefinition} context
-     * @returns {module:engine/model/schema~SchemaContext}
      */
     createContext(context) {
         return new SchemaContext(context);
     }
-    /**
-     * @private
-     */
     _clearCache() {
         this._compiledDefinitions = null;
     }
-    /**
-     * @private
-     */
     _compile() {
         const compiledDefinitions = {};
         const sourceRules = this._sourceDefinitions;
@@ -856,12 +833,6 @@ export default class Schema extends Observable {
         }
         this._compiledDefinitions = compiledDefinitions;
     }
-    /**
-     * @private
-     * @param {module:engine/model/schema~SchemaCompiledItemDefinition} def
-     * @param {module:engine/model/schema~SchemaContext} context
-     * @param {Number} contextItemIndex
-     */
     _checkContextMatch(def, context, contextItemIndex = context.length - 1) {
         const contextItem = context.getItem(contextItemIndex);
         if (def.allowIn.includes(contextItem.name)) {
@@ -883,10 +854,9 @@ export default class Schema extends Observable {
      *
      * This is a helper function for {@link ~Schema#getValidRanges}.
      *
-     * @private
-     * @param {module:engine/model/range~Range} range The range to process.
-     * @param {String} attribute The name of the attribute to check.
-     * @returns {Iterable.<module:engine/model/range~Range>} Ranges in which the attribute is allowed.
+     * @param range The range to process.
+     * @param attribute The name of the attribute to check.
+     * @returns Ranges in which the attribute is allowed.
      */
     *_getValidRangesForRange(range, attribute) {
         let start = range.start;
@@ -913,13 +883,15 @@ export default class Schema extends Observable {
  *
  * Considering such position:
  *
- *		<$root>
- *			<blockQuote>
- *				<paragraph>
- *					^
- *				</paragraph>
- *			</blockQuote>
- *		</$root>
+ * ```xml
+ * <$root>
+ * 	<blockQuote>
+ * 		<paragraph>
+ * 			^
+ * 		</paragraph>
+ * 	</blockQuote>
+ * </$root>
+ * ```
  *
  * The context of this position is its {@link module:engine/model/position~Position#getAncestors lists of ancestors}:
  *
@@ -935,8 +907,6 @@ export default class Schema extends Observable {
 export class SchemaContext {
     /**
      * Creates an instance of the context.
-     *
-     * @param {module:engine/model/schema~SchemaContextDefinition} context
      */
     constructor(context) {
         if (context instanceof SchemaContext) {
@@ -958,16 +928,12 @@ export class SchemaContext {
     }
     /**
      * The number of items.
-     *
-     * @type {Number}
      */
     get length() {
         return this._items.length;
     }
     /**
      * The last item (the lowest node).
-     *
-     * @type {module:engine/model/schema~SchemaContextItem}
      */
     get last() {
         return this._items[this._items.length - 1];
@@ -976,8 +942,6 @@ export class SchemaContext {
      * Iterable interface.
      *
      * Iterates over all context items.
-     *
-     * @returns {Iterable.<module:engine/model/schema~SchemaContextItem>}
      */
     [Symbol.iterator]() {
         return this._items[Symbol.iterator]();
@@ -987,25 +951,26 @@ export class SchemaContext {
      *
      * Item can be added as:
      *
-     * 		const context = new SchemaContext( [ '$root' ] );
+     * ```ts
+     * const context = new SchemaContext( [ '$root' ] );
      *
-     * 		// An element.
-     * 		const fooElement = writer.createElement( 'fooElement' );
-     * 		const newContext = context.push( fooElement ); // [ '$root', 'fooElement' ]
+     * // An element.
+     * const fooElement = writer.createElement( 'fooElement' );
+     * const newContext = context.push( fooElement ); // [ '$root', 'fooElement' ]
      *
-     * 		// A text node.
-     * 		const text = writer.createText( 'foobar' );
-     * 		const newContext = context.push( text ); // [ '$root', '$text' ]
+     * // A text node.
+     * const text = writer.createText( 'foobar' );
+     * const newContext = context.push( text ); // [ '$root', '$text' ]
      *
-     * 		// A string (element name).
-     * 		const newContext = context.push( 'barElement' ); // [ '$root', 'barElement' ]
+     * // A string (element name).
+     * const newContext = context.push( 'barElement' ); // [ '$root', 'barElement' ]
+     * ```
      *
      * **Note** {@link module:engine/model/node~Node} that is already in the model tree will be added as the only item
      * (without ancestors).
      *
-     * @param {String|module:engine/model/node~Node} item An item that will be added
-     * to the current context.
-     * @returns {module:engine/model/schema~SchemaContext} A new schema context instance with an additional item.
+     * @param item An item that will be added to the current context.
+     * @returns A new schema context instance with an additional item.
      */
     push(item) {
         const ctx = new SchemaContext([item]);
@@ -1014,16 +979,12 @@ export class SchemaContext {
     }
     /**
      * Gets an item on the given index.
-     *
-     * @returns {module:engine/model/schema~SchemaContextItem}
      */
     getItem(index) {
         return this._items[index];
     }
     /**
      * Returns the names of items.
-     *
-     * @returns {Iterable.<String>}
      */
     *getNames() {
         yield* this._items.map(item => item.name);
@@ -1031,15 +992,14 @@ export class SchemaContext {
     /**
      * Checks whether the context ends with the given nodes.
      *
-     *		const ctx = new SchemaContext( [ rootElement, paragraphElement, textNode ] );
-     *
-     *		ctx.endsWith( '$text' ); // -> true
-     *		ctx.endsWith( 'paragraph $text' ); // -> true
-     *		ctx.endsWith( '$root' ); // -> false
-     *		ctx.endsWith( 'paragraph' ); // -> false
+     * ```ts
+     * const ctx = new SchemaContext( [ rootElement, paragraphElement, textNode ] );
      *
-     * @param {String} query
-     * @returns {Boolean}
+     * ctx.endsWith( '$text' ); // -> true
+     * ctx.endsWith( 'paragraph $text' ); // -> true
+     * ctx.endsWith( '$root' ); // -> false
+     * ctx.endsWith( 'paragraph' ); // -> false
+     * ```
      */
     endsWith(query) {
         return Array.from(this.getNames()).join(' ').endsWith(query);
@@ -1047,15 +1007,14 @@ export class SchemaContext {
     /**
      * Checks whether the context starts with the given nodes.
      *
-     *		const ctx = new SchemaContext( [ rootElement, paragraphElement, textNode ] );
-     *
-     *		ctx.endsWith( '$root' ); // -> true
-     *		ctx.endsWith( '$root paragraph' ); // -> true
-     *		ctx.endsWith( '$text' ); // -> false
-     *		ctx.endsWith( 'paragraph' ); // -> false
+     * ```ts
+     * const ctx = new SchemaContext( [ rootElement, paragraphElement, textNode ] );
      *
-     * @param {String} query
-     * @returns {Boolean}
+     * ctx.endsWith( '$root' ); // -> true
+     * ctx.endsWith( '$root paragraph' ); // -> true
+     * ctx.endsWith( '$text' ); // -> false
+     * ctx.endsWith( 'paragraph' ); // -> false
+     * ```
      */
     startsWith(query) {
         return Array.from(this.getNames()).join(' ').startsWith(query);
@@ -1222,13 +1181,15 @@ function mapContextItem(ctxItem) {
         };
     }
 }
-// Generator function returning values from provided walkers, switching between them at each iteration. If only one walker
-// is provided it will return data only from that walker.
-//
-// @param {module:engine/module/treewalker~TreeWalker} [backward] Walker iterating in backward direction.
-// @param {module:engine/module/treewalker~TreeWalker} [forward] Walker iterating in forward direction.
-// @returns {Iterable.<Object>} Object returned at each iteration contains `value` and `walker` (informing which walker returned
-// given value) fields.
+/**
+ * Generator function returning values from provided walkers, switching between them at each iteration. If only one walker
+ * is provided it will return data only from that walker.
+ *
+ * @param backward Walker iterating in backward direction.
+ * @param forward Walker iterating in forward direction.
+ * @returns Object returned at each iteration contains `value` and `walker` (informing which walker returned
+ * given value) fields.
+ */
 function* combineWalkers(backward, forward) {
     let done = false;
     while (!done) {
@@ -1255,11 +1216,13 @@ function* combineWalkers(backward, forward) {
         }
     }
 }
-// Takes an array of non-intersecting ranges. For each of them gets minimal flat ranges covering that range and returns
-// all those minimal flat ranges.
-//
-// @param {Array.<module:engine/model/range~Range>} ranges Ranges to process.
-// @returns {Iterable.<module:engine/model/range~Range>} Minimal flat ranges of given `ranges`.
+/**
+ * Takes an array of non-intersecting ranges. For each of them gets minimal flat ranges covering that range and returns
+ * all those minimal flat ranges.
+ *
+ * @param ranges Ranges to process.
+ * @returns Minimal flat ranges of given `ranges`.
+ */
 function* convertToMinimalFlatRanges(ranges) {
     for (const range of ranges) {
         yield* range.getMinimalFlatRanges();