From 4a2689e9142a3e12c00f2204cd71103876491d12 Mon Sep 17 00:00:00 2001 From: Anna Tomanek Date: Wed, 31 Jan 2018 14:07:35 +0100 Subject: [PATCH 1/2] Docs: Controller API docs revised. [skip ci] --- src/controller/datacontroller.js | 42 ++++++++++++++--------------- src/controller/editingcontroller.js | 12 ++++----- 2 files changed, 27 insertions(+), 27 deletions(-) diff --git a/src/controller/datacontroller.js b/src/controller/datacontroller.js index 5b126d602..aff0ea868 100644 --- a/src/controller/datacontroller.js +++ b/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,7 +61,7 @@ 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} @@ -68,8 +69,8 @@ export default class DataController { 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 {String} [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. diff --git a/src/controller/editingcontroller.js b/src/controller/editingcontroller.js index 4a22ae8c2..58eefdd77 100644 --- a/src/controller/editingcontroller.js +++ b/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,7 +57,7 @@ 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} @@ -65,9 +65,9 @@ export default class EditingController { 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 ); * From 4331e01d3a5cce6e2364ded9a4d02ebef3ed6839 Mon Sep 17 00:00:00 2001 From: Anna Tomanek Date: Wed, 31 Jan 2018 15:02:32 +0100 Subject: [PATCH 2/2] Docs: Data processor API docs revised. [skip ci] --- src/dataprocessor/basichtmlwriter.js | 6 ++-- src/dataprocessor/dataprocessor.jsdoc | 14 +++++----- src/dataprocessor/htmldataprocessor.js | 26 +++++++++--------- src/dataprocessor/htmlwriter.js | 4 +-- src/dataprocessor/xmldataprocessor.js | 38 +++++++++++++------------- 5 files changed, 44 insertions(+), 44 deletions(-) diff --git a/src/dataprocessor/basichtmlwriter.js b/src/dataprocessor/basichtmlwriter.js index e84169ed2..04d4fd43d 100644 --- a/src/dataprocessor/basichtmlwriter.js +++ b/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} diff --git a/src/dataprocessor/dataprocessor.jsdoc b/src/dataprocessor/dataprocessor.jsdoc index c217b7f5f..4cfbd0519 100644 --- a/src/dataprocessor/dataprocessor.jsdoc +++ b/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} */ diff --git a/src/dataprocessor/htmldataprocessor.js b/src/dataprocessor/htmldataprocessor.js index d3c4f4d87..200237c16 100644 --- a/src/dataprocessor/htmldataprocessor.js +++ b/src/dataprocessor/htmldataprocessor.js @@ -14,18 +14,18 @@ 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} @@ -33,7 +33,7 @@ export default class HtmlDataProcessor { 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 @@ -41,7 +41,7 @@ export default class HtmlDataProcessor { 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 diff --git a/src/dataprocessor/htmlwriter.js b/src/dataprocessor/htmlwriter.js index 178791202..3bde4e392 100644 --- a/src/dataprocessor/htmlwriter.js +++ b/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 diff --git a/src/dataprocessor/xmldataprocessor.js b/src/dataprocessor/xmldataprocessor.js index 8e7f4ec19..2984a1666 100644 --- a/src/dataprocessor/xmldataprocessor.js +++ b/src/dataprocessor/xmldataprocessor.js @@ -14,26 +14,26 @@ import DomConverter from '../view/domconverter'; import { NBSP_FILLER } from '../view/filler'; /** - * XmlDataProcessor class. - * This data processor implementation uses XML as input/output data. + * The XML data processor class. + * This data processor implementation uses XML as input and output data. * This class is needed because unlike HTML, XML allows to use any tag with any value. - * E.g. `Text` is a valid XML but invalid HTML. + * For example, `Text` is a valid XML but invalid HTML. * * @implements module:engine/dataprocessor/dataprocessor~DataProcessor */ export default class XmlDataProcessor { /** - * Creates a new instance of the XmlDataProcessor class. + * Creates a new instance of the XML data processor class. * * @param {Object} options Configuration options. - * @param {Array} [options.namespaces=[]] List of namespaces allowed to use in XML input. + * @param {Array} [options.namespaces=[]] A list of namespaces allowed to use in the XML input. */ constructor( options = {} ) { /** - * List of namespaces allowed to use in XML input. + * A list of namespaces allowed to use in the XML input. * - * E.g. Registering namespaces [ 'attribute', 'container' ] allows to use `` and - * `` input. It is mainly for debugging. + * For example, registering namespaces [ 'attribute', 'container' ] allows to use `` + * and `` input. It is mainly for debugging. * * @public * @member {DOMParser} @@ -41,7 +41,7 @@ export default class XmlDataProcessor { this.namespaces = options.namespaces || []; /** - * DOMParser instance used to parse XML string to XMLDocument. + * DOM parser instance used to parse an XML string to an XML document. * * @private * @member {DOMParser} @@ -57,8 +57,8 @@ export default class XmlDataProcessor { this._domConverter = new DomConverter( { blockFiller: NBSP_FILLER } ); /** - * BasicHtmlWriter instance used to convert DOM elements to XML string. - * There is no need to use dedicated for XML writer because BasicHtmlWriter works well in this case. + * A basic HTML writer instance used to convert DOM elements to an XML string. + * There is no need to use a dedicated XML writer because the basic HTML writer works well in this case. * * @private * @member {module:engine/dataprocessor/basichtmlwriter~BasicHtmlWriter} @@ -67,11 +67,11 @@ export default class XmlDataProcessor { } /** - * Converts provided {@link module:engine/view/documentfragment~DocumentFragment DocumentFragment} - * to data format- in this case XML string. + * Converts the provided {@link module:engine/view/documentfragment~DocumentFragment document fragment} + * to data format — in this case an XML string. * * @param {module:engine/view/documentfragment~DocumentFragment} viewFragment - * @returns {String} XML string. + * @returns {String} An XML string. */ toData( viewFragment ) { // Convert view DocumentFragment to DOM DocumentFragment. @@ -83,10 +83,10 @@ export default class XmlDataProcessor { } /** - * Converts provided XML string to view tree. + * Converts the provided XML string to a view tree. * - * @param {String} data XML string. - * @returns {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment|null} Converted view element. + * @param {String} data An XML string. + * @returns {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment|null} A converted view element. */ toView( data ) { // Convert input XML data to DOM DocumentFragment. @@ -97,8 +97,8 @@ export default class XmlDataProcessor { } /** - * Converts XML String to its DOM representation. Returns DocumentFragment, containing nodes parsed from - * provided data. + * Converts an XML string to its DOM representation. Returns a document fragment containing nodes parsed from + * the provided data. * * @private * @param {String} data