Merge branch 'master' into t/1213

src/controller/datacontroller.js

@@ -26,7 +26,7 @@ import ModelRange from '../model/range';
  * Controller for the data pipeline. The data pipeline controls how data is retrieved from the document
  * and set inside it. Hence, the controller features two methods which allow to {@link ~DataController#get get}
  * and {@link ~DataController#set set} data of the {@link ~DataController#model model}
- * using given:
+ * using the given:
  *
  * * {@link module:engine/dataprocessor/dataprocessor~DataProcessor data processor},
  * * {@link module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher model to view} and
@@ -36,10 +36,11 @@ import ModelRange from '../model/range';
  */
 export default class DataController {
  /**
- * Creates data controller instance.
+ * Creates a data controller instance.
  *
  * @param {module:engine/model/model~Model} model Data model.
- * @param {module:engine/dataprocessor/dataprocessor~DataProcessor} [dataProcessor] Data processor which should used by the controller.
+ * @param {module:engine/dataprocessor/dataprocessor~DataProcessor} [dataProcessor] Data processor that should be used
+ * by the controller.
  */
  constructor( model, dataProcessor ) {
  /**
@@ -60,16 +61,16 @@ export default class DataController {
 
  /**
  * Mapper used for the conversion. It has no permanent bindings, because they are created when getting data and
- * cleared directly after data are converted. However, the mapper is defined as class property, because
+ * cleared directly after the data are converted. However, the mapper is defined as a class property, because
  * it needs to be passed to the `ModelConversionDispatcher` as a conversion API.
  *
  * @member {module:engine/conversion/mapper~Mapper}
  */
  this.mapper = new Mapper();
 
  /**
- * Model to view conversion dispatcher used by the {@link #get get method}.
- * To attach model to view converter to the data pipeline you need to add lister to this property:
+ * Model-to-view conversion dispatcher used by the {@link #get get method}.
+ * To attach the model-to-view converter to the data pipeline you need to add a listener to this property:
  *
  * data.modelToView( 'insert:$element', customInsertConverter );
  *
@@ -86,8 +87,8 @@ export default class DataController {
  this.modelToView.on( 'insert:$text', insertText(), { priority: 'lowest' } );
 
  /**
- * View to model conversion dispatcher used by the {@link #set set method}.
- * To attach view to model converter to the data pipeline you need to add lister to this property:
+ * View-to-model conversion dispatcher used by the {@link #set set method}.
+ * To attach the view-to-model converter to the data pipeline you need to add a listener to this property:
  *
  * data.viewToModel( 'element', customElementConverter );
  *
@@ -113,7 +114,7 @@ export default class DataController {
  }
 
  /**
- * Returns model's data converted by the {@link #modelToView model to view converters} and
+ * Returns the model's data converted by the {@link #modelToView model-to-view converters} and
  * formatted by the {@link #processor data processor}.
  *
  * @param {String} [rootName='main'] Root name.
@@ -127,11 +128,11 @@ export default class DataController {
  /**
  * Returns the content of the given {@link module:engine/model/element~Element model's element} or
  * {@link module:engine/model/documentfragment~DocumentFragment model document fragment} converted by the
- * {@link #modelToView model to view converters} and formatted by the
+ * {@link #modelToView model-to-view converters} and formatted by the
  * {@link #processor data processor}.
  *
  * @param {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment} modelElementOrFragment
- * Element which content will be stringified.
+ * Element whose content will be stringified.
  * @returns {String} Output data.
  */
  stringify( modelElementOrFragment ) {
@@ -145,11 +146,11 @@ export default class DataController {
  /**
  * Returns the content of the given {@link module:engine/model/element~Element model element} or
  * {@link module:engine/model/documentfragment~DocumentFragment model document fragment} converted by the
- * {@link #modelToView model to view converters} to a
+ * {@link #modelToView model-to-view converters} to a
  * {@link module:engine/view/documentfragment~DocumentFragment view document fragment}.
  *
  * @param {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment} modelElementOrFragment
- * Element or document fragment which content will be converted.
+ * Element or document fragment whose content will be converted.
  * @returns {module:engine/view/documentfragment~DocumentFragment} Output view DocumentFragment.
  */
  toView( modelElementOrFragment ) {
@@ -179,9 +180,9 @@ export default class DataController {
 
  /**
  * Sets input data parsed by the {@link #processor data processor} and
- * converted by the {@link #viewToModel view to model converters}.
+ * converted by the {@link #viewToModel view-to-model converters}.
  *
- * This method also creates a batch with all the changes applied. If all you need is to parse data use
+ * This method also creates a batch with all the changes applied. If all you need is to parse data, use
  * the {@link #parse} method.
  *
  * @param {String} data Input data.
@@ -204,7 +205,7 @@ export default class DataController {
 
  /**
  * Returns data parsed by the {@link #processor data processor} and then
- * converted by the {@link #viewToModel view to model converters}.
+ * converted by the {@link #viewToModel view-to-model converters}.
  *
  * @see #set
  * @param {String} data Data to parse.
@@ -221,16 +222,15 @@ export default class DataController {
  }
 
  /**
- * Returns wrapped by {module:engine/model/documentfragment~DocumentFragment} result of the given
- * {@link module:engine/view/element~Element view element} or
+ * Returns the result of the given {@link module:engine/view/element~Element view element} or
  * {@link module:engine/view/documentfragment~DocumentFragment view document fragment} converted by the
- * {@link #viewToModel view to model converters}.
+ * {@link #viewToModel view-to-model converters}, wrapped by {module:engine/model/documentfragment~DocumentFragment}.
  *
- * When marker elements were converted during conversion process then will be set as DocumentFragment's
+ * When marker elements were converted during the conversion process, it will be set as a DocumentFragment's
  * {@link module:engine/model/documentfragment~DocumentFragment#markers static markers map}.
  *
  * @param {module:engine/view/element~Element|module:engine/view/documentfragment~DocumentFragment} viewElementOrFragment
- * Element or document fragment which content will be converted.
+ * Element or document fragment whose content will be converted.
  * @param {module:engine/model/schema~SchemaContextDefinition} [context=['$root']] Base context in which the view will
  * be converted to the model. See: {@link module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher#convert}.
  * @returns {module:engine/model/documentfragment~DocumentFragment} Output document fragment.

src/controller/editingcontroller.js

@@ -28,14 +28,14 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
 
 /**
  * Controller for the editing pipeline. The editing pipeline controls {@link ~EditingController#model model} rendering,
- * including selection handling. It also creates {@link ~EditingController#view view document} which build a
- * browser-independent virtualization over the DOM elements. Editing controller also attach default converters.
+ * including selection handling. It also creates the {@link ~EditingController#view view document} which builds a
+ * browser-independent virtualization over the DOM elements. The editing controller also attaches default converters.
  *
  * @mixes module:utils/observablemixin~ObservableMixin
  */
 export default class EditingController {
  /**
- * Creates editing controller instance.
+ * Creates an editing controller instance.
  *
  * @param {module:engine/model/model~Model} model Editing model.
  */
@@ -57,17 +57,17 @@ export default class EditingController {
  this.view = new ViewDocument();
 
  /**
- * Mapper which describes model-view binding.
+ * Mapper which describes the model-view binding.
  *
  * @readonly
  * @member {module:engine/conversion/mapper~Mapper}
  */
  this.mapper = new Mapper();
 
  /**
- * Model to view conversion dispatcher, which converts changes from the model to {@link #view the editing view}.
+ * Model-to-view conversion dispatcher that converts changes from the model to {@link #view the editing view}.
  *
- * To attach model-to-view converter to the editing pipeline you need to add a listener to this dispatcher:
+ * To attach the model-to-view converter to the editing pipeline you need to add a listener to this dispatcher:
  *
  * editing.modelToView( 'insert:$element', customInsertConverter );
  *

src/dataprocessor/basichtmlwriter.js

@@ -10,14 +10,14 @@
 /* globals document */
 
 /**
- * Basic HTML writer, it uses the native `innerHTML` property for basic conversion
- * from DocumentFragment to an HTML string.
+ * Basic HTML writer. It uses the native `innerHTML` property for basic conversion
+ * from a document fragment to an HTML string.
  *
  * @implements module:engine/dataprocessor/htmlwriter~HtmlWriter
  */
 export default class BasicHtmlWriter {
  /**
- * Returns HTML string created from DocumentFragment.
+ * Returns an HTML string created from the document fragment.
  *
  * @param {DocumentFragment} fragment
  * @returns {String}

src/dataprocessor/dataprocessor.jsdoc

@@ -8,25 +8,25 @@
  */
 
 /**
- * DataProcessor interface. It should be implemented by actual DataProcessors.
- * Each data processor implements a certain format of the data. E.g. `MarkdownDataProcessor` will convert the data
- * (Markdown string) to a {@link module:engine/view/documentfragment~DocumentFragment DocumentFragment} and back.
+ * The data processor interface. It should be implemented by actual data processors.
+ * Each data processor implements a certain format of the data. For example, Markdown data processor will convert the data
+ * (a Markdown string) to a {@link module:engine/view/documentfragment~DocumentFragment document fragment} and back.
  *
  * @interface DataProcessor
  */
 
 /**
- * Converts a {@link module:engine/view/documentfragment~DocumentFragment DocumentFragment} to data.
+ * Converts a {@link module:engine/view/documentfragment~DocumentFragment document fragment} to data.
  *
  * @method #toData
- * @param {module:engine/view/documentfragment~DocumentFragment} fragment DocumentFragment to be processed.
+ * @param {module:engine/view/documentfragment~DocumentFragment} fragment The document fragment to be processed.
  * @returns {*}
  */
 
 /**
- * Converts data to a {@link module:engine/view/documentfragment~DocumentFragment DocumentFragment}.
+ * Converts the data to a {@link module:engine/view/documentfragment~DocumentFragment document fragment}.
  *
  * @method #toView
- * @param {*} data Data to be processed.
+ * @param {*} data The data to be processed.
  * @returns {module:engine/view/documentfragment~DocumentFragment}
  */

src/dataprocessor/htmldataprocessor.js

@@ -14,34 +14,34 @@ import DomConverter from '../view/domconverter';
 import { NBSP_FILLER } from '../view/filler';
 
 /**
- * HtmlDataProcessor class.
- * This data processor implementation uses HTML as input/output data.
+ * The HTML data processor class.
+ * This data processor implementation uses HTML as input and output data.
  *
  * @implements module:engine/dataprocessor/dataprocessor~DataProcessor
  */
 export default class HtmlDataProcessor {
  /**
- * Creates a new instance of the HtmlDataProcessor class.
+ * Creates a new instance of the HTML data processor class.
  */
  constructor() {
  /**
- * DOMParser instance used to parse HTML string to HTMLDocument.
+ * A DOM parser instance used to parse an HTML string to an HTML document.
  *
  * @private
  * @member {DOMParser}
  */
  this._domParser = new DOMParser();
 
  /**
- * DOM converter used to convert DOM elements to view elements.
+ * A DOM converter used to convert DOM elements to view elements.
  *
  * @private
  * @member
  */
  this._domConverter = new DomConverter( { blockFiller: NBSP_FILLER } );
 
  /**
- * BasicHtmlWriter instance used to convert DOM elements to HTML string.
+ * A basic HTML writer instance used to convert DOM elements to an HTML string.
  *
  * @private
  * @member {module:engine/dataprocessor/basichtmlwriter~BasicHtmlWriter}
@@ -50,8 +50,8 @@ export default class HtmlDataProcessor {
  }
 
  /**
- * Converts provided {@link module:engine/view/documentfragment~DocumentFragment DocumentFragment}
- * to data format - in this case HTML string.
+ * Converts a provided {@link module:engine/view/documentfragment~DocumentFragment document fragment}
+ * to data format — in this case to an HTML string.
  *
  * @param {module:engine/view/documentfragment~DocumentFragment} viewFragment
  * @returns {String} HTML string.
@@ -65,10 +65,10 @@ export default class HtmlDataProcessor {
  }
 
  /**
- * Converts provided HTML string to view tree.
+ * Converts the provided HTML string to a view tree.
  *
- * @param {String} data HTML string.
- * @returns {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment|null} Converted view element.
+ * @param {String} data An HTML string.
+ * @returns {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment|null} A converted view element.
  */
  toView( data ) {
  // Convert input HTML data to DOM DocumentFragment.
@@ -79,8 +79,8 @@ export default class HtmlDataProcessor {
  }
 
  /**
- * Converts HTML String to its DOM representation. Returns DocumentFragment, containing nodes parsed from
- * provided data.
+ * Converts an HTML string to its DOM representation. Returns a document fragment containing nodes parsed from
+ * the provided data.
  *
  * @private
  * @param {String} data

src/dataprocessor/htmlwriter.js

@@ -8,13 +8,13 @@
  */
 
 /**
- * HTML writer interface.
+ * The HTML writer interface.
  *
  * @interface module:engine/dataprocessor/htmlwriter~HtmlWriter
  */
 
 /**
- * Returns HTML string created from DocumentFragment.
+ * Returns an HTML string created from a document fragment.
  *
  * @method module:engine/dataprocessor/htmlwriter~HtmlWriter#getHtml
  * @param {DocumentFragment} fragment