Przeglądaj źródła

Merge branch 'master' into t/1210

Szymon Kupś 8 lat temu
rodzic
commit
952a44893d

+ 6 - 6
packages/ckeditor5-engine/src/dev-utils/deltareplayer.js

@@ -12,7 +12,7 @@
 import DeltaFactory from '../model/delta/deltafactory';
 
 /**
- * DeltaReplayer is a dev-tool created for easily replaying operations on the document from stringified deltas.
+ * Delta replayer is a development tool created for easy replaying of operations on the document from stringified deltas.
  */
 export default class DeltaReplayer {
 	/**
@@ -27,7 +27,7 @@ export default class DeltaReplayer {
 	}
 
 	/**
-	 * Parses given string containing stringified deltas and sets parsed deltas as deltas to replay.
+	 * Parses the given string containing stringified deltas and sets parsed deltas as deltas to replay.
 	 *
 	 * @param {String} stringifiedDeltas Stringified deltas to replay.
 	 */
@@ -53,7 +53,7 @@ export default class DeltaReplayer {
 	}
 
 	/**
-	 * Applies all deltas with delay between actions.
+	 * Applies all deltas with a delay between actions.
 	 *
 	 * @param {Number} timeInterval Time between applying deltas.
 	 * @returns {Promise}
@@ -81,7 +81,7 @@ export default class DeltaReplayer {
 	/**
 	 * Applies `numberOfDeltas` deltas, beginning after the last applied delta (or first delta, if no deltas were applied).
 	 *
-	 * @param {Number} numberOfDeltas Number of deltas to apply.
+	 * @param {Number} numberOfDeltas The number of deltas to apply.
 	 * @returns {Promise}
 	 */
 	applyDeltas( numberOfDeltas ) {
@@ -112,8 +112,8 @@ export default class DeltaReplayer {
 	}
 
 	/**
-	 * Applies the next delta to replay. Returns promise with `isFinished` parameter that is `true` if the last
-	 * delta in replayer has been applied, `false` otherwise.
+	 * Applies the next delta to replay. Returns a promise with the `isFinished` parameter that is `true` if the last
+	 * delta in the replayer has been applied, `false` otherwise.
 	 *
 	 * @returns {Promise.<Boolean>}
 	 */

+ 12 - 12
packages/ckeditor5-engine/src/dev-utils/enableenginedebug.js

@@ -113,7 +113,7 @@ let logger = console;
  *
  * Every operation applied on {@link module:engine/model/document~Document model.Document} is logged.
  *
- * Following classes are expanded with `log` and meaningful `toString` methods:
+ * The following classes are expanded with `log` and meaningful `toString` methods:
  * * {@link module:engine/model/position~Position model.Position},
  * * {@link module:engine/model/range~Range model.Range},
  * * {@link module:engine/model/text~Text model.Text},
@@ -127,25 +127,25 @@ let logger = console;
  * * {@link module:engine/view/documentfragment~DocumentFragment view.DocumentFragment},
  * * {@link module:engine/view/document~Document view.Document}.
  *
- * Additionally, following logging utility methods are added:
+ * Additionally, the following logging utility methods are added:
  * * {@link module:engine/model/text~Text model.Text} `logExtended`,
  * * {@link module:engine/model/element~Element model.Element} `logExtended`,
  * * {@link module:engine/model/element~Element model.Element} `logAll`,
  * * {@link module:engine/model/delta/delta~Delta model.Delta} `logAll`.
  *
- * Additionally, following classes are expanded with `logTree` and `printTree` methods:
+ * Additionally, the following classes are expanded with `logTree` and `printTree` methods:
  * * {@link module:engine/model/element~Element model.Element},
  * * {@link module:engine/model/documentfragment~DocumentFragment model.DocumentFragment},
  * * {@link module:engine/view/element~Element view.Element},
  * * {@link module:engine/view/documentfragment~DocumentFragment view.DocumentFragment}.
  *
- * Finally, following methods are added to {@link module:core/editor/editor~Editor}: `logModel`, `logView`, `logDocuments`.
- * All those methods take one parameter, which is a version of {@link module:engine/model/document~Document model document}
- * for which model or view document state should be logged.
+ * Finally, the following methods are added to {@link module:core/editor/editor~Editor}: `logModel`, `logView`, `logDocuments`.
+ * All those methods take one parameter, which is the version of the {@link module:engine/model/document~Document model document}
+ * for which the model or view document state should be logged.
  *
- * @param {Object} [_logger] Object with functions used to log messages and errors. By default messages are logged to console.
+ * @param {Object} [_logger] An object with functions used to log messages and errors. By default messages are logged to the console.
  * If specified, it is expected to have `log()` and `error()` methods.
- * @returns {module:engine/dev-utils/enableenginedebug~DebugPlugin} Plugin to be loaded in the editor.
+ * @returns {module:engine/dev-utils/enableenginedebug~DebugPlugin} The plugin to be loaded into the editor.
  */
 export default function enableEngineDebug( _logger = console ) {
 	logger = _logger;
@@ -677,7 +677,7 @@ class DebugPlugin extends Plugin {
 	}
 }
 
-// Helper function, stores `document` state for given `version` as a string in private property.
+// Helper function, stores the `document` state for a given `version` as a string in a private property.
 function dumpTrees( document, version ) {
 	let string = '';
 
@@ -694,7 +694,7 @@ function dumpTrees( document, version ) {
 	}
 }
 
-// Helper function, returns class name of given `Delta` or `Operation`.
+// Helper function, returns the class name of a given `Delta` or `Operation`.
 // @param {module:engine/model/delta/delta~Delta|module:engine/model/operation/operation~Operation}
 // @returns {String} Class name.
 function getClassName( obj ) {
@@ -703,7 +703,7 @@ function getClassName( obj ) {
 	return path[ path.length - 1 ];
 }
 
-// Helper function, converts map to {"key1":"value1","key2":"value2"} format.
+// Helper function, converts a map to the {"key1":"value1","key2":"value2"} format.
 // @param {Map} map Map to convert.
 // @returns {String} Converted map.
 function mapString( map ) {
@@ -716,7 +716,7 @@ function mapString( map ) {
 	return JSON.stringify( obj );
 }
 
-// Helper function, converts map to key1="value1" key2="value1" format.
+// Helper function, converts a map to the key1="value1" key2="value1" format.
 // @param {Map} map Map to convert.
 // @returns {String} Converted map.
 function mapToTags( map ) {

+ 28 - 28
packages/ckeditor5-engine/src/dev-utils/model.js

@@ -8,7 +8,7 @@
  */
 
 /**
- * Collection of methods for manipulating {@link module:engine/model/model model} for testing purposes.
+ * Collection of methods for manipulating the {@link module:engine/model/model model} for testing purposes.
  */
 
 import RootElement from '../model/rootelement';
@@ -38,18 +38,18 @@ import isPlainObject from '@ckeditor/ckeditor5-utils/src/lib/lodash/isPlainObjec
 import toMap from '@ckeditor/ckeditor5-utils/src/tomap';
 
 /**
- * Writes the contents of the {@link module:engine/model/document~Document Document} to an HTML-like string.
+ * Writes the content of the {@link module:engine/model/document~Document document} to an HTML-like string.
  *
- * **Note:** {@link module:engine/model/text~Text text} node contains attributes will be represented as:
+ * **Note:** A {@link module:engine/model/text~Text text} node that contains attributes will be represented as:
  *
  *		<$text attribute="value">Text data</$text>
  *
  * @param {module:engine/model/model~Model} model
  * @param {Object} [options]
- * @param {Boolean} [options.withoutSelection=false] Whether to write the selection. When set to `true` selection will
- * be not included in returned string.
- * @param {String} [options.rootName='main'] Name of the root from which data should be stringified. If not provided
- * default `main` name will be used.
+ * @param {Boolean} [options.withoutSelection=false] Whether to write the selection. When set to `true`, the selection will
+ * not be included in the returned string.
+ * @param {String} [options.rootName='main'] The name of the root from which the data should be stringified. If not provided,
+ * the default `main` name will be used.
  * @returns {String} The stringified data.
  */
 export function getData( model, options = {} ) {
@@ -68,21 +68,21 @@ export function getData( model, options = {} ) {
 getData._stringify = stringify;
 
 /**
- * Sets the contents of the {@link module:engine/model/document~Document Document} provided as HTML-like string.
+ * Sets the content of the {@link module:engine/model/document~Document document} provided as an HTML-like string.
  *
- * **Note:** Remember to register elements in {@link module:engine/model/model~Model#schema model's schema} before inserting them.
+ * **Note:** Remember to register elements in the {@link module:engine/model/model~Model#schema model's schema} before inserting them.
  *
- * **Note:** To create {@link module:engine/model/text~Text text} node witch containing attributes use:
+ * **Note:** To create a {@link module:engine/model/text~Text text} node that contains attributes use:
  *
  *		<$text attribute="value">Text data</$text>
  *
  * @param {module:engine/model/model~Model} model
- * @param {String} data HTML-like string to write into Document.
+ * @param {String} data HTML-like string to write into the document.
  * @param {Object} options
- * @param {String} [options.rootName='main'] Root name where parsed data will be stored. If not provided, default `main`
+ * @param {String} [options.rootName='main'] Root name where parsed data will be stored. If not provided, the default `main`
  * name will be used.
- * @param {Array<Object>} [options.selectionAttributes] List of attributes which will be passed to the selection.
- * @param {Boolean} [options.lastRangeBackward=false] If set to true last range will be added as backward.
+ * @param {Array<Object>} [options.selectionAttributes] A list of attributes which will be passed to the selection.
+ * @param {Boolean} [options.lastRangeBackward=false] If set to `true`, the last range will be added as backward.
  * @param {String} [options.batchType='transparent'] Batch type used for inserting elements.
  * See {@link module:engine/model/batch~Batch#type}.
  */
@@ -145,18 +145,18 @@ setData._parse = parse;
 /**
  * Converts model nodes to HTML-like string representation.
  *
- * **Note:** {@link module:engine/model/text~Text text} node contains attributes will be represented as:
+ * **Note:** A {@link module:engine/model/text~Text text} node that contains attributes will be represented as:
  *
  *		<$text attribute="value">Text data</$text>
  *
  * @param {module:engine/model/rootelement~RootElement|module:engine/model/element~Element|module:engine/model/text~Text|
- * module:engine/model/documentfragment~DocumentFragment} node Node to stringify.
+ * module:engine/model/documentfragment~DocumentFragment} node A node to stringify.
  * @param {module:engine/model/selection~Selection|module:engine/model/position~Position|
  * module:engine/model/range~Range} [selectionOrPositionOrRange=null]
- * Selection instance which ranges will be included in returned string data. If Range instance is provided - it will be
- * converted to selection containing this range. If Position instance is provided - it will be converted to selection
+ * A selection instance whose ranges will be included in the returned string data. If a range instance is provided, it will be
+ * converted to a selection containing this range. If a position instance is provided, it will be converted to a selection
  * containing one range collapsed at this position.
- * @returns {String} HTML-like string representing the model.
+ * @returns {String} An HTML-like string representing the model.
  */
 export function stringify( node, selectionOrPositionOrRange = null ) {
 	const model = new Model();
@@ -231,23 +231,23 @@ export function stringify( node, selectionOrPositionOrRange = null ) {
 }
 
 /**
- * Parses HTML-like string and returns model {@link module:engine/model/rootelement~RootElement rootElement}.
+ * Parses an HTML-like string and returns the model {@link module:engine/model/rootelement~RootElement rootElement}.
  *
- * **Note:** To create {@link module:engine/model/text~Text text} node witch containing attributes use:
+ * **Note:** To create a {@link module:engine/model/text~Text text} node that contains attributes use:
  *
  *		<$text attribute="value">Text data</$text>
  *
  * @param {String} data HTML-like string to be parsed.
- * @param {module:engine/model/schema~Schema} schema Schema instance uses by converters for element validation.
- * @param {module:engine/model/batch~Batch} batch Batch used for conversion.
+ * @param {module:engine/model/schema~Schema} schema A schema instance used by converters for element validation.
+ * @param {module:engine/model/batch~Batch} batch A batch used for conversion.
  * @param {Object} [options={}] Additional configuration.
- * @param {Array<Object>} [options.selectionAttributes] List of attributes which will be passed to the selection.
- * @param {Boolean} [options.lastRangeBackward=false] If set to true last range will be added as backward.
+ * @param {Array<Object>} [options.selectionAttributes] A list of attributes which will be passed to the selection.
+ * @param {Boolean} [options.lastRangeBackward=false] If set to `true`, the last range will be added as backward.
  * @param {module:engine/model/schema~SchemaContextDefinition} [options.context=[ '$root' ]] The conversion context.
- * If not provided default `[ '$root' ]` will be used.
+ * If not provided, the default `[ '$root' ]` will be used.
  * @returns {module:engine/model/element~Element|module:engine/model/text~Text|
- * module:engine/model/documentfragment~DocumentFragment|Object} Returns parsed model node or
- * object with two fields `model` and `selection` when selection ranges were included in data to parse.
+ * module:engine/model/documentfragment~DocumentFragment|Object} Returns the parsed model node or
+ * an object with two fields: `model` and `selection`, when selection ranges were included in the data to parse.
  */
 export function parse( data, schema, options = {} ) {
 	const mapper = new Mapper();

+ 173 - 168
packages/ckeditor5-engine/src/dev-utils/view.js

@@ -8,7 +8,7 @@
  */
 
 /**
- * Collection of methods for manipulating {@link module:engine/view/view view} for testing purposes.
+ * Collection of methods for manipulating the {@link module:engine/view/view view} for testing purposes.
  */
 
 import View from '../view/view';
@@ -35,17 +35,17 @@ const allowedTypes = {
 };
 
 /**
- * Writes the contents of the {@link module:engine/view/document~Document Document} to an HTML-like string.
+ * Writes the content of the {@link module:engine/view/document~Document document} to an HTML-like string.
  *
  * @param {module:engine/view/view~View} view
  * @param {Object} [options]
- * @param {Boolean} [options.withoutSelection=false] Whether to write the selection. When set to `true` selection will
- * be not included in returned string.
- * @param {Boolean} [options.rootName='main'] Name of the root from which data should be stringified. If not provided
- * default `main` name will be used.
- * @param {Boolean} [options.showType=false] When set to `true` type of elements will be printed (`<container:p>`
+ * @param {Boolean} [options.withoutSelection=false] Whether to write the selection. When set to `true`, the selection will
+ * not be included in the returned string.
+ * @param {Boolean} [options.rootName='main'] The name of the root from which the data should be stringified. If not provided,
+ * the default `main` name will be used.
+ * @param {Boolean} [options.showType=false] When set to `true`, the type of elements will be printed (`<container:p>`
  * instead of `<p>`, `<attribute:b>` instead of `<b>` and `<empty:img>` instead of `<img>`).
- * @param {Boolean} [options.showPriority=false] When set to `true` AttributeElement's priority will be printed
+ * @param {Boolean} [options.showPriority=false] When set to `true`, attribute element's priority will be printed
  * (`<span view-priority="12">`, `<b view-priority="10">`).
  * @returns {String} The stringified data.
  */
@@ -73,13 +73,13 @@ export function getData( view, options = {} ) {
 getData._stringify = stringify;
 
 /**
- * Sets the contents of the {@link module:engine/view/document~Document Document} provided as HTML-like string.
+ * Sets the content of the {@link module:engine/view/document~Document document} provided as an HTML-like string.
  *
  * @param {module:engine/view/view~View} view
- * @param {String} data HTML-like string to write into Document.
+ * @param {String} data An HTML-like string to write into the document.
  * @param {Object} options
- * @param {String} [options.rootName='main'] Root name where parsed data will be stored. If not provided,
- * default `main` name will be used.
+ * @param {String} [options.rootName='main'] The root name where parsed data will be stored. If not provided,
+ * the default `main` name will be used.
  */
 export function setData( view, data, options = {} ) {
 	if ( !( view instanceof View ) ) {
@@ -104,17 +104,17 @@ setData._parse = parse;
 
 /**
  * Converts view elements to HTML-like string representation.
- * Root element can be provided as {@link module:engine/view/text~Text Text}:
+ * A root element can be provided as {@link module:engine/view/text~Text text}:
  *
  *		const text = new Text( 'foobar' );
  *		stringify( text ); // 'foobar'
  *
- * or as {@link module:engine/view/element~Element Element}:
+ * or as an {@link module:engine/view/element~Element element}:
  *
  *		const element = new Element( 'p', null, new Text( 'foobar' ) );
  *		stringify( element ); // '<p>foobar</p>'
  *
- * or as {@link module:engine/view/documentfragment~DocumentFragment DocumentFragment}:
+ * or as a {@link module:engine/view/documentfragment~DocumentFragment document fragment}:
  *
  *		const text = new Text( 'foobar' );
  *		const b = new Element( 'b', { name: 'test' }, text );
@@ -123,9 +123,9 @@ setData._parse = parse;
  *
  *		stringify( fragment ); // '<p style="color:red;"></p><b name="test">foobar</b>'
  *
- * Additionally {@link module:engine/view/selection~Selection Selection} instance can be provided, then ranges from that selection
- * will be included in output data.
- * If range position is placed inside element node, it will be represented with `[` and `]`:
+ * Additionally, a {@link module:engine/view/selection~Selection selection} instance can be provided. Ranges from the selection
+ * will then be included in output data.
+ * If a range position is placed inside the element node, it will be represented with `[` and `]`:
  *
  *		const text = new Text( 'foobar' );
  *		const b = new Element( 'b', null, text );
@@ -136,7 +136,7 @@ setData._parse = parse;
  *
  *		stringify( p, selection ); // '<p>[<b>foobar</b>]</p>'
  *
- * If range is placed inside text node, it will be represented with `{` and `}`:
+ * If a range is placed inside the text node, it will be represented with `{` and `}`:
  *
  *		const text = new Text( 'foobar' );
  *		const b = new Element( 'b', null, text );
@@ -147,7 +147,8 @@ setData._parse = parse;
  *
  * ** Note: **
  * It is possible to unify selection markers to `[` and `]` for both (inside and outside text)
- * by setting `sameSelectionCharacters=true` option. It is mainly used when view stringify option is used by model utils.
+ * by setting the `sameSelectionCharacters=true` option. It is mainly used when the view stringify option is used by
+ * model utilities.
  *
  * Multiple ranges are supported:
  *
@@ -159,9 +160,9 @@ setData._parse = parse;
  *
  *		stringify( text, selection ); // '{f}oo{ba}r'
  *
- * Instead of {@link module:engine/view/selection~Selection Selection} instance {@link module:engine/view/range~Range Range} or
- * {@link module:engine/view/position~Position Position} instance can be provided. If Range instance is provided - it will be
- * converted to selection containing this range. If Position instance is provided - it will be converted to selection
+ * A {@link module:engine/view/range~Range range} or {@link module:engine/view/position~Position position} instance can be provided
+ * instead of the {@link module:engine/view/selection~Selection selection} instance. If a range instance is provided, it will be
+ * converted to a selection containing this range. If a position instance is provided, it will be converted to a selection
  * containing one range collapsed at this position.
  *
  *		const text = new Text( 'foobar' );
@@ -171,12 +172,12 @@ setData._parse = parse;
  *		stringify( text, range ); // '{f}oobar'
  *		stringify( text, position ); // 'foo{}bar'
  *
- * Additional options object can be provided.
+ * An additional `options` object can be provided.
  * If `options.showType` is set to `true`, element's types will be
- * presented for {@link module:engine/view/attributeelement~AttributeElement AttributeElements},
- * {@link module:engine/view/containerelement~ContainerElement ContainerElements}
- * {@link module:engine/view/emptyelement~EmptyElement EmptyElements}
- * and {@link module:engine/view/uielement~UIElement UIElements}:
+ * presented for {@link module:engine/view/attributeelement~AttributeElement attribute elements},
+ * {@link module:engine/view/containerelement~ContainerElement container elements}
+ * {@link module:engine/view/emptyelement~EmptyElement empty elements}
+ * and {@link module:engine/view/uielement~UIElement UI elements}:
  *
  *		const attribute = new AttributeElement( 'b' );
  *		const container = new ContainerElement( 'p' );
@@ -187,30 +188,30 @@ setData._parse = parse;
  *		getData( empty, null, { showType: true } ); // '<empty:img></empty:img>'
  *		getData( ui, null, { showType: true } ); // '<ui:span></ui:span>'
  *
- * If `options.showPriority` is set to `true`, priority will be displayed for all
- * {@link module:engine/view/attributeelement~AttributeElement AttributeElements}.
+ * If `options.showPriority` is set to `true`, a priority will be displayed for all
+ * {@link module:engine/view/attributeelement~AttributeElement attribute elements}.
  *
  *		const attribute = new AttributeElement( 'b' );
  *		attribute.priority = 20;
  *		getData( attribute, null, { showPriority: true } ); // <b view-priority="20"></b>
  *
  * @param {module:engine/view/text~Text|module:engine/view/element~Element|module:engine/view/documentfragment~DocumentFragment}
- * node Node to stringify.
+ * node The node to stringify.
  * @param {module:engine/view/selection~Selection|module:engine/view/position~Position|module:engine/view/range~Range}
  * [selectionOrPositionOrRange = null ]
- * Selection instance which ranges will be included in returned string data. If Range instance is provided - it will be
- * converted to selection containing this range. If Position instance is provided - it will be converted to selection
+ * A selection instance whose ranges will be included in the returned string data. If a range instance is provided, it will be
+ * converted to a selection containing this range. If a position instance is provided, it will be converted to a selection
  * containing one range collapsed at this position.
- * @param {Object} [options] Object with additional options.
- * @param {Boolean} [options.showType=false] When set to `true` type of elements will be printed (`<container:p>`
+ * @param {Object} [options] An object with additional options.
+ * @param {Boolean} [options.showType=false] When set to `true`, the type of elements will be printed (`<container:p>`
  * instead of `<p>`, `<attribute:b>` instead of `<b>` and `<empty:img>` instead of `<img>`).
- * @param {Boolean} [options.showPriority=false] When set to `true` AttributeElement's priority will be printed
+ * @param {Boolean} [options.showPriority=false] When set to `true`,  the attribute element's priority will be printed
  * (`<span view-priority="12">`, `<b view-priority="10">`).
- * @param {Boolean} [options.ignoreRoot=false] When set to `true` root's element opening and closing will not be printed.
- * Mainly used by `getData` function to ignore {@link module:engine/view/document~Document Document's} root element.
- * @param {Boolean} [options.sameSelectionCharacters=false] When set to `true` then selection inside text will be marked as `{` and `}`
- * and selection outside text as `[` and `]`. When set to `false` then both will be marked as `[` and `]` only.
- * @returns {String} HTML-like string representing the view.
+ * @param {Boolean} [options.ignoreRoot=false] When set to `true`, the root's element opening and closing will not be printed.
+ * Mainly used by the `getData` function to ignore the {@link module:engine/view/document~Document document's} root element.
+ * @param {Boolean} [options.sameSelectionCharacters=false] When set to `true`, the selection inside the text will be marked as
+ *  `{` and `}` and the selection outside the text as `[` and `]`. When set to `false`, both will be marked as `[` and `]` only.
+ * @returns {String} An HTML-like string representing the view.
  */
 export function stringify( node, selectionOrPositionOrRange = null, options = {} ) {
 	let selection;
@@ -230,23 +231,23 @@ export function stringify( node, selectionOrPositionOrRange = null, options = {}
 }
 
 /**
- * Parses HTML-like string and returns view tree nodes.
- * Simple string will be converted to {@link module:engine/view/text~Text Text} node:
+ * Parses an HTML-like string and returns view tree nodes.
+ * A simple string will be converted to a {@link module:engine/view/text~Text text} node:
  *
- *		parse( 'foobar' ); // Returns instance of Text.
+ *		parse( 'foobar' ); // Returns an instance of text.
  *
- * {@link module:engine/view/element~Element Elements} will be parsed with attributes an children:
+ * {@link module:engine/view/element~Element Elements} will be parsed with attributes as children:
  *
- *		parse( '<b name="baz">foobar</b>' ); // Returns instance of Element with `baz` attribute and text child node.
+ *		parse( '<b name="baz">foobar</b>' ); // Returns an instance of element with the `baz` attribute and a text child node.
  *
- * Multiple nodes provided on root level will be converted to
- * {@link module:engine/view/documentfragment~DocumentFragment DocumentFragment}:
+ * Multiple nodes provided on root level will be converted to a
+ * {@link module:engine/view/documentfragment~DocumentFragment document fragment}:
  *
- *		parse( '<b>foo</b><i>bar</i>' ); // Returns DocumentFragment with two child elements.
+ *		parse( '<b>foo</b><i>bar</i>' ); // Returns a document fragment with two child elements.
  *
- * Method can parse multiple {@link module:engine/view/range~Range ranges} provided in string data and return
- * {@link module:engine/view/selection~Selection Selection} instance containing these ranges. Ranges placed inside
- * {@link module:engine/view/text~Text Text} nodes should be marked using `{` and `}` brackets:
+ * The method can parse multiple {@link module:engine/view/range~Range ranges} provided in string data and return a
+ * {@link module:engine/view/selection~Selection selection} instance containing these ranges. Ranges placed inside
+ * {@link module:engine/view/text~Text text} nodes should be marked using `{` and `}` brackets:
  *
  *		const { text, selection } = parse( 'f{ooba}r' );
  *
@@ -256,49 +257,51 @@ export function stringify( node, selectionOrPositionOrRange = null, options = {}
  *
  * ** Note: **
  * It is possible to unify selection markers to `[` and `]` for both (inside and outside text)
- * by setting `sameSelectionCharacters=true` option. It is mainly used when view parse option is used by model utils.
+ * by setting `sameSelectionCharacters=true` option. It is mainly used when the view parse option is used by model utilities.
  *
- * Sometimes there is a need for defining order of ranges inside created selection. This can be achieved by providing
- * ranges order array as additional parameter:
+ * Sometimes there is a need for defining the order of ranges inside the created selection. This can be achieved by providing
+ * the range order array as an additional parameter:
  *
  *		const { root, selection } = parse( '{fo}ob{ar}{ba}z', { order: [ 2, 3, 1 ] } );
  *
- * In above example first range (`{fo}`) will be added to selection as second one, second range (`{ar}`) will be added
- * as third and third range (`{ba}`) will be added as first one.
+ * In the example above, the first range (`{fo}`) will be added to the selection as the second one, the second range (`{ar}`) will be
+ * added as the third and the third range (`{ba}`) will be added as the first one.
  *
- * If selection's last range should be added as backward one (so the {@link module:engine/view/selection~Selection#anchor selection
- * anchor} is represented by `end` position and {@link module:engine/view/selection~Selection#focus selection focus} is
- * represented by `start` position) use `lastRangeBackward` flag:
+ * If the selection's last range should be added as a backward one (so the {@link module:engine/view/selection~Selection#anchor selection
+ * anchor} is represented by the `end` position and {@link module:engine/view/selection~Selection#focus selection focus} is
+ * represented by the `start` position), use the `lastRangeBackward` flag:
  *
  *		const { root, selection } = parse( `{foo}bar{baz}`, { lastRangeBackward: true } );
  *
- * Other examples and edge cases:
+ * Some more examples and edge cases:
  *
- *		// Returns empty DocumentFragment.
+ *		// Returns an empty document fragment.
  *		parse( '' );
  *
- *		// Returns empty DocumentFragment and collapsed selection.
+ *		// Returns an empty document fragment and a collapsed selection.
  *		const { root, selection } = parse( '[]' );
  *
- *		// Returns Element and selection that is placed inside of DocumentFragment containing that element.
+ *		// Returns an element and a selection that is placed inside the document fragment containing that element.
  *		const { root, selection } = parse( '[<a></a>]' );
  *
- * @param {String} data HTML-like string to be parsed.
+ * @param {String} data An HTML-like string to be parsed.
  * @param {Object} options
- * @param {Array.<Number>} [options.order] Array with order of parsed ranges added to returned
- * {@link module:engine/view/selection~Selection Selection} instance. Each element should represent desired position of each range in
- * selection instance. For example: `[2, 3, 1]` means that first range will be placed as second, second as third and third as first.
- * @param {Boolean} [options.lastRangeBackward=false] If set to true last range will be added as backward to the returned
- * {@link module:engine/view/selection~Selection Selection} instance.
+ * @param {Array.<Number>} [options.order] An array with the order of parsed ranges added to the returned
+ * {@link module:engine/view/selection~Selection Selection} instance. Each element should represent the desired position of each range in
+ * the selection instance. For example: `[2, 3, 1]` means that the first range will be placed as the second, the second as the third and
+ * the third as the first.
+ * @param {Boolean} [options.lastRangeBackward=false] If set to `true`, the last range will be added as backward to the returned
+ * {@link module:engine/view/selection~Selection selection} instance.
  * @param {module:engine/view/element~Element|module:engine/view/documentfragment~DocumentFragment}
- * [options.rootElement=null] Default root to use when parsing elements.
- * When set to `null` root element will be created automatically. If set to
- * {@link module:engine/view/element~Element Element} or {@link module:engine/view/documentfragment~DocumentFragment DocumentFragment}
- * - this node will be used as root for all parsed nodes.
- * @param {Boolean} [options.sameSelectionCharacters=false] When set to `false` then selection inside text should be marked using
- * `{` and `}` and selection outside text using `[` and `]`. When set to `true` then both should be marked with `[` and `]` only.
+ * [options.rootElement=null] The default root to use when parsing elements.
+ * When set to `null`, the root element will be created automatically. If set to
+ * {@link module:engine/view/element~Element Element} or {@link module:engine/view/documentfragment~DocumentFragment DocumentFragment},
+ * this node will be used as the root for all parsed nodes.
+ * @param {Boolean} [options.sameSelectionCharacters=false] When set to `false`, the selection inside the text should be marked using
+ * `{` and `}` and the selection outside the ext using `[` and `]`. When set to `true`, both should be marked with `[` and `]` only.
  * @returns {module:engine/view/text~Text|module:engine/view/element~Element|module:engine/view/documentfragment~DocumentFragment|Object}
- * Returns parsed view node or object with two fields `view` and `selection` when selection ranges were included in data to parse.
+ * Returns the parsed view node or an object with two fields: `view` and `selection` when selection ranges were included in the data
+ * to parse.
  */
 export function parse( data, options = {} ) {
 	options.order = options.order || [];
@@ -354,31 +357,32 @@ export function parse( data, options = {} ) {
 }
 
 /**
- * Private helper class used for converting ranges represented as text inside view {@link module:engine/view/text~Text Text nodes}.
+ * Private helper class used for converting ranges represented as text inside view {@link module:engine/view/text~Text text nodes}.
  *
  * @private
  */
 class RangeParser {
 	/**
-	 * Create RangeParser instance.
+	 * Creates a range parser instance.
 	 *
-	 * @param {Object} options RangeParser configuration.
-	 * @param {Boolean} [options.sameSelectionCharacters=false] When set to `true` it means that selection inside text is marked as
-	 * `{` and `}` and selection outside text as `[` and `]`. When set to `false` then both are marked as `[` and `]`.
+	 * @param {Object} options The range parser configuration.
+	 * @param {Boolean} [options.sameSelectionCharacters=false] When set to `true`, the selection inside the text is marked as
+	 * `{` and `}` and the selection outside the text as `[` and `]`. When set to `false`, both are marked as `[` and `]`.
 	 */
 	constructor( options ) {
 		this.sameSelectionCharacters = !!options.sameSelectionCharacters;
 	}
 
 	/**
-	 * Parses the view, and returns ranges represented inside {@link module:engine/view/text~Text Text nodes}.
-	 * Method will remove all occurrences of `{`, `}`, `[` and `]` from found text nodes. If text node is empty after
-	 * the process - it will be removed too.
+	 * Parses the view and returns ranges represented inside {@link module:engine/view/text~Text text nodes}.
+	 * The method will remove all occurrences of `{`, `}`, `[` and `]` from found text nodes. If a text node is empty after
+	 * the process, it will be removed, too.
 	 *
-	 * @param {module:engine/view/node~Node} node Starting node.
-	 * @param {Array.<Number>} order Ranges order. Each element should represent desired position of the range after
-	 * sorting. For example: `[2, 3, 1]` means that first range will be placed as second, second as third and third as first.
-	 * @returns {Array.<module:engine/view/range~Range>} Array with ranges found.
+	 * @param {module:engine/view/node~Node} node The starting node.
+	 * @param {Array.<Number>} order The order of ranges. Each element should represent the desired position of the range after
+	 * sorting. For example: `[2, 3, 1]` means that the first range will be placed as the second, the second as the third and the third
+	 * as the first.
+	 * @returns {Array.<module:engine/view/range~Range>} An array with ranges found.
 	 */
 	parse( node, order ) {
 		this._positions = [];
@@ -404,9 +408,8 @@ class RangeParser {
 	}
 
 	/**
-	 * Gathers positions of brackets inside view tree starting from provided node. Method will remove all occurrences of
-	 * `{`, `}`, `[` and `]` from found text nodes. If text node is empty after the process - it will be removed
-	 * too.
+	 * Gathers positions of brackets inside the view tree starting from the provided node. The method will remove all occurrences of
+	 * `{`, `}`, `[` and `]` from found text nodes. If a text node is empty after the process, it will be removed, too.
 	 *
 	 * @private
 	 * @param {module:engine/view/node~Node} node Staring node.
@@ -504,13 +507,14 @@ class RangeParser {
 	}
 
 	/**
-	 * Sort ranges in given order. Ranges order should be an array, each element should represent desired position
+	 * Sorts ranges in a given order. Range order should be an array and each element should represent the desired position
 	 * of the range after sorting.
-	 * For example: `[2, 3, 1]` means that first range will be placed as second, second as third and third as first.
+	 * For example: `[2, 3, 1]` means that the first range will be placed as the second, the second as the third and the third
+	 * as the first.
 	 *
 	 * @private
 	 * @param {Array.<module:engine/view/range~Range>} ranges Ranges to sort.
-	 * @param {Array.<Number>} rangesOrder Array with new ranges order.
+	 * @param {Array.<Number>} rangesOrder An array with new range order.
 	 * @returns {Array} Sorted ranges array.
 	 */
 	_sortRanges( ranges, rangesOrder ) {
@@ -570,24 +574,24 @@ class RangeParser {
 }
 
 /**
- * Private helper class used for converting view tree to string.
+ * Private helper class used for converting the view tree to a string.
  *
  * @private
  */
 class ViewStringify {
 	/**
-	 * Creates ViewStringify instance.
+	 * Creates a view stringify instance.
 	 *
 	 * @param root
-	 * @param {module:engine/view/selection~Selection} selection Selection which ranges should be also converted to string.
-	 * @param {Object} options Options object.
-	 * @param {Boolean} [options.showType=false] When set to `true` type of elements will be printed (`<container:p>`
+	 * @param {module:engine/view/selection~Selection} selection A selection whose ranges should also be converted to a string.
+	 * @param {Object} options An options object.
+	 * @param {Boolean} [options.showType=false] When set to `true`, the type of elements will be printed (`<container:p>`
 	 * instead of `<p>`, `<attribute:b>` instead of `<b>` and `<empty:img>` instead of `<img>`).
-	 * @param {Boolean} [options.showPriority=false] When set to `true` AttributeElement's priority will be printed.
-	 * @param {Boolean} [options.ignoreRoot=false] When set to `true` root's element opening and closing tag will not
+	 * @param {Boolean} [options.showPriority=false] When set to `true`, the attribute element's priority will be printed.
+	 * @param {Boolean} [options.ignoreRoot=false] When set to `true`, the root's element opening and closing tag will not
 	 * be outputted.
-	 * @param {Boolean} [options.sameSelectionCharacters=false] When set to `true` it means that selection inside text is marked as
-	 * `{` and `}` and selection outside text as `[` and `]`. When set to `false` then both are marked as `[` and `]`.
+	 * @param {Boolean} [options.sameSelectionCharacters=false] When set to `true`, the selection inside the text is marked as
+	 * `{` and `}` and the selection outside the text as `[` and `]`. When set to `false`, both are marked as `[` and `]`.
 	 */
 	constructor( root, selection, options ) {
 		this.root = root;
@@ -605,7 +609,7 @@ class ViewStringify {
 	}
 
 	/**
-	 * Converts view to string.
+	 * Converts the view to a string.
 	 *
 	 * @returns {String} String representation of the view elements.
 	 */
@@ -619,8 +623,8 @@ class ViewStringify {
 	}
 
 	/**
-	 * Executes simple walker that iterates over all elements in the view tree starting from root element.
-	 * Calls `callback` with parsed chunks of string data.
+	 * Executes a simple walker that iterates over all elements in the view tree starting from the root element.
+	 * Calls the `callback` with parsed chunks of string data.
 	 *
 	 * @private
 	 * @param {module:engine/view/documentfragment~DocumentFragment|module:engine/view/element~Element|module:engine/view/text~Text} root
@@ -654,8 +658,8 @@ class ViewStringify {
 	}
 
 	/**
-	 * Checks if given {@link module:engine/view/element~Element Element} has {@link module:engine/view/range~Range#start range start} or
-	 * {@link module:engine/view/range~Range#start range end} placed at given offset and returns its string representation.
+	 * Checks if a given {@link module:engine/view/element~Element element} has a {@link module:engine/view/range~Range#start range start}
+	 * or a {@link module:engine/view/range~Range#start range end} placed at a given offset and returns its string representation.
 	 *
 	 * @private
 	 * @param {module:engine/view/element~Element} element
@@ -684,8 +688,9 @@ class ViewStringify {
 	}
 
 	/**
-	 * Checks if given {@link module:engine/view/element~Element Text node} has {@link module:engine/view/range~Range#start range start} or
-	 * {@link module:engine/view/range~Range#start range end} placed somewhere inside. Returns string representation of text
+	 * Checks if a given {@link module:engine/view/element~Element Text node} has a
+	 * {@link module:engine/view/range~Range#start range start} or a
+	 * {@link module:engine/view/range~Range#start range end} placed somewhere inside. Returns a string representation of text
 	 * with range delimiters placed inside.
 	 *
 	 * @private
@@ -738,10 +743,10 @@ class ViewStringify {
 	}
 
 	/**
-	 * Converts passed {@link module:engine/view/element~Element Element} to opening tag.
-	 * Depending on current configuration opening tag can be simple (`<a>`), contain type prefix (`<container:p>`,
-	 * `<attribute:a>` or `<empty:img>`), contain priority information ( `<attribute:a view-priority="20">` ).
-	 * Element's attributes also will be included (`<a href="http://ckeditor.com" name="foobar">`).
+	 * Converts the passed {@link module:engine/view/element~Element element} to an opening tag.
+	 * Depending on the current configuration, the opening tag can be simple (`<a>`), contain a type prefix (`<container:p>`,
+	 * `<attribute:a>` or `<empty:img>`) or contain priority information ( `<attribute:a view-priority="20">` ).
+	 * Element attributes will also be included (`<a href="https://ckeditor.com" name="foobar">`).
 	 *
 	 * @private
 	 * @param {module:engine/view/element~Element} element
@@ -759,8 +764,8 @@ class ViewStringify {
 	}
 
 	/**
-	 * Converts passed {@link module:engine/view/element~Element Element} to closing tag.
-	 * Depending on current configuration closing tag can be simple (`</a>`) or contain type prefix (`</container:p>`,
+	 * Converts the passed {@link module:engine/view/element~Element element} to a closing tag.
+	 * Depending on the current configuration, the closing tag can be simple (`</a>`) or contain a type prefix (`</container:p>`,
 	 * `</attribute:a>` or `</empty:img>`).
 	 *
 	 * @private
@@ -775,14 +780,14 @@ class ViewStringify {
 	}
 
 	/**
-	 * Converts passed {@link module:engine/view/element~Element Element's} type to its string representation
+	 * Converts the passed {@link module:engine/view/element~Element element's} type to its string representation
 	 *
 	 * Returns:
-	 * * 'attribute' for {@link module:engine/view/attributeelement~AttributeElement AttributeElements},
-	 * * 'container' for {@link module:engine/view/containerelement~ContainerElement ContainerElements},
-	 * * 'empty' for {@link module:engine/view/emptyelement~EmptyElement EmptyElements}.
-	 * * 'ui' for {@link module:engine/view/uielement~UIElement UIElements}.
-	 * * empty string when current configuration is preventing showing elements' types.
+	 * * 'attribute' for {@link module:engine/view/attributeelement~AttributeElement attribute elements},
+	 * * 'container' for {@link module:engine/view/containerelement~ContainerElement container elements},
+	 * * 'empty' for {@link module:engine/view/emptyelement~EmptyElement empty elements}.
+	 * * 'ui' for {@link module:engine/view/uielement~UIElement UI elements}.
+	 * * an empty string when the current configuration is preventing showing elements' types.
 	 *
 	 * @private
 	 * @param {module:engine/view/element~Element} element
@@ -801,10 +806,10 @@ class ViewStringify {
 	}
 
 	/**
-	 * Converts passed {@link module:engine/view/element~Element Element} to its priority representation.
-	 * Priority string representation will be returned when passed element is an instance of
-	 * {@link module:engine/view/attributeelement~AttributeElement AttributeElement} and current configuration allow to show priority.
-	 * Otherwise returns empty string.
+	 * Converts the passed {@link module:engine/view/element~Element element} to its priority representation.
+	 * The priority string representation will be returned when the passed element is an instance of
+	 * {@link module:engine/view/attributeelement~AttributeElement attribute element} and the current configuration allows to show the
+	 * priority. Otherwise returns an empty string.
 	 *
 	 * @private
 	 * @param {module:engine/view/element~Element} element
@@ -819,8 +824,8 @@ class ViewStringify {
 	}
 
 	/**
-	 * Converts passed {@link module:engine/view/element~Element Element} attributes to their string representation.
-	 * If element has no attributes - empty string is returned.
+	 * Converts the passed {@link module:engine/view/element~Element element} attributes to their string representation.
+	 * If an element has no attributes, an empty string is returned.
 	 *
 	 * @private
 	 * @param {module:engine/view/element~Element} element
@@ -853,18 +858,18 @@ class ViewStringify {
 	}
 }
 
-// Converts {@link module:engine/view/element~Element Elements} to
-// {@link module:engine/view/attributeelement~AttributeElement AttributeElements},
-// {@link module:engine/view/containerelement~ContainerElement ContainerElements},
-// {@link module:engine/view/emptyelement~EmptyElement EmptyElements} or
-// {@link module:engine/view/uielement~UIElement UIElements}.
-// It converts whole tree starting from the `rootNode`. Conversion is based on element names.
-// See `_convertElement` method for more details.
+// Converts {@link module:engine/view/element~Element elements} to
+// {@link module:engine/view/attributeelement~AttributeElement attribute elements},
+// {@link module:engine/view/containerelement~ContainerElement container elements},
+// {@link module:engine/view/emptyelement~EmptyElement empty elements} or
+// {@link module:engine/view/uielement~UIElement UI elements}.
+// It converts the whole tree starting from the `rootNode`. The conversion is based on element names.
+// See the `_convertElement` method for more details.
 //
 // @param {module:engine/view/element~Element|module:engine/view/documentfragment~DocumentFragment|module:engine/view/text~Text}
-//  rootNode Root node to convert.
+//  rootNode The root node to convert.
 // @returns {module:engine/view/element~Element|module:engine/view/documentfragment~DocumentFragment|
-// module:engine/view/text~Text} Root node of converted elements.
+// module:engine/view/text~Text} The root node of converted elements.
 function _convertViewElements( rootNode ) {
 	if ( rootNode.is( 'element' ) || rootNode.is( 'documentFragment' ) ) {
 		// Convert element or leave document fragment.
@@ -891,27 +896,27 @@ function _convertViewElements( rootNode ) {
 	return rootNode;
 }
 
-// Converts {@link module:engine/view/element~Element Element} to
-// {@link module:engine/view/attributeelement~AttributeElement AttributeElement},
-// {@link module:engine/view/containerelement~ContainerElement ContainerElement},
-// {@link module:engine/view/emptyelement~EmptyElement EmptyElement} or
-// {@link module:engine/view/uielement~UIElement UIElement}.
-// If element's name is in format `attribute:b` with `view-priority="11"` attribute it will be converted to
-// {@link module:engine/view/attributeelement~AttributeElement AttributeElement} with priority 11.
-// If element's name is in format `container:p` - it will be converted to
-// {@link module:engine/view/containerelement~ContainerElement ContainerElement}.
-// If element's name is in format `empty:img` - it will be converted to
-// {@link module:engine/view/emptyelement~EmptyElement EmptyElement}.
-// If element's name is in format `ui:span` - it will be converted to
-// {@link module:engine/view/uielement~UIElement UIElement}.
-// If element's name will not contain any additional information - {@link module:engine/view/element~Element view Element} will be
+// Converts an {@link module:engine/view/element~Element element} to
+// {@link module:engine/view/attributeelement~AttributeElement attribute element},
+// {@link module:engine/view/containerelement~ContainerElement container element},
+// {@link module:engine/view/emptyelement~EmptyElement empty element} or
+// {@link module:engine/view/uielement~UIElement UI element}.
+// If the element's name is in the format of `attribute:b` with `view-priority="11"` attribute, it will be converted to
+// an {@link module:engine/view/attributeelement~AttributeElement attribute element} with a priority of 11.
+// If the element's name is in the format of `container:p`, it will be converted to
+// a {@link module:engine/view/containerelement~ContainerElement container element}.
+// If the element's name is in the format of `empty:img`, it will be converted to
+// an {@link module:engine/view/emptyelement~EmptyElement empty element}.
+// If the element's name is in the format of `ui:span`, it will be converted to
+// a {@link module:engine/view/uielement~UIElement UI element}.
+// If the element's name does not contain any additional information, a {@link module:engine/view/element~Element view Element} will be
 // returned.
 //
-// @param {module:engine/view/element~Element} viewElement View element to convert.
+// @param {module:engine/view/element~Element} viewElement A view element to convert.
 // @returns {module:engine/view/element~Element|module:engine/view/attributeelement~AttributeElement|
 // module:engine/view/emptyelement~EmptyElement|module:engine/view/uielement~UIElement|
-// module:engine/view/containerelement~ContainerElement} Tree view
-// element converted according to it's name.
+// module:engine/view/containerelement~ContainerElement} A tree view
+// element converted according to its name.
 function _convertElement( viewElement ) {
 	const info = _convertElementNameAndPriority( viewElement );
 	const ElementConstructor = allowedTypes[ info.type ];
@@ -931,19 +936,19 @@ function _convertElement( viewElement ) {
 	return newElement;
 }
 
-// Converts `view-priority` attribute and {@link module:engine/view/element~Element#name Element's name} information needed for creating
-// {@link module:engine/view/attributeelement~AttributeElement AttributeElement},
-// {@link module:engine/view/containerelement~ContainerElement ContainerElement},
-// {@link module:engine/view/emptyelement~EmptyElement EmptyElement} or,
-// {@link module:engine/view/uielement~UIElement UIElement}.
-// Name can be provided in two formats: as a simple element's name (`div`), or as a type and name (`container:div`,
+// Converts the `view-priority` attribute and the {@link module:engine/view/element~Element#name element's name} information needed for
+// creating {@link module:engine/view/attributeelement~AttributeElement attribute element},
+// {@link module:engine/view/containerelement~ContainerElement container element},
+// {@link module:engine/view/emptyelement~EmptyElement empty element} or
+// {@link module:engine/view/uielement~UIElement UI element}.
+// The name can be provided in two formats: as a simple element's name (`div`), or as a type and name (`container:div`,
 // `attribute:span`, `empty:img`, `ui:span`);
 //
-// @param {module:engine/view/element~Element} element Element which name should be converted.
-// @returns {Object} info Object with parsed information.
-// @returns {String} info.name Parsed name of the element.
-// @returns {String|null} info.type Parsed type of the element, can be `attribute`, `container` or `empty`.
-// returns {Number|null} info.priority Parsed priority of the element.
+// @param {module:engine/view/element~Element} element The element whose name should be converted.
+// @returns {Object} info An object with parsed information.
+// @returns {String} info.name The parsed name of the element.
+// @returns {String|null} info.type The parsed type of the element. It can be `attribute`, `container` or `empty`.
+// returns {Number|null} info.priority The parsed priority of the element.
 function _convertElementNameAndPriority( viewElement ) {
 	const parts = viewElement.name.split( ':' );
 	const priority = _convertPriority( viewElement.getAttribute( 'view-priority' ) );
@@ -971,7 +976,7 @@ function _convertElementNameAndPriority( viewElement ) {
 	throw new Error( `Parse error - cannot parse element's name: ${ viewElement.name }.` );
 }
 
-// Checks if element's type is allowed. Returns `attribute`, `container`, `empty` or `null`.
+// Checks if the element's type is allowed. Returns `attribute`, `container`, `empty` or `null`.
 //
 // @param {String} type
 // @returns {String|null}
@@ -979,7 +984,7 @@ function _convertType( type ) {
 	return allowedTypes[ type ] ? type : null;
 }
 
-// Checks if given priority is allowed. Returns null if priority cannot be converted.
+// Checks if a given priority is allowed. Returns null if the priority cannot be converted.
 //
 // @param {String} priorityString
 // returns {Number|Null}

+ 15 - 14
packages/ckeditor5-engine/src/model/batch.js

@@ -8,8 +8,8 @@
  */
 
 /**
- * `Batch` instance groups model changes ({@link module:engine/model/delta/delta~Delta deltas}). All deltas grouped in a single `Batch`
- * can be reverted together, so you can think about `Batch` as of a single undo step. If you want to extend given undo step you
+ * A batch instance groups model changes ({@link module:engine/model/delta/delta~Delta deltas}). All deltas grouped in a single batch
+ * can be reverted together, so you can think about a batch as of a single undo step. If you want to extend a given undo step, you
  * can add more changes to the batch using {@link module:engine/model/model~Model#enqueueChange}:
  *
  *		model.enqueueChange( batch, writer => {
@@ -21,15 +21,15 @@
  */
 export default class Batch {
 	/**
-	 * Creates `Batch` instance.
+	 * Creates a batch instance.
 	 *
 	 * @see module:engine/model/model~Model#enqueueChange
 	 * @see module:engine/model/model~Model#change
-	 * @param {'transparent'|'default'} [type='default'] Type of the batch.
+	 * @param {'transparent'|'default'} [type='default'] The type of the batch.
 	 */
 	constructor( type = 'default' ) {
 		/**
-		 * Array of deltas which compose this batch.
+		 * An array of deltas that compose this batch.
 		 *
 		 * @readonly
 		 * @type {Array.<module:engine/model/delta/delta~Delta>}
@@ -37,11 +37,12 @@ export default class Batch {
 		this.deltas = [];
 
 		/**
-		 * Type of the batch.
+		 * The type of the batch.
 		 *
-		 * Can be one of the following values:
-		 * * `'default'` - all "normal" batches, most commonly used type.
-		 * * `'transparent'` - batch that should be ignored by other features, i.e. initial batch or collaborative editing changes.
+		 * It can be one of the following values:
+		 * * `'default'` &ndash; All "normal" batches. This is the most commonly used type.
+		 * * `'transparent'` &ndash; A batch that should be ignored by other features, i.e. an initial batch or collaborative editing
+		 * changes.
 		 *
 		 * @readonly
 		 * @type {'transparent'|'default'}
@@ -50,8 +51,8 @@ export default class Batch {
 	}
 
 	/**
-	 * Returns this batch base version, which is equal to the base version of first delta (which has base version set)
-	 * in the batch. If there are no deltas in the batch or neither delta has base version set, it returns `null`.
+	 * Returns the base version of this batch, which is equal to the base version of the first delta (which has the base version set)
+	 * in the batch. If there are no deltas in the batch or neither delta has the base version set, it returns `null`.
 	 *
 	 * @readonly
 	 * @type {Number|null}
@@ -67,11 +68,11 @@ export default class Batch {
 	}
 
 	/**
-	 * Adds delta to the batch instance. All modification methods (insert, remove, split, etc.) use this method
+	 * Adds a delta to the batch instance. All modification methods (insert, remove, split, etc.) use this method
 	 * to add created deltas.
 	 *
-	 * @param {module:engine/model/delta/delta~Delta} delta Delta to add.
-	 * @return {module:engine/model/delta/delta~Delta} Added delta.
+	 * @param {module:engine/model/delta/delta~Delta} delta A delta to add.
+	 * @return {module:engine/model/delta/delta~Delta} An added delta.
 	 */
 	addDelta( delta ) {
 		delta.batch = this;

+ 51 - 50
packages/ckeditor5-engine/src/model/differ.js

@@ -11,17 +11,17 @@ import Position from './position';
 import Range from './range';
 
 /**
- * Calculates difference between two model states.
+ * Calculates the difference between two model states.
  *
  * Receives operations that are to be applied on the model document. Marks parts of the model document tree which
- * are changed and saves those elements state before the change. Then, it compares saved elements with the
+ * are changed and saves the state of these elements before the change. Then, it compares saved elements with the
  * changed elements, after all changes are applied on the model document. Calculates the diff between saved
- * elements and new ones and returns a changes set.
+ * elements and new ones and returns a change set.
  */
 export default class Differ {
 	constructor() {
 		/**
-		 * A map that stores changes that happened in given element.
+		 * A map that stores changes that happened in a given element.
 		 *
 		 * The keys of the map are references to the model elements.
 		 * The values of the map are arrays with changes that were done on this element.
@@ -32,9 +32,9 @@ export default class Differ {
 		this._changesInElement = new Map();
 
 		/**
-		 * A map that stores "element's children snapshots". A snapshot is representing children of given element before
+		 * A map that stores "element's children snapshots". A snapshot is representing children of a given element before
 		 * the first change was applied on that element. Snapshot items are objects with two properties: `name`,
-		 * containing element name (or `'$text'` for text node) and `attributes` which is a map of a node's attributes.
+		 * containing the element name (or `'$text'` for a text node) and `attributes` which is a map of the node's attributes.
 		 *
 		 * @private
 		 * @type {Map}
@@ -45,7 +45,7 @@ export default class Differ {
 		 * A map that stores all changed markers.
 		 *
 		 * The keys of the map are marker names.
-		 * The values of the map are objects with properties `oldRange` and `newRange`. Those holds the marker range
+		 * The values of the map are objects with the `oldRange` and `newRange` properties. They store the marker range
 		 * state before and after the change.
 		 *
 		 * @private
@@ -54,7 +54,7 @@ export default class Differ {
 		this._changedMarkers = new Map();
 
 		/**
-		 * Stores how many changes has been processed. Used to order changes chronologically. It is important
+		 * Stores the number of changes that were processed. Used to order the changes chronologically. It is important
 		 * when changes are sorted.
 		 *
 		 * @private
@@ -75,11 +75,11 @@ export default class Differ {
 		this._cachedChanges = null;
 
 		/**
-		 * For efficiency purposes, `Differ` stores the change set returned by the differ after {@link #getChanges} call.
-		 * Cache is reset each time a new operation is buffered. If the cache has not been reset, {@link #getChanges} will
+		 * For efficiency purposes, `Differ` stores the change set returned by the differ after the {@link #getChanges} call.
+		 * The cache is reset each time a new operation is buffered. If the cache has not been reset, {@link #getChanges} will
 		 * return the cached value instead of calculating it again.
 		 *
-		 * This property stores all changes evaluated by `Differ`, also those that took place in graveyard.
+		 * This property stores all changes evaluated by `Differ`, including those that took place in the graveyard.
 		 *
 		 * @private
 		 * @type {Array.<Object>|null}
@@ -98,12 +98,12 @@ export default class Differ {
 	}
 
 	/**
-	 * Buffers given operation. Operation has to be buffered before it is executed.
+	 * Buffers a given operation. An operation has to be buffered before it is executed.
 	 *
-	 * Operation type is checked and it is checked which nodes it will affect. Then those nodes are stored in `Differ`
+	 * Operation type is checked and it is checked which nodes it will affect. These nodes are then stored in `Differ`
 	 * in the state before the operation is executed.
 	 *
-	 * @param {module:engine/model/operation/operation~Operation} operation Operation to buffer.
+	 * @param {module:engine/model/operation/operation~Operation} operation An operation to buffer.
 	 */
 	bufferOperation( operation ) {
 		switch ( operation.type ) {
@@ -140,9 +140,10 @@ export default class Differ {
 	/**
 	 * Buffers marker change.
 	 *
-	 * @param {String} markerName Name of marker which changed.
-	 * @param {module:engine/model/range~Range|null} oldRange Marker range before the change or `null` if marker was just created.
-	 * @param {module:engine/model/range~Range|null} newRange Marker range after the change or `null` if marker was removed.
+	 * @param {String} markerName The name of the marker that changed.
+	 * @param {module:engine/model/range~Range|null} oldRange Marker range before the change or `null` if the marker has just
+	 * been created.
+	 * @param {module:engine/model/range~Range|null} newRange Marker range after the change or `null` if the marker was removed.
 	 */
 	bufferMarkerChange( markerName, oldRange, newRange ) {
 		const buffered = this._changedMarkers.get( markerName );
@@ -164,9 +165,9 @@ export default class Differ {
 	}
 
 	/**
-	 * Returns all markers which should be removed as a result of buffered changes.
+	 * Returns all markers that should be removed as a result of buffered changes.
 	 *
-	 * @returns {Array.<Object>} Markers to remove. Each array item is an object containing `name` and `range` property.
+	 * @returns {Array.<Object>} Markers to remove. Each array item is an object containing the `name` and `range` properties.
 	 */
 	getMarkersToRemove() {
 		const result = [];
@@ -183,7 +184,7 @@ export default class Differ {
 	/**
 	 * Returns all markers which should be added as a result of buffered changes.
 	 *
-	 * @returns {Array.<Object>} Markers to add. Each array item is an object containing `name` and `range` property.
+	 * @returns {Array.<Object>} Markers to add. Each array item is an object containing the `name` and `range` properties.
 	 */
 	getMarkersToAdd() {
 		const result = [];
@@ -198,20 +199,20 @@ export default class Differ {
 	}
 
 	/**
-	 * Calculates diff between old model tree state (state before the first buffered operations since the last {@link #reset} call)
-	 * and the new model tree state (actual one). Should be called after all buffered operations are executed.
+	 * Calculates the diff between the old model tree state (the state before the first buffered operations since the last {@link #reset}
+	 * call) and the new model tree state (actual one). It should be called after all buffered operations are executed.
 	 *
-	 * The diff set is returned as an array of diff items, each describing a change done on model. The items are sorted by
+	 * The diff set is returned as an array of diff items, each describing a change done on the model. The items are sorted by
 	 * the position on which the change happened. If a position {@link module:engine/model/position~Position#isBefore is before}
 	 * another one, it will be on an earlier index in the diff set.
 	 *
-	 * Because calculating diff is a costly operation, the result is cached. If no new operation was buffered since the
-	 * previous {@link #getChanges} call, the next call with return the cached value.
+	 * Because calculating the diff is a costly operation, the result is cached. If no new operation was buffered since the
+	 * previous {@link #getChanges} call, the next call will return the cached value.
 	 *
 	 * @param {Object} options Additional options.
 	 * @param {Boolean} [options.includeChangesInGraveyard=false] If set to `true`, also changes that happened
-	 * in graveyard root will be returned. By default, changes in graveyard root are not returned.
-	 * @returns {Array.<Object>} Diff between old and new model tree state.
+	 * in the graveyard root will be returned. By default, changes in the graveyard root are not returned.
+	 * @returns {Array.<Object>} Diff between the old and the new model tree state.
 	 */
 	getChanges( options = { includeChangesInGraveyard: false } ) {
 		// If there are cached changes, just return them instead of calculating changes again.
@@ -394,11 +395,11 @@ export default class Differ {
 	}
 
 	/**
-	 * Checks whether given element is inserted or removed or one of its ancestor is inserted or removed. Used to
-	 * filter out sub-changes in elements that are changed itself.
+	 * Checks whether a given element is inserted or removed or one of its ancestors is inserted or removed. Used to
+	 * filter out sub-changes in elements that are changed.
 	 *
 	 * @private
-	 * @param {module:engine/model/element~Element} element Element to check.
+	 * @param {module:engine/model/element~Element} element An element to check.
 	 * @returns {Boolean}
 	 */
 	_isInsertedOrRemoved( element ) {
@@ -434,7 +435,7 @@ export default class Differ {
 	}
 
 	/**
-	 * Saves and handles insert change.
+	 * Saves and handles an insert change.
 	 *
 	 * @private
 	 * @param {module:engine/model/element~Element} parent
@@ -448,7 +449,7 @@ export default class Differ {
 	}
 
 	/**
-	 * Saves and handles remove change.
+	 * Saves and handles a remove change.
 	 *
 	 * @private
 	 * @param {module:engine/model/element~Element} parent
@@ -462,7 +463,7 @@ export default class Differ {
 	}
 
 	/**
-	 * Saves and handles attribute change.
+	 * Saves and handles an attribute change.
 	 *
 	 * @private
 	 * @param {module:engine/model/item~Item} item
@@ -505,7 +506,7 @@ export default class Differ {
 	}
 
 	/**
-	 * Gets an array of changes that were already saved for given element.
+	 * Gets an array of changes that have already been saved for a given element.
 	 *
 	 * @private
 	 * @param {module:engine/model/element~Element} element
@@ -526,7 +527,7 @@ export default class Differ {
 	}
 
 	/**
-	 * Saves a children snapshot for given element.
+	 * Saves a children snapshot for a given element.
 	 *
 	 * @private
 	 * @param {module:engine/model/element~Element} element
@@ -538,12 +539,12 @@ export default class Differ {
 	}
 
 	/**
-	 * For given newly saved change, compares it with a change already done on the element and modifies the incoming
+	 * For a given newly saved change, compares it with a change already done on the element and modifies the incoming
 	 * change and/or the old change.
 	 *
 	 * @private
 	 * @param {Object} inc Incoming (new) change.
-	 * @param {Array.<Object>} changes Array containing all the changes done on that element.
+	 * @param {Array.<Object>} changes An array containing all the changes done on that element.
 	 */
 	_handleChange( inc, changes ) {
 		for ( const old of changes ) {
@@ -718,10 +719,10 @@ export default class Differ {
 	 * Returns an object with a single insert change description.
 	 *
 	 * @private
-	 * @param {module:engine/model/element~Element} parent Element in which change happened.
-	 * @param {Number} offset Offset at which change happened.
-	 * @param {String} name Removed element name or `'$text'` for character.
-	 * @returns {Object} Diff item.
+	 * @param {module:engine/model/element~Element} parent The element in which the change happened.
+	 * @param {Number} offset The offset at which change happened.
+	 * @param {String} name The name of the removed element or `'$text'` for a character.
+	 * @returns {Object} The diff item.
 	 */
 	_getInsertDiff( parent, offset, name ) {
 		return {
@@ -737,10 +738,10 @@ export default class Differ {
 	 * Returns an object with a single remove change description.
 	 *
 	 * @private
-	 * @param {module:engine/model/element~Element} parent Element in which change happened.
-	 * @param {Number} offset Offset at which change happened.
-	 * @param {String} name Removed element name or `'$text'` for character.
-	 * @returns {Object} Diff item.
+	 * @param {module:engine/model/element~Element} parent The element in which change happened.
+	 * @param {Number} offset The offset at which change happened.
+	 * @param {String} name The name of the removed element or `'$text'` for a character.
+	 * @returns {Object} The diff item.
 	 */
 	_getRemoveDiff( parent, offset, name ) {
 		return {
@@ -753,13 +754,13 @@ export default class Differ {
 	}
 
 	/**
-	 * Returns an array of objects that each is a single attribute change description.
+	 * Returns an array of objects where each one is a single attribute change description.
 	 *
 	 * @private
-	 * @param {module:engine/model/range~Range} range Range on which change happened.
-	 * @param {Map} oldAttributes Map, map iterator or compatible object that contains attributes before change.
-	 * @param {Map} newAttributes Map, map iterator or compatible object that contains attributes after change.
-	 * @returns {Array.<Object>} Array containing one or more diff items.
+	 * @param {module:engine/model/range~Range} range The range where the change happened.
+	 * @param {Map} oldAttributes A map, map iterator or compatible object that contains attributes before the change.
+	 * @param {Map} newAttributes A map, map iterator or compatible object that contains attributes after the change.
+	 * @returns {Array.<Object>} An array containing one or more diff items.
 	 */
 	_getAttributesDiff( range, oldAttributes, newAttributes ) {
 		// Results holder.

+ 4 - 2
packages/ckeditor5-engine/src/model/schema.js

@@ -722,7 +722,8 @@ export default class Schema {
 	/**
 	 * Tries to find position ancestors that allows to insert given node.
 	 * It starts searching from the given position and goes node by node to the top of the model tree
-	 * as long as {@link module:engine/model/schema~Schema#isLimit limit element} or top-most ancestor won't be reached.
+	 * as long as {@link module:engine/model/schema~Schema#isLimit limit element},
+	 * {@link module:engine/model/schema~Schema#isObject object element} or top-most ancestor won't be reached.
 	 *
 	 * @params {module:engine/model/node~Node} node Node for which allowed parent should be found.
 	 * @params {module:engine/model/position~Position} position Position from searching will start.
@@ -736,7 +737,8 @@ export default class Schema {
 				return parent;
 			}
 
-			if ( this.isLimit( parent ) ) {
+			// Do not split limit elements and objects.
+			if ( this.isLimit( parent ) || this.isObject( parent ) ) {
 				return null;
 			}
 

+ 1 - 1
packages/ckeditor5-engine/tests/manual/highlight.js

@@ -60,7 +60,7 @@ class FancyWidget extends Plugin {
 
 ClassicEditor.create( global.document.querySelector( '#editor' ), {
 	plugins: [ Enter, Typing, Paragraph, Undo, Heading, Bold, Italic, List, FancyWidget ],
-	toolbar: [ 'headings', 'undo', 'redo', 'bold', 'italic', 'numberedList', 'bulletedList' ]
+	toolbar: [ 'headings', '|', 'undo', 'redo', 'bold', 'italic', 'numberedList', 'bulletedList' ]
 } )
 	.then( editor => {
 		window.editor = editor;

+ 1 - 1
packages/ckeditor5-engine/tests/manual/markers.js

@@ -26,7 +26,7 @@ let _uid = 1;
 ClassicEditor
 	.create( document.querySelector( '#editor' ), {
 		plugins: [ Enter, Typing, Paragraph, Bold, Italic, List, Heading, Undo ],
-		toolbar: [ 'headings', 'bold', 'italic', 'bulletedList', 'numberedList', 'undo', 'redo' ]
+		toolbar: [ 'headings', '|', 'bold', 'italic', 'bulletedList', 'numberedList', 'undo', 'redo' ]
 	} )
 	.then( editor => {
 		window.editor = editor;

+ 1 - 1
packages/ckeditor5-engine/tests/manual/placeholder.js

@@ -17,7 +17,7 @@ import { attachPlaceholder } from '../../src/view/placeholder';
 ClassicEditor
 	.create( global.document.querySelector( '#editor' ), {
 		plugins: [ Enter, Typing, Paragraph, Undo, Heading ],
-		toolbar: [ 'headings', 'undo', 'redo' ]
+		toolbar: [ 'headings', '|', 'undo', 'redo' ]
 	} )
 	.then( editor => {
 		const view = editor.editing.view;

+ 24 - 33
packages/ckeditor5-engine/tests/manual/tickets/475/1.js

@@ -8,9 +8,6 @@
 import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
 
 import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
-
-import TreeWalker from '../../../../src/model/treewalker';
-import Position from '../../../../src/model/position';
 import Range from '../../../../src/model/range';
 import LivePosition from '../../../../src/model/liveposition';
 
@@ -45,51 +42,45 @@ class Link extends Plugin {
 	}
 }
 
-const urlRegex = /https?:\/\/(www\.)?[-a-zA-Z0-9@:%._+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_+.~#?&//=]*)/;
-
 class AutoLinker extends Plugin {
 	init() {
-		this.editor.model.document.on( 'change', ( event, type, changes, batch ) => {
-			if ( type != 'insert' ) {
-				return;
-			}
+		this.editor.model.document.on( 'change', () => {
+			const changes = this.editor.model.document.differ.getChanges();
 
-			for ( const value of changes.range.getItems( { singleCharacters: true } ) ) {
-				const walker = new TreeWalker( {
-					direction: 'backward',
-					startPosition: Position.createAfter( value )
-				} );
+			for ( const entry of changes ) {
+				if ( entry.type != 'insert' || entry.name != '$text' || !entry.position.textNode ) {
+					continue;
+				}
 
-				const currentValue = walker.next().value;
-				const text = currentValue.item.data;
+				const textNode = entry.position.textNode;
+				const text = textNode.data;
 
 				if ( !text ) {
 					return;
 				}
 
-				const matchedUrl = urlRegex.exec( text );
-
-				if ( !matchedUrl ) {
-					return;
+				const regexp = /https?:\/\/(www\.)?[-a-zA-Z0-9@:%._+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_+.~#?&//=]*)/g;
+				let match;
+
+				while ( ( match = regexp.exec( text ) ) !== null ) {
+					const index = match.index;
+					const url = match[ 0 ];
+					const length = url.length;
+
+					if ( entry.position.offset + entry.length == index + length ) {
+						const livePos = LivePosition.createFromParentAndOffset( textNode.parent, index );
+						this.editor.model.enqueueChange( writer => {
+							const urlRange = Range.createFromPositionAndShift( livePos, length );
+							writer.setAttribute( 'link', url, urlRange );
+						} );
+						return;
+					}
 				}
-
-				const url = matchedUrl[ 0 ];
-				const offset = _getLastPathPart( currentValue.nextPosition.path ) + matchedUrl.index;
-				const livePos = LivePosition.createFromParentAndOffset( currentValue.item.parent, offset );
-
-				this.editor.model.enqueueChange( batch, writer => {
-					const urlRange = Range.createFromPositionAndShift( livePos, url.length );
-					writer.setAttribute( 'link', url, urlRange );
-				} );
 			}
 		} );
 	}
 }
 
-function _getLastPathPart( path ) {
-	return path[ path.length - 1 ];
-}
-
 ClassicEditor.create( document.querySelector( '#editor' ), {
 	plugins: [ Enter, Typing, Paragraph, Undo, Link, AutoLinker ],
 	toolbar: [ 'undo', 'redo' ]

+ 1 - 1
packages/ckeditor5-engine/tests/manual/tickets/603/1.js

@@ -16,7 +16,7 @@ import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
 ClassicEditor
 	.create( document.querySelector( '#editor' ), {
 		plugins: [ Enter, Typing, Paragraph, Heading, Bold, Italic ],
-		toolbar: [ 'headings', 'bold', 'italic' ]
+		toolbar: [ 'headings', '|', 'bold', 'italic' ]
 	} )
 	.then( editor => {
 		window.editor = editor;

+ 17 - 3
packages/ckeditor5-engine/tests/model/schema.js

@@ -1386,7 +1386,7 @@ describe( 'Schema', () => {
 			} );
 		} );
 
-		it( 'should return position ancestor that allows to insert given note to it', () => {
+		it( 'should return position ancestor that allows to insert given node to it', () => {
 			const node = new Element( 'paragraph' );
 
 			const allowedParent = schema.findAllowedParent( node, Position.createAt( r1bQp ) );
@@ -1394,7 +1394,7 @@ describe( 'Schema', () => {
 			expect( allowedParent ).to.equal( r1bQ );
 		} );
 
-		it( 'should return position ancestor that allows to insert given note to it when position is already i such an element', () => {
+		it( 'should return position ancestor that allows to insert given node to it when position is already i such an element', () => {
 			const node = new Text( 'text' );
 
 			const parent = schema.findAllowedParent( node, Position.createAt( r1bQp ) );
@@ -1402,7 +1402,7 @@ describe( 'Schema', () => {
 			expect( parent ).to.equal( r1bQp );
 		} );
 
-		it( 'should return null when limit element will be reached before allowed parent', () => {
+		it( 'should return null when limit element is reached before allowed parent', () => {
 			schema.extend( 'blockQuote', {
 				isLimit: true
 			} );
@@ -1416,6 +1416,20 @@ describe( 'Schema', () => {
 			expect( parent ).to.null;
 		} );
 
+		it( 'should return null when object element is reached before allowed parent', () => {
+			schema.extend( 'blockQuote', {
+				isObject: true
+			} );
+			schema.register( 'div', {
+				allowIn: '$root'
+			} );
+			const node = new Element( 'div' );
+
+			const parent = schema.findAllowedParent( node, Position.createAt( r1bQp ) );
+
+			expect( parent ).to.null;
+		} );
+
 		it( 'should return null when there is no allowed ancestor for given position', () => {
 			const node = new Element( 'section' );