Merge b0aa93b into 18bab70

src/dev-utils/view.js

@@ -113,42 +113,44 @@ setData._parse = parse;
  * Converts view elements to HTML-like string representation.
  * A root element can be provided as {@link module:engine/view/text~Text text}:
  *
- *		const text = new Text( 'foobar' );
+ *		const text = downcastWriter.createText( 'foobar' );
  *		stringify( text ); // 'foobar'
  *
  * or as an {@link module:engine/view/element~Element element}:
  *
- *		const element = new Element( 'p', null, new Text( 'foobar' ) );
+ *		const element = downcastWriter.createElement( 'p', null, downcastWriter.createText( 'foobar' ) );
  *		stringify( element ); // '<p>foobar</p>'
  *
  * or as a {@link module:engine/view/documentfragment~DocumentFragment document fragment}:
  *
- *		const text = new Text( 'foobar' );
- *		const b = new Element( 'b', { name: 'test' }, text );
- *		const p = new Element( 'p', { style: 'color:red;' } );
- *		const fragment = new DocumentFragment( [ p, b ] );
+ *		const text = downcastWriter.createText( 'foobar' );
+ *		const b = downcastWriter.createElement( 'b', { name: 'test' }, text );
+ *		const p = downcastWriter.createElement( 'p', { style: 'color:red;' } );
+ *		const fragment = downcastWriter.createDocumentFragment( [ p, b ] );
  *
  *		stringify( fragment ); // '<p style="color:red;"></p><b name="test">foobar</b>'
  *
  * Additionally, a {@link module:engine/view/documentselection~DocumentSelection 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 );
- *		const p = new Element( 'p', null, b );
- *		const selection = new Selection(
- *			Range._createFromParentsAndOffsets( p, 0, p, 1 )
+ *		const text = downcastWriter.createText( 'foobar' );
+ *		const b = downcastWriter.createElement( 'b', null, text );
+ *		const p = downcastWriter.createElement( 'p', null, b );
+ *		const selection = downcastWriter.createSelection(
+ *			downcastWriter.createRangeIn( p )
  *		);
  *
  *		stringify( p, selection ); // '<p>[<b>foobar</b>]</p>'
  *
  * 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 );
- *		const p = new Element( 'p', null, b );
- *		const selection = new Selection( Range._createFromParentsAndOffsets( text, 1, text, 5 ) );
+ *		const text = downcastWriter.createText( 'foobar' );
+ *		const b = downcastWriter.createElement( 'b', null, text );
+ *		const p = downcastWriter.createElement( 'p', null, b );
+ *		const selection = downcastWriter.createSelection(
+ *			downcastWriter.createRange( downcastWriter.createPositionAt( text, 1 ), downcastWriter.createPositionAt( text, 5 ) )
+ *		);
  *
  *		stringify( p, selection ); // '<p><b>f{ooba}r</b></p>'
  *
@@ -159,10 +161,10 @@ setData._parse = parse;
  *
  * Multiple ranges are supported:
  *
- *		const text = new Text( 'foobar' );
- *		const selection = new Selection( [
- *			Range._createFromParentsAndOffsets( text, 0, text, 1 ) ),
- *			Range._createFromParentsAndOffsets( text, 3, text, 5 ) )
+ *		const text = downcastWriter.createText( 'foobar' );
+ *		const selection = downcastWriter.createSelection( [
+ *			downcastWriter.createRange( downcastWriter.createPositionAt( text, 0 ), downcastWriter.createPositionAt( text, 1 ) ),
+ *			downcastWriter.createRange( downcastWriter.createPositionAt( text, 3 ), downcastWriter.createPositionAt( text, 5 ) )
  *		] );
  *
  *		stringify( text, selection ); // '{f}oo{ba}r'
@@ -172,9 +174,9 @@ setData._parse = parse;
  * 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' );
