Merge pull request #1328 from ckeditor/t/738

Other: Methods which modify the model's and view's tree are now protected and shouldn't be used directly in the code. Iinstance of `Writer` should be used instead. Closes #738.

src/controller/datacontroller.js

@@ -66,6 +66,7 @@ export default class DataController {
 		 * cleared directly after the data are converted. However, the mapper is defined as a class property, because
 		 * it needs to be passed to the `DowncastDispatcher` as a conversion API.
 		 *
+		 * @readonly
 		 * @member {module:engine/conversion/mapper~Mapper}
 		 */
 		this.mapper = new Mapper();

src/conversion/conversion.js

@@ -29,6 +29,10 @@ export default class Conversion {
 	 * Creates new Conversion instance.
 	 */
 	constructor() {
+		/**
+		 * @private
+		 * @member {Map}
+		 */
 		this._dispatchersGroups = new Map();
 	}
 

src/dataprocessor/htmldataprocessor.js

@@ -36,7 +36,7 @@ export default class HtmlDataProcessor {
 		 * A DOM converter used to convert DOM elements to view elements.
 		 *
 		 * @private
-		 * @member
+		 * @member {module:engine/view/domconverter~DomConverter}
 		 */
 		this._domConverter = new DomConverter( { blockFiller: NBSP_FILLER } );
 

src/dev-utils/view.js

@@ -322,10 +322,10 @@ export function parse( data, options = {} ) {
 	// If custom root is provided - move all nodes there.
 	if ( options.rootElement ) {
 		const root = options.rootElement;
-		const nodes = view.removeChildren( 0, view.childCount );
+		const nodes = view._removeChildren( 0, view.childCount );
 
-		root.removeChildren( 0, root.childCount );
-		root.appendChildren( nodes );
+		root._removeChildren( 0, root.childCount );
+		root._appendChildren( nodes );
 
 		view = root;
 	}
@@ -350,7 +350,7 @@ export function parse( data, options = {} ) {
 
 	// If single element is returned without selection - remove it from parent and return detached element.
 	if ( view.parent ) {
-		view.remove();
+		view._remove();
 	}
 
 	return view;
@@ -449,13 +449,13 @@ class RangeParser {
 			}
 
 			text = text.replace( regexp, '' );
-			node.data = text;
+			node._data = text;
 			const index = node.index;
 			const parent = node.parent;
 
 			// Remove empty text nodes.
 			if ( !text ) {
-				node.remove();
+				node._remove();
 			}
 
 			for ( const item of brackets ) {
@@ -887,7 +887,7 @@ function _convertViewElements( rootNode ) {
 				throw new Error( 'Parse error - cannot parse inside UIElement.' );
 			}
 
-			convertedElement.appendChildren( _convertViewElements( child ) );
+			convertedElement._appendChildren( _convertViewElements( child ) );
 		}
 
 		return convertedElement;

src/model/delta/basic-transformations.js

@@ -369,9 +369,9 @@ addTransformationCase( SplitDelta, AttributeDelta, ( a, b, context ) => {
 	for ( const operation of b.operations ) {
 		if ( operation.range.containsPosition( splitPosition ) || operation.range.start.isEqual( splitPosition ) ) {
 			if ( operation.newValue !== null ) {
-				a._cloneOperation.nodes.getNode( 0 ).setAttribute( operation.key, operation.newValue );
+				a._cloneOperation.nodes.getNode( 0 )._setAttribute( operation.key, operation.newValue );
 			} else {
-				a._cloneOperation.nodes.getNode( 0 ).removeAttribute( operation.key );
+				a._cloneOperation.nodes.getNode( 0 )._removeAttribute( operation.key );
 			}
 
 			break;

src/model/documentfragment.js

@@ -25,6 +25,10 @@ export default class DocumentFragment {
 	/**
 	 * Creates an empty `DocumentFragment`.
 	 *
+	 * **Note:** Constructor of this class shouldn't be used directly in the code.
+	 * Use the {@link module:engine/model/writer~Writer#createDocumentFragment} method instead.
+	 *
+	 * @protected
 	 * @param {module:engine/model/node~Node|Iterable.<module:engine/model/node~Node>} [children]
 	 * Nodes to be contained inside the `DocumentFragment`.
 	 */
@@ -34,6 +38,7 @@ export default class DocumentFragment {
 		 * which will be set as Markers to {@link module:engine/model/model~Model#markers model markers collection}
 		 * when DocumentFragment will be inserted to the document.
 		 *
+		 * @readonly
 		 * @member {Map<String,module:engine/model/range~Range>} module:engine/model/documentfragment~DocumentFragment#markers
 		 */
 		this.markers = new Map();
@@ -47,7 +52,7 @@ export default class DocumentFragment {
 		this._children = new NodeList();
 
 		if ( children ) {
-			this.insertChildren( 0, children );
+			this._insertChildren( 0, children );
 		}
 	}
 
@@ -217,92 +222,95 @@ export default class DocumentFragment {
 	}
 
 	/**
-	 * {@link #insertChildren Inserts} one or more nodes at the end of this document fragment.
+	 * Converts `DocumentFragment` instance to plain object and returns it.
+	 * Takes care of converting all of this document fragment's children.
+	 *
+	 * @returns {Object} `DocumentFragment` instance converted to plain object.
+	 */
+	toJSON() {
+		const json = [];
+
+		for ( const node of this._children ) {
+			json.push( node.toJSON() );
+		}
+
+		return json;
+	}
+
+	/**
+	 * Creates a `DocumentFragment` instance from given plain object (i.e. parsed JSON string).
+	 * Converts `DocumentFragment` children to proper nodes.
+	 *
+	 * @param {Object} json Plain object to be converted to `DocumentFragment`.
+	 * @returns {module:engine/model/documentfragment~DocumentFragment} `DocumentFragment` instance created using given plain object.
+	 */
+	static fromJSON( json ) {
+		const children = [];
+
+		for ( const child of json ) {
+			if ( child.name ) {
+				// If child has name property, it is an Element.
+				children.push( Element.fromJSON( child ) );
+			} else {
+				// Otherwise, it is a Text node.
+				children.push( Text.fromJSON( child ) );
+			}
+		}
+
+		return new DocumentFragment( children );
+	}
+
+	/**
+	 * {@link #_insertChildren Inserts} one or more nodes at the end of this document fragment.
 	 *
+	 * @protected
 	 * @param {module:engine/model/item~Item|Iterable.<module:engine/model/item~Item>} items Items to be inserted.
 	 */
-	appendChildren( items ) {
-		this.insertChildren( this.childCount, items );
+	_appendChildren( items ) {
+		this._insertChildren( this.childCount, items );
 	}
 
 	/**
 	 * Inserts one or more nodes at the given index and sets {@link module:engine/model/node~Node#parent parent} of these nodes
 	 * to this document fragment.
 	 *
+	 * @protected
 	 * @param {Number} index Index at which nodes should be inserted.
 	 * @param {module:engine/model/item~Item|Iterable.<module:engine/model/item~Item>} items Items to be inserted.
 	 */
-	insertChildren( index, items ) {
+	_insertChildren( index, items ) {
 		const nodes = normalize( items );
 
 		for ( const node of nodes ) {
 			// If node that is being added to this element is already inside another element, first remove it from the old parent.
 			if ( node.parent !== null ) {
-				node.remove();
+				node._remove();
 			}
 
 			node.parent = this;
 		}
 
-		this._children.insertNodes( index, nodes );
+		this._children._insertNodes( index, nodes );
 	}
 
 	/**
 	 * Removes one or more nodes starting at the given index
 	 * and sets {@link module:engine/model/node~Node#parent parent} of these nodes to `null`.
 	 *
+	 * @protected
 	 * @param {Number} index Index of the first node to remove.
 	 * @param {Number} [howMany=1] Number of nodes to remove.
 	 * @returns {Array.<module:engine/model/node~Node>} Array containing removed nodes.
 	 */
-	removeChildren( index, howMany = 1 ) {
-		const nodes = this._children.removeNodes( index, howMany );
+	_removeChildren( index, howMany = 1 ) {
+		const nodes = this._children._removeNodes( index, howMany );
 
 		for ( const node of nodes ) {
 			node.parent = null;
 		}
 
 		return nodes;
 	}
-
-	/**
-	 * Converts `DocumentFragment` instance to plain object and returns it.
-	 * Takes care of converting all of this document fragment's children.
-	 *
-	 * @returns {Object} `DocumentFragment` instance converted to plain object.
-	 */
-	toJSON() {
-		const json = [];
-
-		for ( const node of this._children ) {
-			json.push( node.toJSON() );
-		}
-
-		return json;
-	}
-
-	/**
-	 * Creates a `DocumentFragment` instance from given plain object (i.e. parsed JSON string).
-	 * Converts `DocumentFragment` children to proper nodes.
-	 *
-	 * @param {Object} json Plain object to be converted to `DocumentFragment`.
-	 * @returns {module:engine/model/documentfragment~DocumentFragment} `DocumentFragment` instance created using given plain object.
-	 */
-	static fromJSON( json ) {
-		const children = [];
-
-		for ( const child of json ) {
-			if ( child.name ) {
-				// If child has name property, it is an Element.
-				children.push( Element.fromJSON( child ) );
-			} else {
-				// Otherwise, it is a Text node.
-				children.push( Text.fromJSON( child ) );
-			}
-		}
-
-		return new DocumentFragment( children );
-	}
 }
 
 // Converts strings to Text and non-iterables to arrays.