Explorar o código

Merge branch 'stable'

Piotrek Koszuliński %!s(int64=7) %!d(string=hai) anos
pai
achega
d49e28b896

+ 102 - 102
packages/ckeditor5-engine/src/conversion/conversion.js

@@ -22,10 +22,10 @@ import {
 } from './upcast-converters';
 
 /**
- * An utility class that helps adding converters to upcast and downcast dispatchers.
+ * A utility class that helps add converters to upcast and downcast dispatchers.
  *
- * We recommend reading first the {@glink framework/guides/architecture/editing-engine} guide to understand the
- * core concepts of the conversion mechanisms.
+ * We recommend reading the {@glink framework/guides/architecture/editing-engine Editing engine architecture} guide first to
+ * understand the core concepts of the conversion mechanisms.
  *
  * The instance of the conversion manager is available in the
  * {@link module:core/editor/editor~Editor#conversion `editor.conversion`} property
@@ -36,7 +36,7 @@ import {
  * * `dataDowncast`
  * * `upcast`
  *
- * To add a converter to a specific group use the {@link module:engine/conversion/conversion~Conversion#for `for()`}
+ * To add a converter to a specific group, use the {@link module:engine/conversion/conversion~Conversion#for `for()`}
  * method:
  *
  *		// Add a converter to editing downcast and data downcast.
@@ -48,23 +48,23 @@ import {
  *		editor.conversion.for( 'editingDowncast' ).add( downcastElementToWidget( config ) );
  *
  * The functions used in `add()` calls are one-way converters (i.e. you need to remember yourself to add
- * a converter in the other direction, if you feature requires that). They are also called "conversion helpers".
+ * a converter in the other direction, if your feature requires that). They are also called "conversion helpers".
  * You can find a set of them in the {@link module:engine/conversion/downcast-converters} and
- * {@link module:engine/conversion/upcast-converters} modules
+ * {@link module:engine/conversion/upcast-converters} modules.
  *
  * Besides allowing to register converters to specific dispatchers, you can also use methods available in this
  * class to add two-way converters (upcast and downcast):
  *
- * * {@link module:engine/conversion/conversion~Conversion#elementToElement `elementToElement()`} 
- * model element to view element and vice versa
- * * {@link module:engine/conversion/conversion~Conversion#attributeToElement `attributeToElement()`} 
- * model attribute to view element and vice versa
- * * {@link module:engine/conversion/conversion~Conversion#attributeToElement `attributeToElement()`} 
- * model attribute to view element and vice versa
+ * * {@link module:engine/conversion/conversion~Conversion#elementToElement `elementToElement()`} –
+ * Model element to view element and vice versa.
+ * * {@link module:engine/conversion/conversion~Conversion#attributeToElement `attributeToElement()`} –
+ * Model attribute to view element and vice versa.
+ * * {@link module:engine/conversion/conversion~Conversion#attributeToElement `attributeToElement()`} –
+ * Model attribute to view element and vice versa.
  */
 export default class Conversion {
 	/**
-	 * Creates new Conversion instance.
+	 * Creates a new conversion instance.
 	 */
 	constructor() {
 		/**
@@ -75,16 +75,16 @@ export default class Conversion {
 	}
 
 	/**
-	 * Registers one or more converters under given group name. Then, group name can be used to assign a converter
+	 * Registers one or more converters under a given group name. The group name can then be used to assign a converter
 	 * to multiple dispatchers at once.
 	 *
-	 * If given group name is used for a second time,
-	 * {@link module:utils/ckeditorerror~CKEditorError conversion-register-group-exists} error is thrown.
+	 * If a given group name is used for the second time, the
+	 * {@link module:utils/ckeditorerror~CKEditorError `conversion-register-group-exists` error} is thrown.
 	 *
-	 * @param {String} groupName A name for dispatchers group.
+	 * @param {String} groupName The name for dispatchers group.
 	 * @param {Array.<module:engine/conversion/downcastdispatcher~DowncastDispatcher|
 	 * module:engine/conversion/upcastdispatcher~UpcastDispatcher>} dispatchers Dispatchers to register
-	 * under given name.
+	 * under the given name.
 	 */
 	register( groupName, dispatchers ) {
 		if ( this._dispatchersGroups.has( groupName ) ) {
@@ -100,34 +100,34 @@ export default class Conversion {
 	}
 
 	/**
-	 * Provides chainable API to assign converters to dispatchers registered under given group name. Converters are added
-	 * by calling `.add()` method of an object returned by this function.
+	 * Provides chainable API to assign converters to dispatchers registered under a given group name. Converters are added
+	 * by calling the `.add()` method of an object returned by this function.
 	 *
 	 *		conversion.for( 'downcast' )
 	 *			.add( conversionHelperA )
 	 *			.add( conversionHelperB );
 	 *
-	 * In above example, `conversionHelperA` and `conversionHelperB` will be called for all dispatchers from `'model'` group.
+	 * In this example `conversionHelperA` and `conversionHelperB` will be called for all dispatchers from the `'model'` group.
 	 *
-	 * `.add()` takes exactly one parameter, which is a function. That function should accept one parameter, which
-	 * is a dispatcher instance. The function should add an actual converter to passed dispatcher instance.
+	 * The `.add()` method takes exactly one parameter, which is a function. This function should accept one parameter that
+	 * is a dispatcher instance. The function should add an actual converter to the passed dispatcher instance.
 	 *
 	 * Conversion helpers for most common cases are already provided. They are flexible enough to cover most use cases.
-	 * See documentation to learn how they can be configured.
+	 * See the documentation to learn how they can be configured.
 	 *
-	 * For downcast (model to view conversion), these are:
+	 * For downcast (model-to-view conversion), these are:
 	 *
-	 * * {@link module:engine/conversion/downcast-converters~downcastElementToElement downcast element to element converter},
-	 * * {@link module:engine/conversion/downcast-converters~downcastAttributeToElement downcast attribute to element converter},
-	 * * {@link module:engine/conversion/downcast-converters~downcastAttributeToAttribute downcast attribute to attribute converter}.
+	 * * {@link module:engine/conversion/downcast-converters~downcastElementToElement Downcast element-to-element converter},
+	 * * {@link module:engine/conversion/downcast-converters~downcastAttributeToElement Downcast attribute-to-element converter},
+	 * * {@link module:engine/conversion/downcast-converters~downcastAttributeToAttribute Downcast attribute-to-attribute converter}.
 	 *
-	 * For upcast (view to model conversion), these are:
+	 * For upcast (view-to-model conversion), these are:
 	 *
-	 * * {@link module:engine/conversion/upcast-converters~upcastElementToElement upcast element to element converter},
-	 * * {@link module:engine/conversion/upcast-converters~upcastElementToAttribute upcast attribute to element converter},
-	 * * {@link module:engine/conversion/upcast-converters~upcastAttributeToAttribute upcast attribute to attribute converter}.
+	 * * {@link module:engine/conversion/upcast-converters~upcastElementToElement Upcast element-to-element converter},
+	 * * {@link module:engine/conversion/upcast-converters~upcastElementToAttribute Upcast attribute-to-element converter},
+	 * * {@link module:engine/conversion/upcast-converters~upcastAttributeToAttribute Upcast attribute-to-attribute converter}.
 	 *
-	 * An example of using conversion helpers to convert `paragraph` model element to `p` view element (and back):
+	 * An example of using conversion helpers to convert the `paragraph` model element to the `p` view element (and back):
 	 *
 	 *		// Define conversion configuration - model element 'paragraph' should be converted to view element 'p'.
 	 *		const config = { model: 'paragraph', view: 'p' };
@@ -136,13 +136,13 @@ export default class Conversion {
 	 *		conversion.for( 'downcast' ).add( downcastElementToElement( config ) );
 	 *		conversion.for( 'upcast' ).add( upcastElementToElement( config ) );
 	 *
-	 * An example of providing custom conversion helper that uses custom converter function:
+	 * An example of providing a custom conversion helper that uses a custom converter function:
 	 *
-	 *		// Adding custom `myConverter` converter for 'paragraph' element insertion, with default priority ('normal').
+	 *		// Adding a custom `myConverter` converter for 'paragraph' element insertion, with the default priority ('normal').
 	 *		conversion.for( 'downcast' ).add( conversion.customConverter( 'insert:paragraph', myConverter ) );
 	 *
-	 * @param {String} groupName Name of dispatchers group to add converters to.
-	 * @returns {Object} Object with `.add()` method, providing a way to add converters.
+	 * @param {String} groupName The name of dispatchers group to add the converters to.
+	 * @returns {Object} An object with the `.add()` method, providing a way to add converters.
 	 */
 	for( groupName ) {
 		const dispatchers = this._getDispatchers( groupName );
@@ -157,13 +157,13 @@ export default class Conversion {
 	}
 
 	/**
-	 * Sets up converters between the model and the view which convert a model element to a view element (and vice versa).
-	 * For example, model `<paragraph>Foo</paragraph>` is `<p>Foo</p>` in the view.
+	 * Sets up converters between the model and the view that convert a model element to a view element (and vice versa).
+	 * For example, the model `<paragraph>Foo</paragraph>` is `<p>Foo</p>` in the view.
 	 *
-	 *		// Simple conversion from `paragraph` model element to `<p>` view element (and vice versa).
+	 *		// A simple conversion from the `paragraph` model element to the `<p>` view element (and vice versa).
 	 *		conversion.elementToElement( { model: 'paragraph', view: 'p' } );
 	 *
-	 *		// Override other converters by specifying converter definition with higher priority.
+	 *		// Override other converters by specifying a converter definition with a higher priority.
 	 *		conversion.elementToElement( { model: 'paragraph', view: 'div', converterPriority: 'high' } );
 	 *
 	 *		// View specified as an object instead of a string.
@@ -175,14 +175,14 @@ export default class Conversion {
 	 *			}
 	 *		} );
 	 *
-	 *		// Use `upcastAlso` to define other view elements that should be also converted to `paragraph` element.
+	 *		// Use `upcastAlso` to define other view elements that should also be converted to a `paragraph` element.
 	 *		conversion.elementToElement( {
 	 *			model: 'paragraph',
 	 *			view: 'p',
 	 *			upcastAlso: [
 	 *				'div',
 	 *				{
-	 *					// Any element with `display: block` style.
+	 *					// Any element with the `display: block` style.
 	 *					styles: {
 	 *						display: 'block'
 	 *					}
@@ -211,9 +211,9 @@ export default class Conversion {
 	 *				const size = Number( match[ 1 ] );
 	 *
 	 *				if ( size > 26 ) {
-	 *					// Returned value be an object with the matched properties.
-	 *					// Those properties will be "consumed" during conversion.
-	 *					// See `engine.view.Matcher~MatcherPattern` and `engine.view.Matcher#match` for more.
+	 *					// Returned value can be an object with the matched properties.
+	 *					// These properties will be "consumed" during the conversion.
+	 *					// See `engine.view.Matcher~MatcherPattern` and `engine.view.Matcher#match` for more details.
 	 *
 	 *					return { name: true, styles: [ 'font-size' ] };
 	 *				}
@@ -222,10 +222,10 @@ export default class Conversion {
 	 *			}
 	 *		} );
 	 *
-	 * `definition.model` is a `String` with a model element name to converter from/to.
+	 * `definition.model` is a `String` with a model element name to convert from or to.
 	 * See {@link module:engine/conversion/conversion~ConverterDefinition} to learn about other parameters.
 	 *
-	 * @param {module:engine/conversion/conversion~ConverterDefinition} definition Converter definition.
+	 * @param {module:engine/conversion/conversion~ConverterDefinition} definition The converter definition.
 	 */
 	elementToElement( definition ) {
 		// Set up downcast converter.
@@ -244,13 +244,13 @@ export default class Conversion {
 	}
 
 	/**
-	 * Sets up converters between the model and the view which convert a model attribute to a view element (and vice versa).
-	 * For example, model text node with data `"Foo"` and `bold` attribute is `<strong>Foo</strong>` in the view.
+	 * Sets up converters between the model and the view that convert a model attribute to a view element (and vice versa).
+	 * For example, a model text node with `"Foo"` as data and the `bold` attribute is `<strong>Foo</strong>` in the view.
 	 *
-	 *		// Simple conversion from `bold=true` attribute to `<strong>` view element (and vice versa).
+	 *		// A simple conversion from the `bold=true` attribute to the `<strong>` view element (and vice versa).
 	 *		conversion.attributeToElement( { model: 'bold', view: 'strong' } );
 	 *
-	 *		// Override other converters by specifying converter definition with higher priority.
+	 *		// Override other converters by specifying a converter definition with a higher priority.
 	 *		conversion.attributeToElement( { model: 'bold', view: 'b', converterPriority: 'high' } );
 	 *
 	 *		// View specified as an object instead of a string.
@@ -262,8 +262,8 @@ export default class Conversion {
 	 *			}
 	 *		} );
 	 *
-	 *		// Use `config.model.name` to define conversion only from given node type, `$text` in this case.
-	 *		// The same attribute on different elements may be then handled by a different converter.
+	 *		// Use `config.model.name` to define the conversion only from a given node type, `$text` in this case.
+	 *		// The same attribute on different elements may then be handled by a different converter.
 	 *		conversion.attributeToElement( {
 	 *			model: {
 	 *				key: 'textDecoration',
@@ -286,7 +286,7 @@ export default class Conversion {
 	 *			}
 	 *		} );
 	 *
-	 *		// Use `upcastAlso` to define other view elements that should be also converted to `bold` attribute.
+	 *		// Use `upcastAlso` to define other view elements that should also be converted to the `bold` attribute.
 	 *		conversion.attributeToElement( {
 	 *			model: 'bold',
 	 *			view: 'strong',
@@ -306,9 +306,9 @@ export default class Conversion {
 	 *					const fontWeight = viewElement.getStyle( 'font-weight' );
 	 *
 	 *					if ( viewElement.is( 'span' ) && fontWeight && /\d+/.test() && Number( fontWeight ) > 500 ) {
-	 *						// Returned value be an object with the matched properties.
-	 *						// Those properties will be "consumed" during conversion.
-	 *						// See `engine.view.Matcher~MatcherPattern` and `engine.view.Matcher#match` for more.
+	 *						// Returned value can be an object with the matched properties.
+	 *						// These properties will be "consumed" during the conversion.
+	 *						// See `engine.view.Matcher~MatcherPattern` and `engine.view.Matcher#match` for more details.
 	 *
 	 *						return {
 	 *							name: true,
@@ -319,7 +319,7 @@ export default class Conversion {
 	 *			]
 	 *		} );
 	 *
-	 *		// Conversion from/to a model attribute key which value is an enum (`fontSize=big|small`).
+	 *		// Conversion from and to a model attribute key whose value is an enum (`fontSize=big|small`).
 	 *		// `upcastAlso` set as callback enables a conversion of a wide range of different view elements.
 	 *		conversion.attributeToElement( {
 	 *			model: {
@@ -357,9 +357,9 @@ export default class Conversion {
 	 *					const size = Number( match[ 1 ] );
 	 *
 	 *					if ( viewElement.is( 'span' ) && size > 10 ) {
-	 *						// Returned value be an object with the matched properties.
-	 *						// Those properties will be "consumed" during conversion.
-	 *						// See `engine.view.Matcher~MatcherPattern` and `engine.view.Matcher#match` for more.
+	 *						// Returned value can be an object with the matched properties.
+	 *						// These properties will be "consumed" during the conversion.
+	 *						// See `engine.view.Matcher~MatcherPattern` and `engine.view.Matcher#match` for more details.
 	 *
 	 *						return { name: true, styles: [ 'font-size' ] };
 	 *					}
@@ -382,9 +382,9 @@ export default class Conversion {
 	 *					const size = Number( match[ 1 ] );
 	 *
 	 *					if ( viewElement.is( 'span' ) && size < 10 ) {
-	 *						// Returned value be an object with the matched properties.
-	 *						// Those properties will be "consumed" during conversion.
-	 *						// See `engine.view.Matcher~MatcherPattern` and `engine.view.Matcher#match` for more.
+	 *						// Returned value can be an object with the matched properties.
+	 *						// These properties will be "consumed" during the conversion.
+	 *						// See `engine.view.Matcher~MatcherPattern` and `engine.view.Matcher#match` for more details.
 	 *
 	 *						return { name: true, styles: [ 'font-size' ] };
 	 *					}
@@ -394,11 +394,11 @@ export default class Conversion {
 	 *			}
 	 *		} );
 	 *
-	 * `definition.model` parameter specifies what model attribute should be converted from/to. It can be a `{ key, value }` object
-	 * describing attribute key and value to convert or a `String` specifying just attribute key (then `value` is set to `true`).
+	 * The `definition.model` parameter specifies which model attribute should be converted from or to. It can be a `{ key, value }` object
+	 * describing the attribute key and value to convert or a `String` specifying just the attribute key (then `value` is set to `true`).
 	 * See {@link module:engine/conversion/conversion~ConverterDefinition} to learn about other parameters.
 	 *
-	 * @param {module:engine/conversion/conversion~ConverterDefinition} definition Converter definition.
+	 * @param {module:engine/conversion/conversion~ConverterDefinition} definition The converter definition.
 	 */
 	attributeToElement( definition ) {
 		// Set up downcast converter.
@@ -417,13 +417,13 @@ export default class Conversion {
 	}
 
 	/**
-	 * Sets up converters between the model and the view which convert a model attribute to a view attribute (and vice versa).
-	 * For example, `<image src='foo.jpg'></image>` is converted to `<img src='foo.jpg'></img>` (same attribute key and value).
+	 * Sets up converters between the model and the view that convert a model attribute to a view attribute (and vice versa).
+	 * For example, `<image src='foo.jpg'></image>` is converted to `<img src='foo.jpg'></img>` (the same attribute key and value).
 	 *
-	 *		// Simple conversion from `source` model attribute to `src` view attribute (and vice versa).
+	 *		// A simple conversion from the `source` model attribute to the `src` view attribute (and vice versa).
 	 *		conversion.attributeToAttribute( { model: 'source', view: 'src' } );
 	 *
-	 *		// Attributes values are strictly specified.
+	 *		// Attribute values are strictly specified.
 	 *		conversion.attributeToAttribute( {
 	 *			model: {
 	 *				name: 'image',
@@ -439,7 +439,7 @@ export default class Conversion {
 	 *			}
 	 *		} );
 	 *
-	 *		// Set style attribute.
+	 *		// Set the style attribute.
 	 *		conversion.attributeToAttribute( {
 	 *			model: {
 	 *				name: 'image',
@@ -459,8 +459,8 @@ export default class Conversion {
 	 *			}
 	 *		} );
 	 *
-	 *		// Conversion from/to a model attribute key which value is an enum (`align=right|center`).
-	 *		// Use `upcastAlso` to define other view elements that should be also converted to `align=right` attribute.
+	 *		// Conversion from and to a model attribute key whose value is an enum (`align=right|center`).
+	 *		// Use `upcastAlso` to define other view elements that should also be converted to the `align=right` attribute.
 	 *		conversion.attributeToAttribute( {
 	 *			model: {
 	 *				key: 'align',
@@ -490,35 +490,35 @@ export default class Conversion {
 	 *			}
 	 *		} );
 	 *
-	 * `definition.model` parameter specifies what model attribute should be converted from/to.
+	 * The `definition.model` parameter specifies which model attribute should be converted from and to.
 	 * It can be a `{ key, [ values ], [ name ] }` object or a `String`, which will be treated like `{ key: definition.model }`.
-	 * `key` property is the model attribute key to convert from/to.
-	 * `values` are the possible model attribute values. If `values` is not set, model attribute value will be the same as the
+	 * The `key` property is the model attribute key to convert from and to.
+	 * The `values` are the possible model attribute values. If `values` is not set, the model attribute value will be the same as the
 	 * view attribute value.
-	 * If `name` is set, conversion will be set up only for model elements with the given name.
+	 * If `name` is set, the conversion will be set up only for model elements with the given name.
 	 *
-	 * `definition.view` parameter specifies what view attribute should be converted from/to.
+	 * The `definition.view` parameter specifies which view attribute should be converted from and to.
 	 * It can be a `{ key, value, [ name ] }` object or a `String`, which will be treated like `{ key: definition.view }`.
-	 * `key` property is the view attribute key to convert from/to.
-	 * `value` is the view attribute value to convert from/to. If `definition.value` is not set, view attribute value will be
+	 * The `key` property is the view attribute key to convert from and to.
+	 * The `value` is the view attribute value to convert from and to. If `definition.value` is not set, the view attribute value will be
 	 * the same as the model attribute value.
 	 * If `key` is `'class'`, `value` can be a `String` or an array of `String`s.
 	 * If `key` is `'style'`, `value` is an object with key-value pairs.
 	 * In other cases, `value` is a `String`.
-	 * If `name` is set, conversion will be set up only for model elements with the given name.
-	 * If `definition.model.values` is set, `definition.view` is an object which assigns values from `definition.model.values`
+	 * If `name` is set, the conversion will be set up only for model elements with the given name.
+	 * If `definition.model.values` is set, `definition.view` is an object that assigns values from `definition.model.values`
 	 * to `{ key, value, [ name ] }` objects.
 	 *
-	 * `definition.upcastAlso` specifies which other matching view elements should be also upcast to given model configuration.
+	 * `definition.upcastAlso` specifies which other matching view elements should also be upcast to the given model configuration.
 	 * If `definition.model.values` is set, `definition.upcastAlso` should be an object assigning values from `definition.model.values`
 	 * to {@link module:engine/view/matcher~MatcherPattern}s or arrays of {@link module:engine/view/matcher~MatcherPattern}s.
 	 *
-	 * **Note:** `definition.model` and `definition.view` form should be mirrored, that is the same type of parameters should
+	 * **Note:** `definition.model` and `definition.view` form should be mirrored, so the same types of parameters should
 	 * be given in both parameters.
 	 *
-	 * @param {Object} definition Converter definition.
-	 * @param {String|Object} definition.model Model attribute to convert from/to.
-	 * @param {String|Object} definition.view View attribute to convert from/to.
+	 * @param {Object} definition The converter definition.
+	 * @param {String|Object} definition.model The model attribute to convert from and to.
+	 * @param {String|Object} definition.view The view attribute to convert from and to.
 	 * @param {module:engine/view/matcher~MatcherPattern|Array.<module:engine/view/matcher~MatcherPattern>} [definition.upcastAlso]
 	 * Any view element matching `definition.upcastAlso` will also be converted to the given model attribute. `definition.upcastAlso`
 	 * is used only if `config.model.values` is specified.
@@ -539,10 +539,10 @@ export default class Conversion {
 	}
 
 	/**
-	 * Returns dispatchers registered under given group name.
+	 * Returns dispatchers registered under a given group name.
 	 *
-	 * If given group name has not been registered,
-	 * {@link module:utils/ckeditorerror~CKEditorError conversion-for-unknown-group} error is thrown.
+	 * If the given group name has not been registered, the
+	 * {@link module:utils/ckeditorerror~CKEditorError `conversion-for-unknown-group` error} is thrown.
 	 *
 	 * @private
 	 * @param {String} groupName
@@ -566,25 +566,25 @@ export default class Conversion {
 }
 
 /**
- * Defines how the model should be converted from/to the view.
+ * Defines how the model should be converted from and to the view.
  *
  * @typedef {Object} module:engine/conversion/conversion~ConverterDefinition
  *
- * @property {*} [model] Model conversion definition. Describes model element or model attribute to convert. This parameter differs
- * for different functions that accepts `ConverterDefinition`. See the description of a function to learn how to set it.
- * @property {module:engine/view/elementdefinition~ElementDefinition|Object} view Definition of a view element to convert from/to.
- * If `model` describes multiple values, `view` is an object that assigns those values (`view` object keys) to view element definitions
+ * @property {*} [model] The model conversion definition. Describes the model element or model attribute to convert. This parameter differs
+ * for different functions that accept `ConverterDefinition`. See the description of the function to learn how to set it.
+ * @property {module:engine/view/elementdefinition~ElementDefinition|Object} view The definition of the view element to convert from and
+ * to. If `model` describes multiple values, `view` is an object that assigns these values (`view` object keys) to view element definitions
  * (`view` object values).
  * @property {module:engine/view/matcher~MatcherPattern|Array.<module:engine/view/matcher~MatcherPattern>} [upcastAlso]
- * Any view element matching `upcastAlso` will also be converted to model. If `model` describes multiple values, `upcastAlso`
- * is an object that assigns those values (`upcastAlso` object keys) to {@link module:engine/view/matcher~MatcherPattern}s
+ * Any view element matching `upcastAlso` will also be converted to the model. If `model` describes multiple values, `upcastAlso`
+ * is an object that assigns these values (`upcastAlso` object keys) to {@link module:engine/view/matcher~MatcherPattern}s
  * (`upcastAlso` object values).
- * @property {module:utils/priorities~PriorityString} [converterPriority] Converter priority.
+ * @property {module:utils/priorities~PriorityString} [converterPriority] The converter priority.
  */
 
-// Helper function for `Conversion` `.add()` method.
+// Helper function for the `Conversion` `.add()` method.
 //
-// Calls `conversionHelper` on each dispatcher from the group specified earlier in `.for()` call, effectively
+// Calls `conversionHelper` on each dispatcher from the group specified earlier in the `.for()` call, effectively
 // adding converters to all specified dispatchers.
 //
 // @private

+ 145 - 140
packages/ckeditor5-engine/src/conversion/downcast-converters.js

@@ -14,7 +14,7 @@ import DocumentSelection from '../model/documentselection';
 import cloneDeep from '@ckeditor/ckeditor5-utils/src/lib/lodash/cloneDeep';
 
 /**
- * Contains downcast (model to view) converters for {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher}.
+ * Contains downcast (model-to-view) converters for {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher}.
  *
  * @module engine/conversion/downcast-converters
  */
@@ -41,12 +41,13 @@ import cloneDeep from '@ckeditor/ckeditor5-utils/src/lib/lodash/cloneDeep';
  * 			view: ( modelElement, viewWriter ) => viewWriter.createContainerElement( 'h' + modelElement.getAttribute( 'level' ) )
  * 		} );
  *
- * See {@link module:engine/conversion/conversion~Conversion#for} to learn how to add converter to conversion process.
+ * See {@link module:engine/conversion/conversion~Conversion#for `conversion.for()`} to learn how to add a converter
+ * to the conversion process.
  *
  * @param {Object} config Conversion configuration.
- * @param {String} config.model Name of the model element to convert.
- * @param {module:engine/view/elementdefinition~ElementDefinition|Function} config.view View element definition or a function
- * that takes model element and view writer as a parameters and returns a view container element.
+ * @param {String} config.model The name of the model element to convert.
+ * @param {module:engine/view/elementdefinition~ElementDefinition|Function} config.view A view element definition or a function
+ * that takes the model element and view writer as parameters and returns a view container element.
  * @returns {Function} Conversion helper.
  */
 export function downcastElementToElement( config ) {
@@ -62,8 +63,8 @@ export function downcastElementToElement( config ) {
 /**
  * Model attribute to view element conversion helper.
  *
- * This conversion results in wrapping view nodes in a view attribute element. For example, model text node with data
- * `"Foo"` and `bold` attribute becomes `<strong>Foo</strong>` in the view.
+ * This conversion results in wrapping view nodes with a view attribute element. For example, a model text node with
+ * `"Foo"` as data and the `bold` attribute becomes `<strong>Foo</strong>` in the view.
  *
  *		downcastAttributeToElement( { model: 'bold', view: 'strong' } );
  *
@@ -115,13 +116,14 @@ export function downcastElementToElement( config ) {
  *			}
  *		} );
  *
- * See {@link module:engine/conversion/conversion~Conversion#for} to learn how to add converter to conversion process.
+ * See {@link module:engine/conversion/conversion~Conversion#for `conversion.for()`} to learn how to add a converter
+ * to the conversion process.
  *
  * @param {Object} config Conversion configuration.
- * @param {String|Object} config.model Key of the attribute to convert from or a `{ key, values }` object. `values` is an array
- * of `String`s with possible values if the model attribute is enumerable.
- * @param {module:engine/view/elementdefinition~ElementDefinition|Function|Object} config.view View element definition or a function
- * that takes model attribute value and view writer as parameters and returns a view attribute element. If `config.model.values` is
+ * @param {String|Object} config.model The key of the attribute to convert from or a `{ key, values }` object. `values` is an array
+ * of `String`s with possible values if the model attribute is an enumerable.
+ * @param {module:engine/view/elementdefinition~ElementDefinition|Function|Object} config.view A view element definition or a function
+ * that takes the model attribute value and view writer as parameters and returns a view attribute element. If `config.model.values` is
  * given, `config.view` should be an object assigning values from `config.model.values` to view element definitions or functions.
  * @param {module:utils/priorities~PriorityString} [config.converterPriority='normal'] Converter priority.
  * @returns {Function} Conversion helper.
@@ -154,7 +156,7 @@ export function downcastAttributeToElement( config ) {
 /**
  * Model attribute to view attribute conversion helper.
  *
- * This conversion results in adding an attribute on a view node, basing on an attribute from a model node. For example,
+ * This conversion results in adding an attribute to a view node, basing on an attribute from a model node. For example,
  * `<image src='foo.jpg'></image>` is converted to `<img src='foo.jpg'></img>`.
  *
  *		downcastAttributeToAttribute( { model: 'source', view: 'src' } );
@@ -191,13 +193,14 @@ export function downcastAttributeToElement( config ) {
  *			view: modelAttributeValue => ( { key: 'class', value: 'styled-' + modelAttributeValue } )
  *		} );
  *
- * See {@link module:engine/conversion/conversion~Conversion#for} to learn how to add converter to conversion process.
+ * See {@link module:engine/conversion/conversion~Conversion#for `conversion.for()`} to learn how to add a converter
+ * to the conversion process.
  *
  * @param {Object} config Conversion configuration.
- * @param {String|Object} config.model Key of the attribute to convert from or a `{ key, values, [ name ] }` object describing
+ * @param {String|Object} config.model The key of the attribute to convert from or a `{ key, values, [ name ] }` object describing
  * the attribute key, possible values and, optionally, an element name to convert from.
- * @param {String|Object|Function} config.view View attribute key, or a `{ key, value }` object or a function that takes
- * model attribute value and returns a `{ key, value }` object. If `key` is `'class'`, `value` can be a `String` or an
+ * @param {String|Object|Function} config.view A view attribute key, or a `{ key, value }` object or a function that takes
+ * the model attribute value and returns a `{ key, value }` object. If `key` is `'class'`, `value` can be a `String` or an
  * array of `String`s. If `key` is `'style'`, `value` is an object with key-value pairs. In other cases, `value` is a `String`.
  * If `config.model.values` is set, `config.view` should be an object assigning values from `config.model.values` to
  * `{ key, value }` objects or a functions.
@@ -232,8 +235,8 @@ export function downcastAttributeToAttribute( config ) {
 /**
  * Model marker to view element conversion helper.
  *
- * This conversion results in creating a view element on the boundaries of the converted marker. If converted marker
- * is collapsed, only one element is created. For example, model marker set like this `<paragraph>F[oo b]ar</paragraph>`
+ * This conversion results in creating a view element on the boundaries of the converted marker. If the converted marker
+ * is collapsed, only one element is created. For example, model marker set like this: `<paragraph>F[oo b]ar</paragraph>`
  * becomes `<p>F<span data-marker="search"></span>oo b<span data-marker="search"></span>ar</p>` in the view.
  *
  *		downcastMarkerToElement( { model: 'search', view: 'marker-search' } );
@@ -257,21 +260,21 @@ export function downcastAttributeToAttribute( config ) {
  * 			}
  * 		} );
  *
- * If function is passed as `config.view` parameter, it will be used to generate both boundary elements. The function
- * receives `data` object as parameter and should return an instance of {@link module:engine/view/uielement~UIElement view.UIElement}.
- * The `data` and `conversionApi` objects are passed from
+ * If a function is passed as the `config.view` parameter, it will be used to generate both boundary elements. The function
+ * receives the `data` object as a parameter and should return an instance of the
+ * {@link module:engine/view/uielement~UIElement view UI element}. The `data` and `conversionApi` objects are passed from
  * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:addMarker}. Additionally,
- * `data.isOpening` parameter is passed, which is set to `true` for marker start boundary element, and `false` to
- * marker end boundary element.
+ * the `data.isOpening` parameter is passed, which is set to `true` for the marker start boundary element, and `false` to
+ * the marker end boundary element.
  *
- * This kind of conversion is useful for saving data into data base, so it should be used in data conversion pipeline.
+ * This kind of conversion is useful for saving data into the database, so it should be used in the data conversion pipeline.
  *
- * See {@link module:engine/conversion/conversion~Conversion#for} to learn how to add converter to conversion process.
+ * See {@link module:engine/conversion/conversion~Conversion#for} to learn how to add a converter to the conversion process.
  *
  * @param {Object} config Conversion configuration.
- * @param {String} config.model Name of the model marker (or model marker group) to convert.
- * @param {module:engine/view/elementdefinition~ElementDefinition|Function} config.view View element definition or a function
- * that takes model marker data as a parameter and returns view ui element.
+ * @param {String} config.model The name of the model marker (or model marker group) to convert.
+ * @param {module:engine/view/elementdefinition~ElementDefinition|Function} config.view A view element definition or a function
+ * that takes the model marker data as a parameter and returns a view UI element.
  * @param {module:utils/priorities~PriorityString} [config.converterPriority='normal'] Converter priority.
  * @returns {Function} Conversion helper.
  */
@@ -292,18 +295,18 @@ export function downcastMarkerToElement( config ) {
  * This conversion results in creating a highlight on view nodes. For this kind of conversion,
  * {@link module:engine/conversion/downcast-converters~HighlightDescriptor} should be provided.
  *
- * For text nodes, a `span` {@link module:engine/view/attributeelement~AttributeElement} is created and it wraps all text nodes
- * in the converted marker range. For example, model marker set like this `<paragraph>F[oo b]ar</paragraph>` becomes
+ * For text nodes, a `<span>` {@link module:engine/view/attributeelement~AttributeElement} is created and it wraps all text nodes
+ * in the converted marker range. For example, a model marker set like this: `<paragraph>F[oo b]ar</paragraph>` becomes
  * `<p>F<span class="comment">oo b</span>ar</p>` in the view.
  *
- * {@link module:engine/view/containerelement~ContainerElement} may provide custom way of handling highlight. Most often,
- * the element itself is given classes and attributes described in the highlight descriptor (instead of being wrapped in `span`).
- * For example, model marker set like this `[<image src="foo.jpg"></image>]` becomes `<img src="foo.jpg" class="comment"></img>`
+ * {@link module:engine/view/containerelement~ContainerElement} may provide a custom way of handling highlight. Most often,
+ * the element itself is given classes and attributes described in the highlight descriptor (instead of being wrapped in `<span>`).
+ * For example, a model marker set like this: `[<image src="foo.jpg"></image>]` becomes `<img src="foo.jpg" class="comment"></img>`
  * in the view.
  *
- * For container elements, the conversion is two-step. While the converter processes highlight descriptor and passes it
- * to a container element, it is the container element instance itself which applies values from highlight descriptor.
- * So, in a sense, converter takes care of stating what should be applied on what, while element decides how to apply that.
+ * For container elements, the conversion is two-step. While the converter processes the highlight descriptor and passes it
+ * to a container element, it is the container element instance itself that applies values from the highlight descriptor.
+ * So, in a sense, the converter takes care of stating what should be applied on what, while the element decides how to apply that.
  *
  *		downcastMarkerToHighlight( { model: 'comment', view: { classes: 'comment' } } );
  *
@@ -312,7 +315,7 @@ export function downcastMarkerToElement( config ) {
  * 		downcastMarkerToHighlight( {
  * 			model: 'comment',
  * 			view: data => {
- * 				// Assuming that marker name is in a form of comment:commentType.
+ * 				// Assuming that the marker name is in a form of comment:commentType.
  *	 			const commentType = data.markerName.split( ':' )[ 1 ];
  *
  *	 			return {
@@ -321,16 +324,17 @@ export function downcastMarkerToElement( config ) {
  * 			}
  * 		} );
  *
- * If function is passed as `config.view` parameter, it will be used to generate highlight descriptor. The function
- * receives `data` object as parameter and should return a {@link module:engine/conversion/downcast-converters~HighlightDescriptor}.
+ * If a function is passed as the `config.view` parameter, it will be used to generate the highlight descriptor. The function
+ * receives the `data` object as a parameter and should return a
+ * {@link module:engine/conversion/downcast-converters~HighlightDescriptor highlight descriptor}.
  * The `data` object properties are passed from {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:addMarker}.
  *
- * See {@link module:engine/conversion/conversion~Conversion#for} to learn how to add converter to conversion process.
+ * See {@link module:engine/conversion/conversion~Conversion#for} to learn how to add a converter to the conversion process.
  *
  * @param {Object} config Conversion configuration.
- * @param {String} config.model Name of the model marker (or model marker group) to convert.
- * @param {module:engine/conversion/downcast-converters~HighlightDescriptor|Function} config.view Highlight descriptor
- * which will be used for highlighting or a function that takes model marker data as a parameter and returns a highlight descriptor.
+ * @param {String} config.model The name of the model marker (or model marker group) to convert.
+ * @param {module:engine/conversion/downcast-converters~HighlightDescriptor|Function} config.view A highlight descriptor
+ * that will be used for highlighting or a function that takes the model marker data as a parameter and returns a highlight descriptor.
  * @param {module:utils/priorities~PriorityString} [config.converterPriority='normal'] Converter priority.
  * @returns {Function} Conversion helper.
  */
@@ -342,8 +346,8 @@ export function downcastMarkerToHighlight( config ) {
 	};
 }
 
-// Takes `config.view`, and if it is a {@link module:engine/view/elementdefinition~ElementDefinition}, converts it
-// to a function (because lower level converters accepts only element creator functions).
+// Takes `config.view`, and if it is an {@link module:engine/view/elementdefinition~ElementDefinition}, converts it
+// to a function (because lower level converters accept only element creator functions).
 //
 // @param {module:engine/view/elementdefinition~ElementDefinition|Function} view View configuration.
 // @param {'container'|'attribute'|'ui'} viewElementType View element type to create.
@@ -357,7 +361,7 @@ function _normalizeToElementConfig( view, viewElementType ) {
 	return ( modelData, viewWriter ) => _createViewElementFromDefinition( view, viewWriter, viewElementType );
 }
 
-// Creates view element instance from provided viewElementDefinition and class.
+// Creates a view element instance from the provided {@link module:engine/view/elementdefinition~ElementDefinition} and class.
 //
 // @param {module:engine/view/elementdefinition~ElementDefinition} viewElementDefinition
 // @param {module:engine/view/writer~Writer} viewWriter
@@ -424,8 +428,8 @@ function _getFromAttributeCreator( config ) {
 	}
 }
 
-// Takes config and adds default parameters if they don't exist and normalizes other parameters to be used in downcast converters
-// for generating view attribute.
+// Takes the configuration, adds default parameters if they do not exist and normalizes other parameters to be used in downcast converters
+// for generating a view attribute.
 //
 // @param {Object} view View configuration.
 function _normalizeToAttributeConfig( view ) {
@@ -447,14 +451,14 @@ function _normalizeToAttributeConfig( view ) {
 }
 
 /**
- * Function factory, creates a converter that converts node insertion changes from the model to the view.
- * Passed function will be provided with all the parameters of the dispatcher's
- * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:insert insert event}.
- * It's expected that the function returns a {@link module:engine/view/element~Element}.
- * The result of the function will be inserted to the view.
+ * Function factory that creates a converter which converts node insertion changes from the model to the view.
+ * The function passed will be provided with all the parameters of the dispatcher's
+ * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:insert `insert` event}.
+ * It is expected that the function returns an {@link module:engine/view/element~Element}.
+ * The result of the function will be inserted into the view.
  *
- * The converter automatically consumes corresponding value from consumables list, stops the event (see
- * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher}) and bind model and view elements.
+ * The converter automatically consumes the corresponding value from the consumables list, stops the event (see
+ * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher}) and binds the model and view elements.
  *
  *		downcastDispatcher.on(
  *			'insert:myElem',
@@ -462,7 +466,7 @@ function _normalizeToAttributeConfig( view ) {
  *				const text = viewWriter.createText( 'myText' );
  *				const myElem = viewWriter.createElement( 'myElem', { myAttr: 'my-' + modelItem.getAttribute( 'myAttr' ) }, text );
  *
- *				// Do something fancy with myElem using `modelItem` or other parameters.
+ *				// Do something fancy with `myElem` using `modelItem` or other parameters.
  *
  *				return myElem;
  *			}
@@ -491,9 +495,9 @@ export function insertElement( elementCreator ) {
 }
 
 /**
- * Function factory, creates a default downcast converter for text insertion changes.
+ * Function factory that creates a default downcast converter for text insertion changes.
  *
- * The converter automatically consumes corresponding value from consumables list and stops the event (see
+ * The converter automatically consumes the corresponding value from the consumables list and stops the event (see
  * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher}).
  *
  *		modelDispatcher.on( 'insert:$text', insertText() );
@@ -515,7 +519,7 @@ export function insertText() {
 }
 
 /**
- * Function factory, creates a default downcast converter for node remove changes.
+ * Function factory that creates a default downcast converter for node remove changes.
  *
  *		modelDispatcher.on( 'remove', remove() );
  *
@@ -543,17 +547,17 @@ export function remove() {
 }
 
 /**
- * Function factory, creates a converter that converts marker adding change to the view ui element.
+ * Function factory that creates a converter which converts marker adding change to the
+ * {@link module:engine/view/uielement~UIElement view UI element}.
  *
- * The view ui element, that will be added to the view, depends on passed parameter. See {@link ~insertElement}.
- * In a case of a non-collapsed range, the ui element will not wrap nodes but separate elements will be placed at the beginning
+ * The view UI element that will be added to the view depends on the passed parameter. See {@link ~insertElement}.
+ * In case of a non-collapsed range, the UI element will not wrap nodes but separate elements will be placed at the beginning
  * and at the end of the range.
  *
- * This converter binds created {@link module:engine/view/uielement~UIElement}s with marker name using
- * the {@link module:engine/conversion/mapper~Mapper#bindElementToMarker}.
+ * This converter binds created UI elements with the marker name using {@link module:engine/conversion/mapper~Mapper#bindElementToMarker}.
  *
- * @param {module:engine/view/uielement~UIElement|Function} elementCreator View ui element or a function returning a view element
- * which will be inserted.
+ * @param {module:engine/view/uielement~UIElement|Function} elementCreator A view UI element or a function returning the view element
+ * that will be inserted.
  * @returns {Function} Insert element event converter.
  */
 export function insertUIElement( elementCreator ) {
@@ -604,12 +608,12 @@ export function insertUIElement( elementCreator ) {
 }
 
 /**
- * Function factory, returns a default downcast converter for removing {@link module:engine/view/uielement~UIElement ui element}
+ * Function factory that returns a default downcast converter for removing a {@link module:engine/view/uielement~UIElement UI element}
  * basing on marker remove change.
  *
- * This converter unbinds elements from marker name.
+ * This converter unbinds elements from the marker name.
  *
- * @returns {Function} Remove ui element converter.
+ * @returns {Function} Removed UI element converter.
  */
 export function removeUIElement() {
 	return ( evt, data, conversionApi ) => {
@@ -632,19 +636,19 @@ export function removeUIElement() {
 }
 
 /**
- * Function factory, creates a converter that converts set/change/remove attribute changes from the model to the view.
+ * Function factory that creates a converter which converts set/change/remove attribute changes from the model to the view.
  *
- * Attributes from model are converted to the view element attributes in the view. You may provide a custom function to generate
- * a key-value attribute pair to add/change/remove. If not provided, model attributes will be converted to view elements
- * attributes on 1-to-1 basis.
+ * Attributes from the model are converted to the view element attributes in the view. You may provide a custom function to generate
+ * a key-value attribute pair to add/change/remove. If not provided, model attributes will be converted to view element
+ * attributes on a one-to-one basis.
  *
- * **Note:** Provided attribute creator should always return the same `key` for given attribute from the model.
+ * **Note:** The provided attribute creator should always return the same `key` for a given attribute from the model.
  *
- * The converter automatically consumes corresponding value from consumables list and stops the event (see
+ * The converter automatically consumes the corresponding value from the consumables list and stops the event (see
  * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher}).
  *
  *		modelDispatcher.on( 'attribute:customAttr:myElem', changeAttribute( ( value, data ) => {
- *			// Change attribute key from `customAttr` to `class` in view.
+ *			// Change attribute key from `customAttr` to `class` in the view.
  *			const key = 'class';
  *			let value = data.attributeNewValue;
  *
@@ -653,13 +657,13 @@ export function removeUIElement() {
  *				value = 'empty';
  *			}
  *
- *			// Return key-value pair.
+ *			// Return the key-value pair.
  *			return { key, value };
  *		} ) );
  *
  * @param {Function} [attributeCreator] Function returning an object with two properties: `key` and `value`, which
- * represents attribute key and attribute value to be set on a {@link module:engine/view/element~Element view element}.
- * The function is passed model attribute value as first parameter and additional data about the change as a second parameter.
+ * represent the attribute key and attribute value to be set on a {@link module:engine/view/element~Element view element}.
+ * The function is passed the model attribute value as the first parameter and additional data about the change as the second parameter.
  * @returns {Function} Set/change attribute converter.
  */
 export function changeAttribute( attributeCreator ) {
@@ -721,12 +725,12 @@ export function changeAttribute( attributeCreator ) {
 }
 
 /**
- * Function factory, creates a converter that converts set/change/remove attribute changes from the model to the view.
- * Also can be used to convert selection attributes. In that case, an empty attribute element will be created and the
+ * Function factory that creates a converter which converts set/change/remove attribute changes from the model to the view.
+ * It can also be used to convert selection attributes. In that case, an empty attribute element will be created and the
  * selection will be put inside it.
  *
- * Attributes from model are converted to a view element that will be wrapping those view nodes that are bound to
- * model elements having given attribute. This is useful for attributes like `bold`, which may be set on text nodes in model
+ * Attributes from the model are converted to a view element that will be wrapping these view nodes that are bound to
+ * model elements having the given attribute. This is useful for attributes like `bold` that may be set on text nodes in the model
  * but are represented as an element in the view:
  *
  *		[paragraph]              MODEL ====> VIEW        <p>
@@ -734,20 +738,20 @@ export function changeAttribute( attributeCreator ) {
  *			|- b {bold: true}                             |   |- ab
  *			|- c                                          |- c
  *
- * Passed `Function` will be provided with attribute value and then all the parameters of the
- * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute attribute event}.
- * It's expected that the function returns a {@link module:engine/view/element~Element}.
+ * Passed `Function` will be provided with the attribute value and then all the parameters of the
+ * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute `attribute` event}.
+ * It is expected that the function returns an {@link module:engine/view/element~Element}.
  * The result of the function will be the wrapping element.
- * When provided `Function` does not return element, then will be no conversion.
+ * When the provided `Function` does not return any element, no conversion will take place.
  *
- * The converter automatically consumes corresponding value from consumables list, stops the event (see
+ * The converter automatically consumes the corresponding value from the consumables list and stops the event (see
  * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher}).
  *
  *		modelDispatcher.on( 'attribute:bold', wrapItem( ( modelAttributeValue, viewWriter ) => {
  *			return viewWriter.createAttributeElement( 'strong' );
  *		} );
  *
- * @param {Function} elementCreator Function returning a view element, which will be used for wrapping.
+ * @param {Function} elementCreator Function returning a view element that will be used for wrapping.
  * @returns {Function} Set/change attribute converter.
  */
 export function wrap( elementCreator ) {
@@ -790,19 +794,19 @@ export function wrap( elementCreator ) {
 }
 
 /**
- * Function factory, creates converter that converts text inside marker's range. Converter wraps the text with
- * {@link module:engine/view/attributeelement~AttributeElement} created from provided descriptor.
+ * Function factory that creates a converter which converts the text inside marker's range. The converter wraps the text with
+ * {@link module:engine/view/attributeelement~AttributeElement} created from the provided descriptor.
  * See {link module:engine/conversion/downcast-converters~createViewElementFromHighlightDescriptor}.
  *
- * Also can be used to convert selection that is inside a marker. In that case, an empty attribute element will be
+ * It can also be used to convert the selection that is inside a marker. In that case, an empty attribute element will be
  * created and the selection will be put inside it.
  *
- * If the highlight descriptor will not provide `priority` property, `10` will be used.
+ * If the highlight descriptor does not provide the `priority` property, `10` will be used.
  *
- * If the highlight descriptor will not provide `id` property, name of the marker will be used.
+ * If the highlight descriptor does not provide the `id` property, the name of the marker will be used.
  *
- * This converter binds created {@link module:engine/view/attributeelement~AttributeElement}s with marker name using
- * the {@link module:engine/conversion/mapper~Mapper#bindElementToMarker}.
+ * This converter binds the created {@link module:engine/view/attributeelement~AttributeElement attribute elemens} with the marker name
+ * using the {@link module:engine/conversion/mapper~Mapper#bindElementToMarker} method.
  *
  * @param {module:engine/conversion/downcast-converters~HighlightDescriptor|Function} highlightDescriptor
  * @return {Function}
@@ -851,21 +855,21 @@ export function highlightText( highlightDescriptor ) {
 }
 
 /**
- * Converter function factory. Creates a function which applies the marker's highlight to an element inside the marker's range.
+ * Converter function factory. It creates a function which applies the marker's highlight to an element inside the marker's range.
  *
- * The converter checks if an element has `addHighlight` function stored as
+ * The converter checks if an element has the `addHighlight` function stored as a
  * {@link module:engine/view/element~Element#_setCustomProperty custom property} and, if so, uses it to apply the highlight.
- * In such case converter will consume all element's children, assuming that they were handled by element itself.
+ * In such case the converter will consume all element's children, assuming that they were handled by the element itself.
  *
- * When `addHighlight` custom property is not present, element is not converted in any special way.
- * This means that converters will proceed to convert element's child nodes.
+ * When the `addHighlight` custom property is not present, the element is not converted in any special way.
+ * This means that converters will proceed to convert the element's child nodes.
  *
- * If the highlight descriptor will not provide `priority` property, `10` will be used.
+ * If the highlight descriptor does not provide the `priority` property, `10` will be used.
  *
- * If the highlight descriptor will not provide `id` property, name of the marker will be used.
+ * If the highlight descriptor does not provide the `id` property, the name of the marker will be used.
  *
- * This converter binds altered {@link module:engine/view/containerelement~ContainerElement}s with marker name using
- * the {@link module:engine/conversion/mapper~Mapper#bindElementToMarker}.
+ * This converter binds altered {@link module:engine/view/containerelement~ContainerElement container elements} with the marker name using
+ * the {@link module:engine/conversion/mapper~Mapper#bindElementToMarker} method.
  *
  * @param {module:engine/conversion/downcast-converters~HighlightDescriptor|Function} highlightDescriptor
  * @return {Function}
@@ -909,25 +913,25 @@ export function highlightElement( highlightDescriptor ) {
 }
 
 /**
- * Function factory, creates a converter that converts removing model marker to the view.
+ * Function factory that creates a converter which converts the removing model marker to the view.
  *
  * Both text nodes and elements are handled by this converter but they are handled a bit differently.
  *
- * Text nodes are unwrapped using {@link module:engine/view/attributeelement~AttributeElement} created from provided
- * highlight descriptor. See {link module:engine/conversion/downcast-converters~highlightDescriptorToAttributeElement}.
+ * Text nodes are unwrapped using the {@link module:engine/view/attributeelement~AttributeElement attribute element} created from the
+ * provided highlight descriptor. See {link module:engine/conversion/downcast-converters~HighlightDescriptor}.
  *
- * For elements, the converter checks if an element has `removeHighlight` function stored as
+ * For elements, the converter checks if an element has the `removeHighlight` function stored as a
  * {@link module:engine/view/element~Element#_setCustomProperty custom property}. If so, it uses it to remove the highlight.
- * In such case, children of that element will not be converted.
+ * In such case, the children of that element will not be converted.
  *
- * When `removeHighlight` is not present, element is not converted in any special way.
- * Instead converter will proceed to convert element's child nodes.
+ * When `removeHighlight` is not present, the element is not converted in any special way.
+ * The converter will proceed to convert the element's child nodes instead.
  *
- * If the highlight descriptor will not provide `priority` property, `10` will be used.
+ * If the highlight descriptor does not provide the `priority` property, `10` will be used.
  *
- * If the highlight descriptor will not provide `id` property, name of the marker will be used.
+ * If the highlight descriptor does not provide the `id` property, the name of the marker will be used.
  *
- * This converter unbinds elements from marker name.
+ * This converter unbinds elements from the marker name.
  *
  * @param {module:engine/conversion/downcast-converters~HighlightDescriptor|Function} highlightDescriptor
  * @return {Function}
@@ -995,9 +999,9 @@ function _prepareDescriptor( highlightDescriptor, data, conversionApi ) {
 }
 
 /**
- * Creates `span` {@link module:engine/view/attributeelement~AttributeElement view attribute element} from information
- * provided by {@link module:engine/conversion/downcast-converters~HighlightDescriptor} object. If priority
- * is not provided in descriptor - default priority will be used.
+ * Creates a `<span>` {@link module:engine/view/attributeelement~AttributeElement view attribute element} from the information
+ * provided by the {@link module:engine/conversion/downcast-converters~HighlightDescriptor highlight descriptor} object. If a priority
+ * is not provided in the descriptor, the default priority will be used.
  *
  * @param {module:engine/conversion/downcast-converters~HighlightDescriptor} descriptor
  * @returns {module:engine/view/attributeelement~AttributeElement}
@@ -1019,35 +1023,36 @@ export function createViewElementFromHighlightDescriptor( descriptor ) {
 }
 
 /**
- * Object describing how the marker highlight should be represented in the view.
+ * An object describing how the marker highlight should be represented in the view.
  *
- * Each text node contained in a highlighted range will be wrapped in a `span` {@link module:engine/view/attributeelement~AttributeElement}
- * with CSS class(es), attributes and priority described by this object.
+ * Each text node contained in a highlighted range will be wrapped in a `<span>`
+ * {@link module:engine/view/attributeelement~AttributeElement view attribute element} with CSS class(es), attributes and a priority
+ * described by this object.
  *
- * Additionally, each {@link module:engine/view/containerelement~ContainerElement} can handle displaying the highlight separately
- * by providing `addHighlight` and `removeHighlight` custom properties. In this case:
+ * Additionally, each {@link module:engine/view/containerelement~ContainerElement container element} can handle displaying the highlight
+ * separately by providing the `addHighlight` and `removeHighlight` custom properties. In this case:
  *
- *  * `HighlightDescriptor` object is passed to the `addHighlight` function upon conversion and should be used to apply the highlight to
- *  the element,
- *  * descriptor `id` is passed to the `removeHighlight` function upon conversion and should be used to remove the highlight of given
- *  id from the element.
+ *  * The `HighlightDescriptor` object is passed to the `addHighlight` function upon conversion and should be used to apply the highlight to
+ *  the element.
+ *  * The descriptor `id` is passed to the `removeHighlight` function upon conversion and should be used to remove the highlight with the
+ *  given ID from the element.
  *
  * @typedef {Object} module:engine/conversion/downcast-converters~HighlightDescriptor
  *
- * @property {String|Array.<String>} classes CSS class or array of classes to set. If descriptor is used to
- * create {@link module:engine/view/attributeelement~AttributeElement} over text nodes, those classes will be set
- * on that {@link module:engine/view/attributeelement~AttributeElement}. If descriptor is applied to an element,
- * usually those class will be set on that element, however this depends on how the element converts the descriptor.
+ * @property {String|Array.<String>} classes A CSS class or an array of classes to set. If the descriptor is used to
+ * create an {@link module:engine/view/attributeelement~AttributeElement attribute element} over text nodes, these classes will be set
+ * on that attribute element. If the descriptor is applied to an element, usually these classes will be set on that element, however,
+ * this depends on how the element converts the descriptor.
  *
- * @property {String} [id] Descriptor identifier. If not provided, defaults to converted marker's name.
+ * @property {String} [id] Descriptor identifier. If not provided, it defaults to the converted marker's name.
  *
- * @property {Number} [priority] Descriptor priority. If not provided, defaults to `10`. If descriptor is used to create
- * {@link module:engine/view/attributeelement~AttributeElement}, it will be that element's
- * {@link module:engine/view/attributeelement~AttributeElement#priority}. If descriptor is applied to an element,
+ * @property {Number} [priority] Descriptor priority. If not provided, it defaults to `10`. If the descriptor is used to create
+ * an {@link module:engine/view/attributeelement~AttributeElement attribute element}, it will be that element's
+ * {@link module:engine/view/attributeelement~AttributeElement#priority priority}. If the descriptor is applied to an element,
  * the priority will be used to determine which descriptor is more important.
  *
- * @property {Object} [attributes] Attributes to set. If descriptor is used to create
- * {@link module:engine/view/attributeelement~AttributeElement} over text nodes, those attributes will be set on that
- * {@link module:engine/view/attributeelement~AttributeElement}. If descriptor is applied to an element, usually those
- * attributes will be set on that element, however this depends on how the element converts the descriptor.
+ * @property {Object} [attributes] Attributes to set. If the descriptor is used to create
+ * an {@link module:engine/view/attributeelement~AttributeElement attribute element} over text nodes, these attributes will be set on that
+ * attribute element. If the descriptor is applied to an element, usually these attributes will be set on that element, however,
+ * this depends on how the element converts the descriptor.
  */

+ 14 - 14
packages/ckeditor5-engine/src/conversion/downcast-selection-converters.js

@@ -6,15 +6,15 @@
 /**
  * Contains {@link module:engine/model/selection~Selection model selection} to
  * {@link module:engine/view/documentselection~DocumentSelection view selection} converters for
- * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher}.
+ * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher downcast dispatcher}.
  *
  * @module engine/conversion/downcast-selection-converters
  */
 
 /**
- * Function factory, creates a converter that converts non-collapsed {@link module:engine/model/selection~Selection model selection} to
- * {@link module:engine/view/documentselection~DocumentSelection view selection}. The converter consumes appropriate
- * value from `consumable` object and maps model positions from selection to view positions.
+ * Function factory that creates a converter which converts a non-collapsed {@link module:engine/model/selection~Selection model selection}
+ * to a {@link module:engine/view/documentselection~DocumentSelection view selection}. The converter consumes appropriate
+ * value from the `consumable` object and maps model positions from the selection to view positions.
  *
  *		modelDispatcher.on( 'selection', convertRangeSelection() );
  *
@@ -44,21 +44,21 @@ export function convertRangeSelection() {
 }
 
 /**
- * Function factory, creates a converter that converts collapsed {@link module:engine/model/selection~Selection model selection} to
- * {@link module:engine/view/documentselection~DocumentSelection view selection}. The converter consumes appropriate
- * value from `consumable` object, maps model selection position to view position and breaks
+ * Function factory that creates a converter which converts a collapsed {@link module:engine/model/selection~Selection model selection} to
+ * a {@link module:engine/view/documentselection~DocumentSelection view selection}. The converter consumes appropriate
+ * value from the `consumable` object, maps the model selection position to the view position and breaks
  * {@link module:engine/view/attributeelement~AttributeElement attribute elements} at the selection position.
  *
  *		modelDispatcher.on( 'selection', convertCollapsedSelection() );
  *
- * Example of view state before and after converting collapsed selection:
+ * An example of the view state before and after converting the collapsed selection:
  *
  *		   <p><strong>f^oo<strong>bar</p>
  *		-> <p><strong>f</strong>^<strong>oo</strong>bar</p>
  *
- * By breaking attribute elements like `<strong>`, selection is in correct element. Then, when selection attribute is
- * converted, the broken attributes might be merged again, or the position where the selection is may be wrapped
- * in different, appropriate attribute elements.
+ * By breaking attribute elements like `<strong>`, the selection is in a correct element. Then, when the selection attribute is
+ * converted, broken attributes might be merged again, or the position where the selection is may be wrapped
+ * with different, appropriate attribute elements.
  *
  * See also {@link module:engine/conversion/downcast-selection-converters~clearAttributes} which does a clean-up
  * by merging attributes.
@@ -87,9 +87,9 @@ export function convertCollapsedSelection() {
 }
 
 /**
- * Function factory, creates a converter that clears artifacts after the previous
+ * Function factory that creates a converter which clears artifacts after the previous
  * {@link module:engine/model/selection~Selection model selection} conversion. It removes all empty
- * {@link module:engine/view/attributeelement~AttributeElement view attribute elements} and merge sibling attributes at all start and end
+ * {@link module:engine/view/attributeelement~AttributeElement view attribute elements} and merges sibling attributes at all start and end
  * positions of all ranges.
  *
  *		   <p><strong>^</strong></p>
@@ -106,7 +106,7 @@ export function convertCollapsedSelection() {
  *		modelDispatcher.on( 'selection', clearAttributes() );
  *
  * See {@link module:engine/conversion/downcast-selection-converters~convertCollapsedSelection}
- * which do the opposite by breaking attributes in the selection position.
+ * which does the opposite by breaking attributes in the selection position.
  *
  * @returns {Function} Selection converter.
  */

+ 70 - 55
packages/ckeditor5-engine/src/model/writer.js

@@ -52,7 +52,7 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  *			writer.insertText( 'foo', paragraph, 'end' );
  *		} );
  *
- * Note that the should never be stored and used outside of the `change()` or
+ * Note that the writer should never be stored and used outside of the `change()` and
  * `enqueueChange()` blocks.
  *
  * @see module:engine/model/model~Model#change
@@ -62,8 +62,8 @@ export default class Writer {
 	/**
 	 * Creates a writer instance.
 	 *
-	 * **Note:** It is not recommended to use it directly. Use {@link module:engine/model/model~Model#change} or
-	 * {@link module:engine/model/model~Model#enqueueChange} instead.
+	 * **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
@@ -71,12 +71,16 @@ export default class Writer {
 	 */
 	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}
 		 */
@@ -87,7 +91,7 @@ export default class Writer {
 	 * Creates a new {@link module:engine/model/text~Text text node}.
 	 *
 	 *		writer.createText( 'foo' );
-	 *		writer.createText( 'foo', { 'bold': true } );
+	 *		writer.createText( 'foo', { bold: true } );
 	 *
 	 * @param {String} data Text data.
 	 * @param {Object} [attributes] Text attributes.
@@ -101,7 +105,7 @@ export default class Writer {
 	 * Creates a new {@link module:engine/model/element~Element element}.
 	 *
 	 *		writer.createElement( 'paragraph' );
-	 *		writer.createElement( 'paragraph', { 'alignment': 'center' } );
+	 *		writer.createElement( 'paragraph', { alignment: 'center' } );
 	 *
 	 * @param {String} name Name of the element.
 	 * @param {Object} [attributes] Elements attributes.
@@ -128,28 +132,28 @@ export default class Writer {
 	 *
 	 * Instead of using position you can use parent and offset:
 	 *
-	 * 		const text = writer.createText( 'foo' );
+	 *		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' );
+	 *		const text = writer.createText( 'foo' );
 	 *		writer.insert( text, paragraph, 'end' );
 	 *
 	 * Or insert before or after another element:
 	 *
-	 * 		const paragraph = writer.createElement( 'paragraph' );
+	 *		const paragraph = writer.createElement( 'paragraph' );
 	 *		writer.insert( paragraph, anotherParagraph, 'after' );
 	 *
-	 * These parameters works the same way as {@link module:engine/model/position~Position.createAt}.
+	 * These parameters works the same way as {@link module:engine/model/position~Position.createAt `Position.createAt()`}.
 	 *
 	 * Note that if the item already has parent it will be removed from the previous parent.
 	 *
-	 * Note that you cannot re-insert a node from a document to a different document or document fragment. In this case,
+	 * Note that you cannot re-insert a node from a document to a different document or a document fragment. In this case,
 	 * `model-writer-insert-forbidden-move` is thrown.
 	 *
 	 * 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 move}.
+	 * {@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.
@@ -214,16 +218,19 @@ 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 );
+	 *		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:
 	 *
-	 * 		writer.insertText( 'foo', paragraph, 5 ); // inserts in paragraph, at offset 5
-	 *		writer.insertText( 'foo', paragraph, 'end' ); // inserts at the end of the paragraph
-	 *		writer.insertText( 'foo', image, 'after' ); // inserts after image
+	 *		// 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 works the same way as {@link module:engine/model/position~Position.createAt}.
+	 * These parameters work in the same way as {@link module:engine/model/position~Position.createAt `Position.createAt()`}.
 	 *
 	 * @param {String} data Text data.
 	 * @param {Object} [attributes] Text attributes.
@@ -243,16 +250,19 @@ export default class Writer {
 	 * Creates and inserts element on given position. You can optionally set attributes:
 	 *
 	 *		writer.insertElement( 'paragraph', position );
-	 *		writer.insertElement( 'paragraph', { 'alignment': 'center' }, 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:
 	 *
-	 * 		writer.insertElement( 'paragraph', paragraph, 5 ); // inserts in paragraph, at offset 5
-	 *		writer.insertElement( 'paragraph', blockquote, 'end' ); // insets at the end of the blockquote
-	 *		writer.insertElement( 'paragraph', image, 'after' ); // inserts after image
+	 *		// 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 module:engine/model/position~Position.createAt}.
+	 * These parameters works the same way as {@link module:engine/model/position~Position.createAt `Position.createAt()`}.
 	 *
 	 * @param {String} name Name of the element.
 	 * @param {Object} [attributes] Elements attributes.
@@ -277,7 +287,7 @@ export default class Writer {
 	 * 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 move}.
+	 * {@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.
@@ -291,7 +301,7 @@ export default class Writer {
 	 * 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 );
+	 *		writer.appendText( 'foo', { bold: true }, paragraph );
 	 *
 	 * @param {String} text Text data.
 	 * @param {Object} [attributes] Text attributes.
@@ -309,7 +319,7 @@ export default class Writer {
 	 * 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 );
+	 *		writer.appendElement( 'paragraph', { alignment: 'center' }, root );
 	 *
 	 * @param {String} name Name of the element.
 	 * @param {Object} [attributes] Elements attributes.
@@ -347,8 +357,8 @@ export default class Writer {
 	 * or on a {@link module:engine/model/range~Range range}.
 	 *
 	 *		writer.setAttributes( {
-	 *			'bold': true,
-	 *			'italic': true
+	 *			bold: true,
+	 *			italic: true
 	 *		}, range );
 	 *
 	 * @param {Object} attributes Attributes keys and values.
@@ -411,11 +421,14 @@ export default class Writer {
 	 * 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:
 	 *
-	 * 		writer.move( sourceRange, paragraph, 5 ); // moves all items in the range to the paragraph at offset 5
-	 *		writer.move( sourceRange, blockquote, 'end' ); // moves all items in the range at the end of the blockquote
-	 *		writer.move( sourceRange, image, 'after' ); // moves all items in the range after the image
+	 *		// 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 module:engine/model/position~Position.createAt}.
+	 * These parameters works the same way as {@link module:engine/model/position~Position.createAt `Position.createAt()`}.
 	 *
 	 * Note that items can be moved only within the same tree. It means that you can move items within the same root
 	 * (element or document fragment) or between {@link module:engine/model/document~Document#roots documents roots},
@@ -554,7 +567,7 @@ export default class Writer {
 	}
 
 	/**
-	 * Renames given element.
+	 * Renames the given element.
 	 *
 	 * @param {module:engine/model/element~Element} element The element to rename.
 	 * @param {String} newName New element name.
@@ -584,10 +597,10 @@ export default class Writer {
 	}
 
 	/**
-	 * Splits elements start from the given position and goes to the top of the model tree as long as given
-	 * `limitElement` won't be reached. When limitElement is not defined then only a parent of given position will be split.
+	 * Splits elements starting from the given position and going to the top of the model tree as long as given
+	 * `limitElement` is reached. When `limitElement` is not defined then only the parent of the given position will be split.
 	 *
-	 * The element needs to have a parent. It cannot be a root element nor document fragment.
+	 * 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.
@@ -671,9 +684,10 @@ export default class Writer {
 	}
 
 	/**
-	 * Wraps given range with given element or with a new element with specified name, if string has been passed.
+	 * Wraps the given range with the given element or with a new element (if a string was passed).
 	 *
-	 * **Note:** range to wrap should be a "flat range" (see {@link module:engine/model/range~Range#isFlat}). If not, error will be thrown.
+	 * **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.
@@ -782,11 +796,11 @@ export default class Writer {
 	 *
 	 * Create marker directly base on marker's name:
 	 *
-	 * 		addMarker( markerName, { range, usingOperation: false } );
+	 *		addMarker( markerName, { range, usingOperation: false } );
 	 *
 	 * Create marker using operation:
 	 *
-	 * 		addMarker( markerName, { range, usingOperation: true } );
+	 *		addMarker( markerName, { range, usingOperation: true } );
 	 *
 	 * Note: For efficiency reasons, it's best to create and keep as little markers as possible.
 	 *
@@ -803,7 +817,7 @@ export default class Writer {
 
 		if ( !options || typeof options.usingOperation != 'boolean' ) {
 			/**
-			 * The options.usingOperations parameter is required when adding a new marker.
+			 * The `options.usingOperations` parameter is required when adding a new marker.
 			 *
 			 * @error writer-addMarker-no-usingOperations
 			 */
@@ -857,16 +871,16 @@ export default class Writer {
 	 *
 	 * Update marker directly base on marker's name:
 	 *
-	 * 		updateMarker( markerName, { range } );
+	 *		updateMarker( markerName, { range } );
 	 *
 	 * Update marker using operation:
 	 *
-	 * 		updateMarker( marker, { range, usingOperation: true } );
-	 * 		updateMarker( markerName, { range, usingOperation: true } );
+	 *		updateMarker( marker, { range, usingOperation: true } );
+	 *		updateMarker( markerName, { range, usingOperation: true } );
 	 *
 	 * Change marker's option (start using operations to manage it):
 	 *
-	 * 		updateMarker( marker, { usingOperation: true } );
+	 *		updateMarker( marker, { usingOperation: true } );
 	 *
 	 * @see module:engine/model/markercollection~Marker
 	 * @param {String} markerOrName Name of a marker to update, or a marker instance.
@@ -976,22 +990,22 @@ export default class Writer {
 	 *		writer.setSelection( range );
 	 *
 	 *		// Sets selection to given ranges.
-	 * 		const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
+	 *		const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
 	 *		writer.setSelection( range );
 	 *
 	 *		// Sets selection to other selection.
 	 *		const otherSelection = new Selection();
 	 *		writer.setSelection( otherSelection );
 	 *
-	 * 		// Sets selection to the given document selection.
+	 *		// Sets selection to the given document selection.
 	 *		const documentSelection = new DocumentSelection( doc );
 	 *		writer.setSelection( documentSelection );
 	 *
-	 * 		// Sets collapsed selection at the given position.
+	 *		// Sets collapsed selection at the given position.
 	 *		const position = new Position( root, path );
 	 *		writer.setSelection( position );
 	 *
-	 * 		// Sets collapsed selection at the position of the given node and an 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
@@ -1003,12 +1017,12 @@ export default class Writer {
 	 *
 	 *		writer.setSelection( paragraph, 'on' );
 	 *
-	 * 		// Removes all selection's ranges.
+	 *		// Removes all selection's ranges.
 	 *		writer.setSelection( null );
 	 *
 	 * `Writer#setSelection()` allow passing additional options (`backward`) as the last argument.
 	 *
-	 * 		// Sets selection as backward.
+	 *		// Sets selection as backward.
 	 *		writer.setSelection( range, { backward: true } );
 	 *
 	 * Throws `writer-incorrect-use` error when the writer is used outside the `change()` block.
@@ -1029,7 +1043,8 @@ export default class Writer {
 	/**
 	 * Moves {@link module:engine/model/documentselection~DocumentSelection#focus} to the specified location.
 	 *
-	 * The location can be specified in the same form as {@link module:engine/model/position~Position.createAt} parameters.
+	 * The location can be specified in the same form as
+	 * {@link module:engine/model/position~Position.createAt `Position.createAt()`} 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
@@ -1057,7 +1072,7 @@ export default class Writer {
 	 * 	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.
+	 * or object / iterable of key => value attribute pairs.
 	 * @param {*} [value] Attribute value.
 	 */
 	setSelectionAttribute( keyOrObjectOrIterable, value ) {
@@ -1075,13 +1090,13 @@ export default class Writer {
 	/**
 	 * Removes attribute(s) with given key(s) from the selection.
 	 *
-	 * Using key
+	 * Remove one attribute:
 	 *
-	 * 	writer.removeSelectionAttribute( 'italic' );
+	 *		writer.removeSelectionAttribute( 'italic' );
 	 *
-	 * Using iterable of keys
+	 * Remove multiple attributes:
 	 *
-	 * 	writer.removeSelectionAttribute( [ 'italic', 'bold' ] );
+	 *		writer.removeSelectionAttribute( [ 'italic', 'bold' ] );
 	 *
 	 * @param {String|Iterable.<String>} keyOrIterableOfKeys Key of the attribute to remove or an iterable of attribute keys to remove.
 	 */