- *		const range = Range._createFromParentsAndOffsets( text, 0, text, 1 );
- *		const position = new Position( text, 3 );
+ *		const text = downcastWriter.createText( 'foobar' );
+ *		const range = downcastWriter.createRange( downcastWriter.createPositionAt( text, 0 ), downcastWriter.createPositionAt( text, 1 ) );
+ *		const position = downcastWriter.createPositionAt( text, 3 );
  *
  *		stringify( text, range ); // '{f}oobar'
  *		stringify( text, position ); // 'foo{}bar'
@@ -186,10 +188,10 @@ setData._parse = parse;
  * {@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' );
- *		const empty = new EmptyElement( 'img' );
- *		const ui = new UIElement( 'span' );
+ *		const attribute = downcastWriter.createAttributeElement( 'b' );
+ *		const container = downcastWriter.createContainerElement( 'p' );
+ *		const empty = downcastWriter.createEmptyElement( 'img' );
+ *		const ui = downcastWriter.createUIElement( 'span' );
  *		getData( attribute, null, { showType: true } ); // '<attribute:b></attribute:b>'
  *		getData( container, null, { showType: true } ); // '<container:p></container:p>'
  *		getData( empty, null, { showType: true } ); // '<empty:img></empty:img>'
@@ -198,14 +200,14 @@ setData._parse = parse;
  * 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' );
+ *		const attribute = downcastWriter.createAttributeElement( 'b' );
  *		attribute._priority = 20;
  *		getData( attribute, null, { showPriority: true } ); // <b view-priority="20"></b>
  *
  * If `options.showAttributeElementId` is set to `true`, the attribute element's id will be displayed for all
  * {@link module:engine/view/attributeelement~AttributeElement attribute elements} that have it set.
  *
- *		const attribute = new AttributeElement( 'span' );
+ *		const attribute = downcastWriter.createAttributeElement( 'span' );
  *		attribute._id = 'marker:foo';
  *		getData( attribute, null, { showAttributeElementId: true } ); // <span view-id="marker:foo"></span>
  *

src/view/attributeelement.js

@@ -21,15 +21,18 @@ const DEFAULT_PRIORITY = 10;
  * be defined by the feature developer. Creating an element you should use {@link module:engine/view/containerelement~ContainerElement}
  * class or `AttributeElement`.
  *
+ * The constructor of this class shouldn't be used directly. To create new `AttributeElement` use the
+ * {@link module:engine/view/downcastwriter~DowncastWriter#createAttributeElement `downcastWriter#createAttributeElement()`} method.
+ *
  * @extends module:engine/view/element~Element
  */
 export default class AttributeElement extends Element {
 	/**
-	 * Creates a attribute element.
+	 * Creates an attribute element.
 	 *
 	 * @see module:engine/view/downcastwriter~DowncastWriter#createAttributeElement
-	 * @protected
 	 * @see module:engine/view/element~Element
+	 * @protected
 	 */
 	constructor( name, attrs, children ) {
 		super( name, attrs, children );

src/view/containerelement.js

@@ -16,6 +16,10 @@ import Element from './element';
  * Editing engine does not define fixed HTML DTD. This is why the type of the {@link module:engine/view/element~Element} need to
  * be defined by the feature developer.
  *
+ * To create new `ContainerElement`
+ * {@link module:engine/view/downcastwriter~DowncastWriter#createContainerElement `DowncastWriter#createContainerElement()`}
+ * method should be used.
+ *
  * Creating an element you should use `ContainerElement` class or {@link module:engine/view/attributeelement~AttributeElement}. This is
  * important to define the type of the element because of two reasons:
  *
@@ -47,8 +51,8 @@ export default class ContainerElement extends Element {
 	/**
 	 * Creates a container element.
 	 *
-	 * @see module:engine/view/element~Element
 	 * @see module:engine/view/downcastwriter~DowncastWriter#createContainerElement
+	 * @see module:engine/view/element~Element
 	 * @protected
 	 */
 	constructor( name, attrs, children ) {

src/view/documentfragment.js

@@ -15,14 +15,18 @@ import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
 
 /**
  * DocumentFragment class.
+ *
+ * The constructor of this class shouldn't be used directly. To create new DocumentFragment instance use the
+ * {@link module:engine/view/upcastwriter~UpcastWriter#createDocumentFragment `UpcastWriter#createDocumentFragment()`}
+ * method instead.
  */
 export default class DocumentFragment {
 	/**
 	 * Creates new DocumentFragment instance.
 	 *
 	 * @protected
-	 * @param {module:engine/view/node~Node|Iterable.<module:engine/view/node~Node>} [children] List of nodes to be inserted into
-	 * created document fragment.
+	 * @param {module:engine/view/node~Node|Iterable.<module:engine/view/node~Node>} [children]
+	 * A list of nodes to be inserted into the created document fragment.
 	 */
 	constructor( children ) {
 		/**

src/view/downcastwriter.js

@@ -141,8 +141,8 @@ export default class DowncastWriter {
 	 *
 	 *		writer.createText( 'foo' );
 	 *
-	 * @param {String} data Text data.
-	 * @returns {module:engine/view/text~Text} Created text node.
+	 * @param {String} data The text's data.
+	 * @returns {module:engine/view/text~Text} The created text node.
 	 */
 	createText( data ) {
 		return new Text( data );

src/view/editableelement.js

@@ -20,6 +20,9 @@ const documentSymbol = Symbol( 'document' );
  *
  * Editable is automatically read-only when its {@link module:engine/view/document~Document Document} is read-only.
  *
+ * The constructor of this class shouldn't be used directly. To create new `EditableElement` use the
+ * {@link module:engine/view/downcastwriter~DowncastWriter#createEditableElement `downcastWriter#createEditableElement()`} method.
+ *
  * @extends module:engine/view/containerelement~ContainerElement
  * @mixes module:utils/observablemixin~ObservableMixin
  */

src/view/element.js

@@ -22,20 +22,21 @@ import { isPlainObject } from 'lodash-es';
  * This is why the type of the {@link module:engine/view/element~Element} need to
  * be defined by the feature developer. When creating an element you should use one of the following methods:
  *
- * * {@link module:engine/view/downcastwriter~DowncastWriter#createContainerElement `writer.createContainerElement()`} in order to create
- * a {@link module:engine/view/containerelement~ContainerElement},
- * * {@link module:engine/view/downcastwriter~DowncastWriter#createAttributeElement `writer.createAttributeElement()`} in order to create
- * a {@link module:engine/view/attributeelement~AttributeElement},
- * * {@link module:engine/view/downcastwriter~DowncastWriter#createEmptyElement `writer.createEmptyElement()`} in order to create
- * a {@link module:engine/view/emptyelement~EmptyElement}.
- * * {@link module:engine/view/downcastwriter~DowncastWriter#createUIElement `writer.createUIElement()`} in order to create
- * a {@link module:engine/view/uielement~UIElement}.
- * * {@link module:engine/view/downcastwriter~DowncastWriter#createEditableElement `writer.createEditableElement()`} in order to create
- * a {@link module:engine/view/editableelement~EditableElement}.
+ * * {@link module:engine/view/downcastwriter~DowncastWriter#createContainerElement `downcastWriter#createContainerElement()`}
+ * in order to create a {@link module:engine/view/containerelement~ContainerElement},
+ * * {@link module:engine/view/downcastwriter~DowncastWriter#createAttributeElement `downcastWriter#createAttributeElement()`}
+ * in order to create a {@link module:engine/view/attributeelement~AttributeElement},
+ * * {@link module:engine/view/downcastwriter~DowncastWriter#createEmptyElement `downcastWriter#createEmptyElement()`}
+ * in order to create a {@link module:engine/view/emptyelement~EmptyElement}.
+ * * {@link module:engine/view/downcastwriter~DowncastWriter#createUIElement `downcastWriter#createUIElement()`}
+ * in order to create a {@link module:engine/view/uielement~UIElement}.
+ * * {@link module:engine/view/downcastwriter~DowncastWriter#createEditableElement `downcastWriter#createEditableElement()`}
+ * in order to create a {@link module:engine/view/editableelement~EditableElement}.
  *
  * Note that for view elements which are not created from the model, like elements from mutations, paste or
- * {@link module:engine/controller/datacontroller~DataController#set data.set} it is not possible to define the type of the element, so
- * these will be instances of the {@link module:engine/view/element~Element}.
+ * {@link module:engine/controller/datacontroller~DataController#set data.set} it is not possible to define the type of the element.
+ * In such cases the {@link module:engine/view/upcastwriter~UpcastWriter#createElement `UpcastWriter#createElement()`} method
+ * should be used to create generic view elements.
  *
  * @extends module:engine/view/node~Node
  */
@@ -45,22 +46,15 @@ export default class Element extends Node {
 	 *
 	 * Attributes can be passed in various formats:
 	 *
-	 *		new Element( 'div', { 'class': 'editor', 'contentEditable': 'true' } ); // object
+	 *		new Element( 'div', { class: 'editor', contentEditable: 'true' } ); // object
 	 *		new Element( 'div', [ [ 'class', 'editor' ], [ 'contentEditable', 'true' ] ] ); // map-like iterator
 	 *		new Element( 'div', mapOfAttributes ); // map
 	 *
-	 * **Note:** Constructor of this class shouldn't be used directly in the code. Use the
-	 * {@link module:engine/view/downcastwriter~DowncastWriter#createAttributeElement} for inline element,
-	 * {@link module:engine/view/downcastwriter~DowncastWriter#createContainerElement} for block element,
-	 * {@link module:engine/view/downcastwriter~DowncastWriter#createEditableElement} for editable element,
-	 * {@link module:engine/view/downcastwriter~DowncastWriter#createEmptyElement} for empty element or
-	 * {@link module:engine/view/downcastwriter~DowncastWriter#createUIElement} for UI element instead.
-	 *
 	 * @protected
 	 * @param {String} name Node name.
 	 * @param {Object|Iterable} [attrs] Collection of attributes.
 	 * @param {module:engine/view/node~Node|Iterable.<module:engine/view/node~Node>} [children]
-	 * List of nodes to be inserted into created element.
+	 * A list of nodes to be inserted into created element.
 	 */
 	constructor( name, attrs, children ) {
 		super();

src/view/emptyelement.js

@@ -12,7 +12,10 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 import Node from './node';
 
 /**
- * EmptyElement class. It is used to represent elements that cannot contain any child nodes.
+ * EmptyElement class. It is used to represent elements that cannot contain any child nodes (for example `<img>` elements).
+ *
+ * The constructor of this class shouldn't be used directly. To create new `EmptyElement` use the
+ * {@link module:engine/view/downcastwriter~DowncastWriter#createEmptyElement `downcastWriter#createEmptyElement()`} method.
  */
 export default class EmptyElement extends Element {
 	/**

src/view/node.js

@@ -16,13 +16,15 @@ import { clone } from 'lodash-es';
 /**
  * Abstract tree view node class.
  *
+ * This is an abstract class. Its constructor should not be used directly.
+ * Use the {@link module:engine/view/element~Element} class to create view elements
+ * or {@link module:engine/view/text~Text} class to create view text nodes.
+ *
  * @abstract
  */
 export default class Node {
 	/**
 	 * Creates a tree view node.
-	 *
-	 * This is an abstract class, so this constructor should not be used directly.
 	 */
 	constructor() {
 		/**
@@ -123,11 +125,11 @@ export default class Node {
 	 * Gets a path to the node. The path is an array containing indices of consecutive ancestors of this node,
 	 * beginning from {@link module:engine/view/node~Node#root root}, down to this node's index.
 	 *
-	 *		const abc = new Text( 'abc' );
-	 *		const foo = new Text( 'foo' );
-	 *		const h1 = new Element( 'h1', null, new Text( 'header' ) );
-	 *		const p = new Element( 'p', null, [ abc, foo ] );
-	 *		const div = new Element( 'div', null, [ h1, p ] );
+	 *		const abc = downcastWriter.createText( 'abc' );
+	 *		const foo = downcastWriter.createText( 'foo' );
+	 *		const h1 = downcastWriter.createElement( 'h1', null, downcastWriter.createText( 'header' ) );
+	 *		const p = downcastWriter.createElement( 'p', null, [ abc, foo ] );
+	 *		const div = downcastWriter.createElement( 'div', null, [ h1, p ] );
 	 *		foo.getPath(); // Returns [ 1, 3 ]. `foo` is in `p` which is in `div`. `p` starts at offset 1, while `foo` at 3.
 	 *		h1.getPath(); // Returns [ 0 ].
 	 *		div.getPath(); // Returns [].

src/view/range.js

@@ -205,10 +205,10 @@ export default class Range {
 	 *
 	 * Examples:
 	 *
-	 *		let foo = new Text( 'foo' );
-	 *		let img = new ContainerElement( 'img' );
-	 *		let bar = new Text( 'bar' );
-	 *		let p = new ContainerElement( 'p', null, [ foo, img, bar ] );
+	 *		let foo = downcastWriter.createText( 'foo' );
+	 *		let img = downcastWriter.createContainerElement( 'img' );
+	 *		let bar = downcastWriter.createText( 'bar' );
+	 *		let p = downcastWriter.createContainerElement( 'p', null, [ foo, img, bar ] );
 	 *
 	 *		let range = view.createRange( view.createPositionAt( foo, 2 ), view.createPositionAt( bar, 1 ); // "o", img, "b" are in range.
 	 *		let otherRange = view.createRange( // "oo", img, "ba" are in range.
@@ -260,10 +260,10 @@ export default class Range {
 	 *
 	 * Examples:
 	 *
-	 *		let foo = new Text( 'foo' );
-	 *		let img = new ContainerElement( 'img' );
-	 *		let bar = new Text( 'bar' );
-	 *		let p = new ContainerElement( 'p', null, [ foo, img, bar ] );
+	 *		let foo = downcastWriter.createText( 'foo' );
+	 *		let img = downcastWriter.createContainerElement( 'img' );
+	 *		let bar = downcastWriter.createText( 'bar' );
+	 *		let p = downcastWriter.createContainerElement( 'p', null, [ foo, img, bar ] );
 	 *
 	 *		let range = view.createRange( view.createPositionAt( foo, 2 ), view.createPositionAt( bar, 1 ); // "o", img, "b" are in range.
 	 *		let otherRange = view.createRange( view.createPositionAt( foo, 1 ), view.createPositionAt( p, 2 ); // "oo", img are in range.

src/view/text.js

@@ -12,17 +12,20 @@ import Node from './node';
 /**
  * Tree view text node.
  *
+ * The constructor of this class shouldn't be used directly. To create new Text instances
+ * use the {@link module:engine/view/downcastwriter~DowncastWriter#createText `DowncastWriter#createText()`}
+ * method when working on data downcasted from the model or the
+ * {@link module:engine/view/upcastwriter~UpcastWriter#createText `UpcastWriter#createText()`}
+ * method when working on non-semantic views.
+ *
  * @extends module:engine/view/node~Node
  */
 export default class Text extends Node {
 	/**
 	 * Creates a tree view text node.
 	 *
-	 * **Note:** Constructor of this class shouldn't be used directly in the code.
-	 * Use the {@link module:engine/view/downcastwriter~DowncastWriter#createText} method instead.
-	 *
 	 * @protected
-	 * @param {String} data Text.
+	 * @param {String} data The text's data.
 	 */
 	constructor( data ) {
 		super();
@@ -57,8 +60,8 @@ export default class Text extends Node {
 	/**
 	 * This getter is required when using the addition assignment operator on protected property:
 	 *
-	 *		const foo = new Text( 'foo' );
-	 *		const bar = new Text( 'bar' );
+	 *		const foo = downcastWriter.createText( 'foo' );
+	 *		const bar = downcastWriter.createText( 'bar' );
 	 *
 	 *		foo._data += bar.data;   // executes: `foo._data = foo._data + bar.data`
 	 *		console.log( foo.data ); // prints: 'foobar'