8
0
Просмотр исходного кода

Docs: Data processor API docs revised. [skip ci]

Anna Tomanek 8 лет назад
Родитель
Сommit
15587c4475

+ 3 - 3
packages/ckeditor5-engine/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}

+ 7 - 7
packages/ckeditor5-engine/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}
  */

+ 13 - 13
packages/ckeditor5-engine/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

+ 2 - 2
packages/ckeditor5-engine/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

+ 19 - 19
packages/ckeditor5-engine/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. `<link>Text</link>` is a valid XML but invalid HTML.
+ * For example, `<link>Text</link>` 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<String>} [options.namespaces=[]] List of namespaces allowed to use in XML input.
+	 * @param {Array<String>} [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 `<attirbute:tagName></attribute:tagName>` and
-		 * `<container:tagName></container:tagName>` input. It is mainly for debugging.
+		 * For example, registering namespaces [ 'attribute', 'container' ] allows to use `<attirbute:tagName></attribute:tagName>`
+		 * and `<container:tagName></container:tagName>` 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 &mdash; 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