Przeglądaj źródła

Merge stable into master

CKEditor Bot 5 lat temu
rodzic
commit
fc797ed1f8

Plik diff jest za duży
+ 18 - 18
docs/framework/guides/architecture/editing-engine.md


+ 9 - 9
packages/ckeditor5-engine/src/controller/datacontroller.js

@@ -126,8 +126,8 @@ export default class DataController {
 		// Define default converters for text and elements.
 		//
 		// Note that if there is no default converter for the element it will be skipped, for instance `<b>foo</b>` will be
-		// converted to nothing. We add `convertToModelFragment` as a last converter so it converts children of that
-		// element to the document fragment so `<b>foo</b>` will be converted to `foo` if there is no converter for `<b>`.
+		// converted to nothing. We therefore add `convertToModelFragment` as a last converter so it converts children of that
+		// element to the document fragment and so `<b>foo</b>` will be converted to `foo` if there is no converter for `<b>`.
 		this.upcastDispatcher.on( 'text', convertText(), { priority: 'lowest' } );
 		this.upcastDispatcher.on( 'element', convertToModelFragment(), { priority: 'lowest' } );
 		this.upcastDispatcher.on( 'documentFragment', convertToModelFragment(), { priority: 'lowest' } );
@@ -135,8 +135,8 @@ export default class DataController {
 		this.decorate( 'init' );
 		this.decorate( 'set' );
 
-		// Fire `ready` event when initialisation has completed. Such low level listener gives possibility
-		// to plug into initialisation pipeline without interrupting the initialisation flow.
+		// Fire the `ready` event when the initialization has completed. Such low-level listener gives possibility
+		// to plug into the initialization pipeline without interrupting the initialization flow.
 		this.on( 'init', () => {
 			this.fire( 'ready' );
 		}, { priority: 'lowest' } );
@@ -220,7 +220,7 @@ export default class DataController {
 
 		this.mapper.bindElements( modelElementOrFragment, viewDocumentFragment );
 
-		// We have no view controller and rendering do DOM in DataController so view.change() block is not used here.
+		// We have no view controller and rendering to DOM in DataController so view.change() block is not used here.
 		this.downcastDispatcher.convertInsert( modelRange, viewWriter );
 
 		if ( !modelElementOrFragment.is( 'documentFragment' ) ) {
@@ -439,17 +439,17 @@ export default class DataController {
 	}
 
 	/**
-	 * Event fired once data initialisation has finished.
+	 * Event fired once the data initialization has finished.
 	 *
 	 * @event ready
 	 */
 
 	/**
-	 * Event fired after {@link #init init() method} has been run. It can be {@link #listenTo listened to} to adjust/modify
-	 * the initialisation flow. However, if the `init` event is stopped or prevented, the {@link #event:ready ready event}
+	 * Event fired after the {@link #init `init()` method} was run. It can be {@link #listenTo listened to} in order to adjust or modify
+	 * the initialization flow. However, if the `init` event is stopped or prevented, the {@link #event:ready `ready` event}
 	 * should be fired manually.
 	 *
-	 * The `init` event is fired by decorated {@link #init} method.
+	 * The `init` event is fired by the decorated {@link #init} method.
 	 * See {@link module:utils/observablemixin~ObservableMixin#decorate} for more information and samples.
 	 *
 	 * @event init

+ 1 - 1
packages/ckeditor5-engine/src/controller/editingcontroller.js

@@ -73,7 +73,7 @@ export default class EditingController {
 		const selection = doc.selection;
 		const markers = this.model.markers;
 
-		// When plugins listen on model changes (on selection change, post fixers, etc) and change the view as a result of
+		// When plugins listen on model changes (on selection change, post fixers, etc.) and change the view as a result of
 		// model's change, they might trigger view rendering before the conversion is completed (e.g. before the selection
 		// is converted). We disable rendering for the length of the outermost model change() block to prevent that.
 		//

+ 55 - 55
packages/ckeditor5-engine/src/conversion/downcastdispatcher.js

@@ -14,84 +14,84 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
 import { extend } from 'lodash-es';
 
 /**
- * `DowncastDispatcher` is a central point of downcasting (conversion from model to view), which is a process of reacting to changes
- * in the model and firing a set of events. Callbacks listening to those events are called converters. Those
- * converters role is to convert the model changes to changes in view (for example, adding view nodes or
+ * Downcast dispatcher is a central point of downcasting (conversion from the model to the view), which is a process of reacting to changes
+ * in the model and firing a set of events. Callbacks listening to these events are called converters. The
+ * converters' role is to convert the model changes to changes in view (for example, adding view nodes or
  * changing attributes on view elements).
  *
- * During conversion process, `DowncastDispatcher` fires events, basing on state of the model and prepares
- * data for those events. It is important to understand that those events are connected with changes done on model,
- * for example: "node has been inserted" or "attribute has changed". This is in a contrary to upcasting (view to model conversion),
- * where we convert view state (view nodes) to a model tree.
+ * During the conversion process, downcast dispatcher fires events basing on the state of the model and prepares
+ * data for these events. It is important to understand that the events are connected with the changes done on the model,
+ * for example: "a node has been inserted" or "an attribute has changed". This is in contrary to upcasting (a view-to-model conversion)
+ * where you convert the view state (view nodes) to a model tree.
  *
  * The events are prepared basing on a diff created by {@link module:engine/model/differ~Differ Differ}, which buffers them
- * and then passes to `DowncastDispatcher` as a diff between old model state and new model state.
+ * and then passes to the downcast dispatcher as a diff between the old model state and the new model state.
  *
- * Note, that because changes are converted there is a need to have a mapping between model structure and view structure.
- * To map positions and elements during downcast (model to view conversion) use {@link module:engine/conversion/mapper~Mapper}.
+ * Note that because the changes are converted, there is a need to have a mapping between the model structure and the view structure.
+ * To map positions and elements during the downcast (a model-to-view conversion), use {@link module:engine/conversion/mapper~Mapper}.
  *
- * `DowncastDispatcher` fires following events for model tree changes:
+ * Downcast dispatcher fires the following events for model tree changes:
  *
- * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:insert insert}
- * if a range of nodes has been inserted to the model tree,
- * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:remove remove}
- * if a range of nodes has been removed from the model tree,
- * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute attribute}
- * if attribute has been added, changed or removed from a model node.
+ * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:insert `insert`} &ndash;
+ * If a range of nodes was inserted to the model tree.
+ * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:remove `remove`} &ndash;
+ * If a range of nodes was removed from the model tree.
+ * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute `attribute`} &ndash;
+ * If an attribute was added, changed or removed from a model node.
  *
- * For {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:insert insert}
- * and {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute attribute},
- * `DowncastDispatcher` generates {@link module:engine/conversion/modelconsumable~ModelConsumable consumables}.
- * These are used to have a control over which changes has been already consumed. It is useful when some converters
- * overwrite other or converts multiple changes (for example converts insertion of an element and also converts that
- * element's attributes during insertion).
+ * For {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:insert `insert`}
+ * and {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute `attribute`},
+ * downcast dispatcher generates {@link module:engine/conversion/modelconsumable~ModelConsumable consumables}.
+ * These are used to have control over which changes have already been consumed. It is useful when some converters
+ * overwrite others or convert multiple changes (for example, it converts an insertion of an element and also converts that
+ * element's attributes during the insertion).
  *
- * Additionally, `DowncastDispatcher` fires events for {@link module:engine/model/markercollection~Marker marker} changes:
+ * Additionally, downcast dispatcher fires events for {@link module:engine/model/markercollection~Marker marker} changes:
  *
- * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:addMarker} if a marker has been added,
- * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:removeMarker} if a marker has been removed.
+ * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:addMarker} &ndash; If a marker was added.
+ * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:removeMarker} &ndash; If a marker was removed.
  *
- * Note, that changing a marker is done through removing the marker from the old range, and adding on the new range,
- * so both those events are fired.
+ * Note that changing a marker is done through removing the marker from the old range and adding it on the new range,
+ * so both events are fired.
  *
- * Finally, `DowncastDispatcher` also handles firing events for {@link module:engine/model/selection model selection}
+ * Finally, downcast dispatcher also handles firing events for the {@link module:engine/model/selection model selection}
  * conversion:
  *
  * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:selection}
- * which converts selection from model to view,
+ * &ndash; Converts the selection from the model to the view.
  * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute}
- * which is fired for every selection attribute,
+ * &ndash; Fired for every selection attribute.
  * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:addMarker}
- * which is fired for every marker which contains selection.
+ * &ndash; Fired for every marker that contains a selection.
  *
  * Unlike model tree and markers, events for selection are not fired for changes but for selection state.
  *
- * When providing custom listeners for `DowncastDispatcher` remember to check whether given change has not been
+ * When providing custom listeners for downcast dispatcher, remember to check whether a given change has not been
  * {@link module:engine/conversion/modelconsumable~ModelConsumable#consume consumed} yet.
  *
- * When providing custom listeners for `DowncastDispatcher` keep in mind that any callback that had
+ * When providing custom listeners for downcast dispatcher, keep in mind that any callback that has
  * {@link module:engine/conversion/modelconsumable~ModelConsumable#consume consumed} a value from a consumable and
  * converted the change should also stop the event (for efficiency purposes).
  *
- * When providing custom listeners for `DowncastDispatcher` remember to use provided
+ * When providing custom listeners for downcast dispatcher, remember to use the provided
  * {@link module:engine/view/downcastwriter~DowncastWriter view downcast writer} to apply changes to the view document.
  *
- * Example of a custom converter for `DowncastDispatcher`:
+ * An example of a custom converter for the downcast dispatcher:
  *
- *		// We will convert inserting "paragraph" model element into the model.
+ *		// You will convert inserting a "paragraph" model element into the model.
  *		downcastDispatcher.on( 'insert:paragraph', ( evt, data, conversionApi ) => {
  *			// Remember to check whether the change has not been consumed yet and consume it.
  *			if ( conversionApi.consumable.consume( data.item, 'insert' ) ) {
  *				return;
  *			}
  *
- *			// Translate position in model to position in view.
+ *			// Translate the position in the model to a position in the view.
  *			const viewPosition = conversionApi.mapper.toViewPosition( data.range.start );
  *
- *			// Create <p> element that will be inserted in view at `viewPosition`.
+ *			// Create a <p> element that will be inserted into the view at the `viewPosition`.
  *			const viewElement = conversionApi.writer.createContainerElement( 'p' );
  *
- *			// Bind the newly created view element to model element so positions will map accordingly in future.
+ *			// Bind the newly created view element to the model element so positions will map accordingly in the future.
  *			conversionApi.mapper.bindElements( data.item, viewElement );
  *
  *			// Add the newly created view element to the view.
@@ -103,15 +103,15 @@ import { extend } from 'lodash-es';
  */
 export default class DowncastDispatcher {
 	/**
-	 * Creates a `DowncastDispatcher` instance.
+	 * Creates a downcast dispatcher instance.
 	 *
 	 * @see module:engine/conversion/downcastdispatcher~DowncastConversionApi
-	 * @param {Object} conversionApi Additional properties for interface that will be passed to events fired
-	 * by `DowncastDispatcher`.
+	 * @param {Object} conversionApi Additional properties for an interface that will be passed to events fired
+	 * by the downcast dispatcher.
 	 */
 	constructor( conversionApi ) {
 		/**
-		 * Interface passed by dispatcher to the events callbacks.
+		 * An interface passed by the dispatcher to the event callbacks.
 		 *
 		 * @member {module:engine/conversion/downcastdispatcher~DowncastConversionApi}
 		 */
@@ -119,11 +119,11 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Takes {@link module:engine/model/differ~Differ model differ} object with buffered changes and fires conversion basing on it.
+	 * Takes a {@link module:engine/model/differ~Differ model differ} object with buffered changes and fires conversion basing on it.
 	 *
-	 * @param {module:engine/model/differ~Differ} differ Differ object with buffered changes.
-	 * @param {module:engine/model/markercollection~MarkerCollection} markers Markers connected with converted model.
-	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify view document.
+	 * @param {module:engine/model/differ~Differ} differ The differ object with buffered changes.
+	 * @param {module:engine/model/markercollection~MarkerCollection} markers Markers connected with the converted model.
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer The view writer that should be used to modify the view document.
 	 */
 	convertChanges( differ, markers, writer ) {
 		// Before the view is updated, remove markers which have changed.
@@ -157,15 +157,15 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Starts conversion of a range insertion.
+	 * Starts a conversion of a range insertion.
 	 *
-	 * For each node in the range, {@link #event:insert insert event is fired}. For each attribute on each node,
-	 * {@link #event:attribute attribute event is fired}.
+	 * For each node in the range, {@link #event:insert `insert` event is fired}. For each attribute on each node,
+	 * {@link #event:attribute `attribute` event is fired}.
 	 *
 	 * @fires insert
 	 * @fires attribute
-	 * @param {module:engine/model/range~Range} range Inserted range.
-	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify view document.
+	 * @param {module:engine/model/range~Range} range The inserted range.
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer The view writer that should be used to modify the view document.
 	 */
 	convertInsert( range, writer ) {
 		this.conversionApi.writer = writer;
@@ -554,7 +554,7 @@ export default class DowncastDispatcher {
 	 */
 
 	/**
-	 * Fired when a new marker is added to the model. Also fired when collapsed model selection that is inside marker is converted.
+	 * Fired when a new marker is added to the model. Also fired when collapsed model selection that is inside a marker is converted.
 	 *
 	 * `addMarker` is a namespace for a class of events. Names of actually called events follow this pattern:
 	 * `addMarker:markerName`. By specifying certain marker names, you can make the events even more gradual. For example,
@@ -634,7 +634,7 @@ function shouldMarkerChangeBeConverted( modelPosition, marker, mapper ) {
 /**
  * Conversion interface that is registered for given {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher}
  * and is passed as one of parameters when {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher dispatcher}
- * fires it's events.
+ * fires its events.
  *
  * @interface module:engine/conversion/downcastdispatcher~DowncastConversionApi
  */

+ 21 - 20
packages/ckeditor5-engine/src/conversion/downcasthelpers.js

@@ -364,39 +364,40 @@ export default class DowncastHelpers extends ConversionHelpers {
 	 *
 	 * This conversion creates a representation for model marker boundaries in the view:
 	 *
-	 * * if the marker boundary is at a position where text nodes are allowed, then a view element with specified tag name
-	 * and `name` attribute is added at that position,
-	 * * in other cases, a specified attribute is set on a view element that is before/after marker boundary.
+	 * * If the marker boundary is at a position where text nodes are allowed, then a view element with the specified tag name
+	 * and `name` attribute is added at this position.
+	 * * In other cases, a specified attribute is set on a view element that is before or after the marker boundary.
 	 *
-	 * Typically, the marker names use `group:uniqueId:otherData` convention. For example: `comment:e34zfk9k2n459df53sjl34:zx32c`.
-	 * The default configuration for this conversion is that the first part is `group` part and the rest of
-	 * the marker name becomes `name` part.
+	 * Typically, marker names use the `group:uniqueId:otherData` convention. For example: `comment:e34zfk9k2n459df53sjl34:zx32c`.
+	 * The default configuration for this conversion is that the first part is the `group` part and the rest of
+	 * the marker name becomes the `name` part.
 	 *
 	 * Tag and attribute names and values are generated from the marker name:
 	 *
-	 * * templates for attributes are `data-[group]-start-before="[name]"`, `data-[group]-start-after="[name]"`,
-	 * `data-[group]-end-before="[name]"` and `data-[group]-end-after="[name]"`,
-	 * * templates for view elements are `<[group]-start name="[name]">` and `<[group]-end name="[name]">`.
+	 * * Templates for attributes are `data-[group]-start-before="[name]"`, `data-[group]-start-after="[name]"`,
+	 * `data-[group]-end-before="[name]"` and `data-[group]-end-after="[name]"`.
+	 * * Templates for view elements are `<[group]-start name="[name]">` and `<[group]-end name="[name]">`.
 	 *
-	 * Attributes mark whether given marker start or end boundary is before or after given element.
+	 * Attributes mark whether the given marker's start or end boundary is before or after the given element.
 	 * Attributes `data-[group]-start-before` and `data-[group]-end-after` are favored.
 	 * The other two are used when the former two cannot be used.
 	 *
 	 * The conversion configuration can take a function that will generate different group and name parts.
 	 * If such function is set as the `config.view` parameter, it is passed a marker name and it is expected to return an object with two
-	 * properties: `group` and `name`. If the function returns falsy value, the conversion will not take place.
+	 * properties: `group` and `name`. If the function returns a falsy value, the conversion will not take place.
 	 *
 	 * Basic usage:
 	 *
 	 *		// Using the default conversion.
-	 *		// In this case, all markers which name starts with 'comment:' will be converted.
+	 *		// In this case, all markers whose name starts with 'comment:' will be converted.
 	 *		// The `group` parameter will be set to `comment`.
 	 *		// The `name` parameter will be the rest of the marker name (without `:`).
 	 *		editor.conversion.for( 'dataDowncast' ).markerToData( {
 	 *			model: 'comment'
 	 *		} );
 	 *
-	 * An example of a view that may be generated by this conversion (assuming a marker with name `comment:commentId:uid` marked by `[]`):
+	 * An example of a view that may be generated by this conversion (assuming a marker with the name `comment:commentId:uid` marked
+	 * by `[]`):
 	 *
 	 *		// Model:
 	 *		<paragraph>Foo[bar</paragraph>
@@ -408,12 +409,12 @@ export default class DowncastHelpers extends ConversionHelpers {
 	 *
 	 * In the example above, the comment starts before "bar" and ends after the image.
 	 *
-	 * If `name` part is empty, following view may be generated:
+	 * If the `name` part is empty, the following view may be generated:
 	 *
 	 *		<p>Foo <myMarker-start></myMarker-start>bar</p>
 	 *		<figure data-myMarker-end-after="" class="image"><img src="abc.jpg" /></figure>
 	 *
-	 * **Note:** situation when some markers have `name` part and some don't is incorrect and should be avoided.
+	 * **Note:** A situation where some markers have the `name` part and some do not have it is incorrect and should be avoided.
 	 *
 	 * Examples where `data-group-start-after` and `data-group-end-before` are used:
 	 *
@@ -423,7 +424,7 @@ export default class DowncastHelpers extends ConversionHelpers {
 	 * 		// View:
 	 *		<blockquote><p data-group-end-before="name" data-group-start-before="name">Foo</p></blockquote>
 	 *
-	 * Similarly, when marker is collapsed after the last element:
+	 * Similarly, when a marker is collapsed after the last element:
 	 *
 	 *		// Model:
 	 *		<blockQuote><paragraph>Foo</paragraph>[]</blockQuote>
@@ -436,7 +437,7 @@ export default class DowncastHelpers extends ConversionHelpers {
 	 *
 	 * Other examples of usage:
 	 *
-	 *		// Using custom function which is the same as the default conversion:
+	 *		// Using a custom function which is the same as the default conversion:
 	 *		editor.conversion.for( 'dataDowncast' ).markerToData( {
 	 *			model: 'comment'
 	 *			view: markerName => ( {
@@ -445,7 +446,7 @@ export default class DowncastHelpers extends ConversionHelpers {
 	 *			} )
 	 *		} );
 	 *
-	 *		// Using converter priority:
+	 *		// Using the converter priority:
 	 *		editor.conversion.for( 'dataDowncast' ).markerToData( {
 	 *			model: 'comment'
 	 *			view: markerName => ( {
@@ -463,7 +464,7 @@ export default class DowncastHelpers extends ConversionHelpers {
 	 * @method #markerToData
 	 * @param {Object} config Conversion configuration.
 	 * @param {String} config.model The name of the model marker (or model marker group) to convert.
-	 * @param {Function} [config.view] Function that takes the model marker name as a parameter and returns an object with `group`
+	 * @param {Function} [config.view] A function that takes the model marker name as a parameter and returns an object with the `group`
 	 * and `name` properties.
 	 * @param {module:utils/priorities~PriorityString} [config.converterPriority='normal'] Converter priority.
 	 * @returns {module:engine/conversion/downcasthelpers~DowncastHelpers}
@@ -845,7 +846,7 @@ export function insertUIElement( elementCreator ) {
 }
 
 // Function factory that returns a default downcast converter for removing a {@link module:engine/view/uielement~UIElement UI element}
-// basing on marker remove change.
+// based on marker remove change.
 //
 // This converter unbinds elements from the marker name.
 //

+ 11 - 10
packages/ckeditor5-engine/src/conversion/upcasthelpers.js

@@ -340,7 +340,7 @@ export default class UpcastHelpers extends ConversionHelpers {
 	elementToMarker( config ) {
 		/**
 		 * The {@link module:engine/conversion/upcasthelpers~UpcastHelpers#elementToMarker `UpcastHelpers#elementToMarker()`}
-		 * method has been deprecated and will be removed in the near future.
+		 * method was deprecated and will be removed in the near future.
 		 * Please use {@link module:engine/conversion/upcasthelpers~UpcastHelpers#dataToMarker `UpcastHelpers#dataToMarker()`} instead.
 		 *
 		 * @error upcast-helpers-element-to-marker-deprecated
@@ -348,7 +348,7 @@ export default class UpcastHelpers extends ConversionHelpers {
 		console.warn(
 			attachLinkToDocumentation(
 				'upcast-helpers-element-to-marker-deprecated: ' +
-				'The UpcastHelpers#elementToMarker() method has been deprecated and will be removed in the near future. ' +
+				'The UpcastHelpers#elementToMarker() method was deprecated and will be removed in the near future. ' +
 				'Please use UpcastHelpers#dataToMarker() instead.'
 			)
 		);
@@ -357,7 +357,7 @@ export default class UpcastHelpers extends ConversionHelpers {
 	}
 
 	/**
-	 * View to model marker conversion helper.
+	 * View-to-model marker conversion helper.
 	 *
 	 * Converts view data created by {@link module:engine/conversion/downcasthelpers~DowncastHelpers#markerToData `#markerToData()`}
 	 * back to a model marker.
@@ -368,7 +368,7 @@ export default class UpcastHelpers extends ConversionHelpers {
 	 *
 	 * The `config.view` property is equal to the marker group name to convert.
 	 *
-	 * By default, this converter creates markers with `group:name` name convention (to match the default `markerToData` conversion).
+	 * By default, this converter creates markers with the `group:name` name convention (to match the default `markerToData` conversion).
 	 *
 	 * The conversion configuration can take a function that will generate a marker name.
 	 * If such function is set as the `config.model` parameter, it is passed the `name` part from the view element or attribute and it is
@@ -377,7 +377,7 @@ export default class UpcastHelpers extends ConversionHelpers {
 	 * Basic usage:
 	 *
 	 *		// Using the default conversion.
-	 *		// In this case, all markers from `comment` group will be converted.
+	 *		// In this case, all markers from the `comment` group will be converted.
 	 *		// The conversion will look for `<comment-start>` and `<comment-end>` tags and
 	 *		// `data-comment-start-before`, `data-comment-start-after`,
 	 *		// `data-comment-end-before` and `data-comment-end-after` attributes.
@@ -395,17 +395,17 @@ export default class UpcastHelpers extends ConversionHelpers {
 	 *		<paragraph>Foo[bar</paragraph>
 	 *		<image src="abc.jpg"></image>]
 	 *
-	 * Where `[]` are boundaries of a marker that will receive `comment:commentId:uid` name.
+	 * Where `[]` are boundaries of a marker that will receive the `comment:commentId:uid` name.
 	 *
 	 * Other examples of usage:
 	 *
-	 *		// Using custom function which is the same as the default conversion:
+	 *		// Using a custom function which is the same as the default conversion:
 	 *		editor.conversion.for( 'upcast' ).dataToMarker( {
 	 *			view: 'comment',
 	 *			model: name => 'comment:' + name,
 	 *		} );
 	 *
-	 *		// Using converter priority:
+	 *		// Using the converter priority:
 	 *		editor.conversion.for( 'upcast' ).dataToMarker( {
 	 *			view: 'comment',
 	 *			model: name => 'comment:' + name,
@@ -417,8 +417,9 @@ export default class UpcastHelpers extends ConversionHelpers {
 	 *
 	 * @method #dataToMarker
 	 * @param {Object} config Conversion configuration.
-	 * @param {String} config.view Marker group name to convert.
-	 * @param {Function} [config.model] Function that takes `name` part from the view element or attribute and returns the marker name.
+	 * @param {String} config.view The marker group name to convert.
+	 * @param {Function} [config.model] A function that takes the `name` part from the view element or attribute and returns the marker
+	 * name.
 	 * @param {module:utils/priorities~PriorityString} [config.converterPriority='normal'] Converter priority.
 	 * @returns {module:engine/conversion/upcasthelpers~UpcastHelpers}
 	 */

+ 1 - 1
packages/ckeditor5-engine/src/model/markercollection.js

@@ -99,7 +99,7 @@ export default class MarkerCollection {
 			 *
 			 * @error markercollection-incorrect-marker-name
 			 */
-			throw new CKEditorError( 'markercollection-incorrect-marker-name: Marker name cannot contain "," character.', this );
+			throw new CKEditorError( 'markercollection-incorrect-marker-name: Marker name cannot contain the "," character.', this );
 		}
 
 		const oldMarker = this._markers.get( markerName );