浏览代码

Typos, corrections and clarifications in the API docs.

Piotrek Koszuliński 10 年之前
父节点
当前提交
f5e3e89862

+ 14 - 14
packages/ckeditor5-utils/src/document/attribute.js

@@ -13,7 +13,7 @@ CKEDITOR.define( [ 'utils' ], function( utils ) {
 	 */
 	class Attribute {
 		/**
-		 * Create a new attribute class. Once attribute is created it should not be modified.
+		 * Creates a new instance of the `Attribute` class. Once attribute is created it is immutable.
 		 *
 		 * @param {String} key Attribute key.
 		 * @param {Mixed} value Attribute value.
@@ -37,7 +37,7 @@ CKEDITOR.define( [ 'utils' ], function( utils ) {
 			this.value = value;
 
 			/**
-			 * Attribute hash. Used to compare attribute. Two attributes with the same key and value will have the same hash.
+			 * Attribute hash. Used to compare attributes. Two attributes with the same key and value will have the same hash.
 			 *
 			 * @readonly
 			 * @private
@@ -45,7 +45,7 @@ CKEDITOR.define( [ 'utils' ], function( utils ) {
 			 */
 			this._hash = this.key + ': ' + JSON.stringify( this.value, sort );
 
-			// If attribute is registered the registered one should be returned.
+			// If attribute is already registered the registered one should be returned.
 			if ( Attribute._register[ this._hash ] ) {
 				return Attribute._register[ this._hash ];
 			}
@@ -68,15 +68,15 @@ CKEDITOR.define( [ 'utils' ], function( utils ) {
 		}
 
 		/**
-		 * Compare two attributes. Returns true if two attributes have the same key and value even if the order of value
-		 * elements is different.
+		 * Compares two attributes. Returns `true` if two attributes have the same key and value even if the order of keys
+		 * in the value object is different.
 		 *
-		 *	var attr1 = new Attribute( 'foo', { a: 1, b: 2 } );
-		 *	var attr2 = new Attribute( 'foo', { b: 2, a: 1 } );
-		 *	attr1.isEqual( attr2 ); // true
+		 *		var attr1 = new Attribute( 'foo', { a: 1, b: 2 } );
+		 *		var attr2 = new Attribute( 'foo', { b: 2, a: 1 } );
+		 *		attr1.isEqual( attr2 ); // true
 		 *
 		 * @param {document.Attribute} otherAttr Attribute to compare with.
-		 * @returns {Boolean} True if attributes equals.
+		 * @returns {Boolean} True if attributes are equal to each other.
 		 */
 		isEqual( otherAttr ) {
 			return this._hash === otherAttr._hash;
@@ -88,11 +88,11 @@ CKEDITOR.define( [ 'utils' ], function( utils ) {
 		 *
 		 * Note that attributes are registered globally.
 		 *
-		 *	var attr1 = Attribute.register( 'bold', true );
-		 *	var attr2 = Attribute.register( 'bold', true );
-		 *	var attr3 = new Attribute( 'bold', true );
-		 *	attr1 === attr2 // true
-		 *	attr1 === attr3 // true
+		 *		var attr1 = Attribute.register( 'bold', true );
+		 *		var attr2 = Attribute.register( 'bold', true );
+		 *		var attr3 = new Attribute( 'bold', true );
+		 *		attr1 === attr2 // true
+		 *		attr1 === attr3 // true
 		 *
 		 * @static
 		 * @param {String} key Attribute key.

+ 6 - 8
packages/ckeditor5-utils/src/document/document.js

@@ -21,7 +21,7 @@ CKEDITOR.define( [
 	 */
 	class Document {
 		/**
-		 * Create an empty document.
+		 * Creates an empty document instance.
 		 *
 		 * @constructor
 		 */
@@ -34,15 +34,13 @@ CKEDITOR.define( [
 			 */
 			this.roots = new Map();
 
-			/**
-			 * Graveyard tree root. Document always have a graveyard root, which is storing removed nodes.
-			 */
+			// Graveyard tree root. Document always have a graveyard root, which stores removed nodes.
 			this.createRoot( graveyardSymbol );
 
 			/**
-			 * Document version. It starts from 0 and every operation increase the version. It is used to ensure that
-			 * operations is applied on the proper document version. If the {@link document.operations.Operation#baseVersion} will
-			 * not match document version an {@link document-applyOperation-wrong-version} error is fired.
+			 * Document version. It starts from `0` and every operation increases the version number. It is used to ensure that
+			 * operations are applied on the proper document version. If the {@link document.operations.Operation#baseVersion} will
+			 * not match document version the {@link document-applyOperation-wrong-version} error is thrown.
 			 *
 			 * @readonly
 			 * @property {Number} version
@@ -128,7 +126,7 @@ CKEDITOR.define( [
 		}
 
 		/**
-		 * Graveyard tree root. Document always have a graveyard root, which is storing removed nodes.
+		 * Graveyard tree root. Document always have a graveyard root, which stores removed nodes.
 		 *
 		 * @protected
 		 * @readonly

+ 13 - 13
packages/ckeditor5-utils/src/document/element.js

@@ -13,7 +13,7 @@ CKEDITOR.define( [ 'document/node', 'document/nodelist' ], function( Node, NodeL
 	 */
 	class Element extends Node {
 		/**
-		 * Creates tree data model element.
+		 * Creates a tree data model element.
 		 *
 		 * This constructor should be used only internally by the document.
 		 *
@@ -48,14 +48,14 @@ CKEDITOR.define( [ 'document/node', 'document/nodelist' ], function( Node, NodeL
 		}
 
 		/**
-		 * Insert a list of child nodes on the given index and set the parent of these node to this.
+		 * Inserts a list of child nodes on the given index and sets the parent of these nodes to this element.
 		 *
-		 * Note that list of children can be modified only in elements not attached yet to the document.
+		 * Note that the list of children can be modified only in elements not yet attached to the document.
 		 * All attached nodes should be modified using the {@link document.operations.InsertOperation}.
 		 *
 		 * @param {Number} index Position where nodes should be inserted.
-		 * @param {document.Node|document.Text|document.NodeList|String|Iterable} nodes List of nodes to be inserted.
-		 * List of nodes can be of any type accepted by the {@link document.NodeList} constructor.
+		 * @param {document.Node|document.Text|document.NodeList|String|Iterable} nodes The list of nodes to be inserted.
+		 * The list of nodes can be of any type accepted by the {@link document.NodeList} constructor.
 		 */
 		insertChildren( index, nodes ) {
 			this._children.insert( index, new NodeList( nodes ) );
@@ -66,14 +66,14 @@ CKEDITOR.define( [ 'document/node', 'document/nodelist' ], function( Node, NodeL
 		}
 
 		/**
-		 * Removes number of child nodes starting at the given index and set the parent of these node to null.
+		 * Removes number of child nodes starting at the given index and set the parent of these nodes to `null`.
 		 *
-		 * Note that list of children can be modified only in elements not attached yet to the document.
+		 * Note that the list of children can be modified only in elements not yet attached to the document.
 		 * All attached nodes should be modified using the {@link document.operations.RemoveOperation}.
 		 *
 		 * @param {Number} index Position of the first node to remove.
 		 * @param {Number} number Number of nodes to remove.
-		 * @returns {document.NodeList} List of removed nodes.
+		 * @returns {document.NodeList} The list of removed nodes.
 		 */
 
 		removeChildren( index, number ) {
@@ -85,7 +85,7 @@ CKEDITOR.define( [ 'document/node', 'document/nodelist' ], function( Node, NodeL
 		}
 
 		/**
-		 * Gets child at given index.
+		 * Gets child at the given index.
 		 *
 		 * @param {Number} index Index of child.
 		 * @returns {document.Node} Child node.
@@ -95,19 +95,19 @@ CKEDITOR.define( [ 'document/node', 'document/nodelist' ], function( Node, NodeL
 		}
 
 		/**
-		 * Gets index of child node.
+		 * Gets index of the given child node.
 		 *
 		 * @param {document.Node} node Child node.
-		 * @returns {Number} Index of child.
+		 * @returns {Number} Index of the child node.
 		 */
 		getChildIndex( node ) {
 			return this._children.indexOf( node );
 		}
 
 		/**
-		 * Gets number of element's children.
+		 * Gets the number of element's children.
 		 *
-		 * @returns {Number} Number of element's children.
+		 * @returns {Number} The number of element's children.
 		 */
 		getChildCount() {
 			return this._children.length;

+ 99 - 101
packages/ckeditor5-utils/src/document/node.js

@@ -9,15 +9,14 @@ CKEDITOR.define( [ 'document/attribute', 'utils' ], function( Attribute, utils )
 	/**
 	 * Abstract document tree node class.
 	 *
+	 * @abstract
 	 * @class document.Node
 	 */
 	class Node {
 		/**
-		 * Creates tree node.
+		 * Creates a tree node.
 		 *
-		 * This is an abstract class, it should not be created directly.
-		 *
-		 * Created node has no parent. Parent of the node is set when it is attached to the {@link document.Element}.
+		 * This is an abstract class, so this constructor should not be used directly.
 		 *
 		 * @param {Iterable} attrs Iterable collection of {@link document.Attribute attributes}.
 		 * @constructor
@@ -26,14 +25,15 @@ CKEDITOR.define( [ 'document/attribute', 'utils' ], function( Attribute, utils )
 			/**
 			 * Parent element. Null by default. Set by {@link document.Element#insertChildren}.
 			 *
+			 * @readonly
 			 * @property {document.Element|null} parent
 			 */
 			this.parent = null;
 
 			/**
-			 * Array of attributes.
+			 * Attributes set.
 			 *
-			 * Attributes of nodes attached to the document can be changed only be the {@link document.ChangeOpeation}.
+			 * Attributes of nodes attached to the document can be changed only be the {@link document.operations.ChangeOperation}.
 			 *
 			 * @private
 			 * @property {Set} _attrs
@@ -42,96 +42,6 @@ CKEDITOR.define( [ 'document/attribute', 'utils' ], function( Attribute, utils )
 		}
 
 		/**
-		 * Returns true if node contain attribute with the same key and value as given or the same key if the
-		 * given parameter is a string.
-		 *
-		 * @param {document.Attribute|String} attr Attribute or key to compare.
-		 * @returns {Boolean} True if node contains given attribute or attribute with given key.
-		 */
-		hasAttr( key ) {
-			var attr;
-
-			// Attribute.
-			if ( key instanceof Attribute ) {
-				for ( attr of this._attrs ) {
-					if ( attr.isEqual( key ) ) {
-						return true;
-					}
-				}
-			}
-			// Key.
-			else {
-				for ( attr of this._attrs ) {
-					if ( attr.key == key ) {
-						return true;
-					}
-				}
-			}
-
-			return false;
-		}
-
-		/**
-		 * Returns attribute if node contain attribute with the same key and value as given or the same key if the
-		 * given parameter is a string.
-		 *
-		 * @param {document.Attribute|String|null} attr Attribute or key to compare.
-		 * @returns {document.Attribute} Attribute if node contains given attribute or attribute with given key,
-		 * or null if attribute was not found.
-		 */
-		getAttr( key ) {
-			for ( var attr of this._attrs ) {
-				if ( attr.key == key ) {
-					return attr.value;
-				}
-			}
-
-			return null;
-		}
-
-		/**
-		 * Removes attribute from the list of attribute.
-		 *
-		 * @param {String} key Attribute key.
-		 */
-		removeAttr( key ) {
-			for ( var attr of this._attrs ) {
-				if ( attr.key == key ) {
-					this._attrs.delete( attr );
-
-					return;
-				}
-			}
-		}
-
-		/**
-		 * Get number of attributes.
-		 *
-		 * @protected
-		 * @returns {Number} Number of attributes.
-		 */
-		_getAttrCount() {
-			var count = 0;
-
-			for ( var attr of this._attrs ) { // jshint ignore:line
-				count++;
-			}
-
-			return count;
-		}
-
-		/**
-		 * Insert a given attribute. If the attribute with the same key already exists it will be removed.
-		 *
-		 * @param {document.Attribute} attr Attribute to insert.
-		 */
-		setAttr( attr ) {
-			this.removeAttr( attr.key );
-
-			this._attrs.add( attr );
-		}
-
-		/**
 		 * Position of the node in the parent element.
 		 *
 		 * @readonly
@@ -168,7 +78,7 @@ CKEDITOR.define( [ 'document/attribute', 'utils' ], function( Attribute, utils )
 		}
 
 		/**
-		 * The top parent for the node. If node has no parent it is its own root.
+		 * The top parent for the node. If node has no parent it is the root itself.
 		 *
 		 * @readonly
 		 * @property {Number} depth
@@ -184,7 +94,7 @@ CKEDITOR.define( [ 'document/attribute', 'utils' ], function( Attribute, utils )
 		}
 
 		/**
-		 * Nodes next sibling or null if it is the last child.
+		 * Nodes next sibling or `null` if it is the last child.
 		 *
 		 * @readonly
 		 * @property {document.Node|null} nextSibling
@@ -208,10 +118,82 @@ CKEDITOR.define( [ 'document/attribute', 'utils' ], function( Attribute, utils )
 		}
 
 		/**
-		 * Get path to the node. For example if the node is the second child of the first child of the root then the path
-		 * will be [ 1, 2 ]. This path can be used as a parameter of in {@link document.Position}.
+		 * Returns `true` if the node contains an attribute with the same key and value as given or the same key if the
+		 * given parameter is a string.
+		 *
+		 * @param {document.Attribute|String} attr An attribute or a key to compare.
+		 * @returns {Boolean} True if node contains given attribute or an attribute with the given key.
+		 */
+		hasAttr( key ) {
+			var attr;
+
+			// Attribute.
+			if ( key instanceof Attribute ) {
+				for ( attr of this._attrs ) {
+					if ( attr.isEqual( key ) ) {
+						return true;
+					}
+				}
+			}
+			// Key.
+			else {
+				for ( attr of this._attrs ) {
+					if ( attr.key == key ) {
+						return true;
+					}
+				}
+			}
+
+			return false;
+		}
+
+		/**
+		 * Finds an attribute by a key.
+		 *
+		 * @param {String} attr The attribute key.
+		 * @returns {document.Attribute} The found attribute.
+		 */
+		getAttr( key ) {
+			for ( var attr of this._attrs ) {
+				if ( attr.key == key ) {
+					return attr.value;
+				}
+			}
+
+			return null;
+		}
+
+		/**
+		 * Removes attribute from the list of attributes.
+		 *
+		 * @param {String} key The attribute key.
+		 */
+		removeAttr( key ) {
+			for ( var attr of this._attrs ) {
+				if ( attr.key == key ) {
+					this._attrs.delete( attr );
+
+					return;
+				}
+			}
+		}
+
+		/**
+		 * Sets a given attribute. If the attribute with the same key already exists it will be removed.
 		 *
-		 * @returns {Array} Path, array of numbers.
+		 * @param {document.Attribute} attr Attribute to set.
+		 */
+		setAttr( attr ) {
+			this.removeAttr( attr.key );
+
+			this._attrs.add( attr );
+		}
+
+		/**
+		 * Gets path to the node. For example if the node is the second child of the first child of the root then the path
+		 * will be `[ 1, 2 ]`. This path can be used as a parameter of {@link document.Position}.
+		 *
+		 * @returns {Number[]} The path.
 		 */
 		getPath() {
 			var path = [];
@@ -238,6 +220,22 @@ CKEDITOR.define( [ 'document/attribute', 'utils' ], function( Attribute, utils )
 
 			return json;
 		}
+
+		/**
+		 * Gets the number of attributes.
+		 *
+		 * @protected
+		 * @returns {Number} Number of attributes.
+		 */
+		_getAttrCount() {
+			var count = 0;
+
+			for ( var attr of this._attrs ) { // jshint ignore:line
+				count++;
+			}
+
+			return count;
+		}
 	}
 
 	return Node;

+ 3 - 4
packages/ckeditor5-utils/src/document/nodelist.js

@@ -61,7 +61,7 @@ CKEDITOR.define( [
 			 * Internal array to store nodes.
 			 *
 			 * @private
-			 * @property {Array} _nodes
+			 * @property {Array}
 			 */
 			this._nodes = [];
 
@@ -127,9 +127,8 @@ CKEDITOR.define( [
 		/**
 		 * Search for the node in the node list.
 		 *
-		 * @param {document.Node} node Node to found.
-		 * @returns {Number} Number representing the position where the specified search value occurs for the first time,
-		 * or -1 if it never occurs.
+		 * @param {document.Node} node Node to find.
+		 * @returns {Number} Position of the node in the list.
 		 */
 		indexOf( node ) {
 			return this._nodes.indexOf( node );

+ 20 - 26
packages/ckeditor5-utils/src/document/operations/changeoperation.js

@@ -7,7 +7,7 @@
 
 CKEDITOR.define( [ 'document/operations/operation', 'ckeditorerror' ], function( Operation, CKEditorError ) {
 	/**
-	 * Operation to change nodes attribute. Using this class you can add, remove or change value of the attribute.
+	 * Operation to change nodes' attribute. Using this class you can add, remove or change value of the attribute.
 	 *
 	 * @class document.operations.ChangeOperation
 	 */
@@ -15,19 +15,19 @@ CKEDITOR.define( [ 'document/operations/operation', 'ckeditorerror' ], function(
 		/**
 		 * Creates a change operation.
 		 *
-		 * If only new attribute is set it will be inserted. Note that there must be no attributes with the same key as
-		 * a new attribute in all nodes in ranges.
+		 * If only the new attribute is set, then it will be inserted. Note that in all nodes in ranges there must be
+		 * no attributes with the same key as the new attribute.
 		 *
-		 * If only old attribute is set it will be removed. Note that this attribute must be present in all nodes in
+		 * If only the old attribute is set, then it will be removed. Note that this attribute must be present in all nodes in
 		 * ranges.
 		 *
-		 * If both new and old attributes are set the operation will change the attribute value. Node that both new and
+		 * If both new and old attributes are set, then the operation will change the attribute value. Note that both new and
 		 * old attributes have to have the same key and the old attribute must be present in all nodes in ranges.
 		 *
-		 * @param {document.Range} range Range on which operation should be applied.
-		 * @param {document.Attribute|null} oldAttr Attribute to be removed. Null if operation just inserts a new attribute.
-		 * @param {document.Attribute|null} newAttr Attribute to be added. Null if operation just removes an attribute.
-		 * @param {Number} baseVersion {@link document.Document#version} on which operation can be applied.
+		 * @param {document.Range} range Range on which the operation should be applied.
+		 * @param {document.Attribute|null} oldAttr Attribute to be removed. If `null`, then the operation just inserts a new attribute.
+		 * @param {document.Attribute|null} newAttr Attribute to be added. If `null`, then the operation just removes the attribute.
+		 * @param {Number} baseVersion {@link document.Document#version} on which the operation can be applied.
 		 * @constructor
 		 */
 		constructor( range, oldAttr, newAttr, baseVersion ) {
@@ -42,7 +42,7 @@ CKEDITOR.define( [ 'document/operations/operation', 'ckeditorerror' ], function(
 			this.range = range;
 
 			/**
-			 * Old attribute to change. Null if operation inserts new attribute.
+			 * Old attribute to change. Set to `null` if operation inserts a new attribute.
 			 *
 			 * @readonly
 			 * @type {document.Attribute|null}
@@ -50,7 +50,7 @@ CKEDITOR.define( [ 'document/operations/operation', 'ckeditorerror' ], function(
 			this.oldAttr = oldAttr;
 
 			/**
-			 * New attribute. Null if operation removes attribute.
+			 * New attribute. Set to `null` if operation removes the attribute.
 			 *
 			 * @readonly
 			 * @type {document.Attribute|null}
@@ -58,9 +58,6 @@ CKEDITOR.define( [ 'document/operations/operation', 'ckeditorerror' ], function(
 			this.newAttr = newAttr;
 		}
 
-		/**
-		 * See {@link document.operations.Operation#_execute}.
-		 */
 		_execute() {
 			var oldAttr = this.oldAttr;
 			var newAttr = this.newAttr;
@@ -71,13 +68,13 @@ CKEDITOR.define( [ 'document/operations/operation', 'ckeditorerror' ], function(
 				 * Old and new attributes should have the same keys.
 				 *
 				 * @error operation-change-different-keys
-				 * @param {document.operations.ChangeOperation} changeOperation
+				 * @param {document.operations.ChangeOperation} op
 				 * @param {document.Attribute} oldAttr
 				 * @param {document.Attribute} newAttr
 				 */
 				throw new CKEditorError(
 					'operation-change-different-keys: Old and new attributes should have the same keys.',
-					{ changeOperation: this, oldAttr: oldAttr, newAttr: newAttr } );
+					{ op: this, oldAttr: oldAttr, newAttr: newAttr } );
 			}
 
 			// Remove or change.
@@ -85,20 +82,20 @@ CKEDITOR.define( [ 'document/operations/operation', 'ckeditorerror' ], function(
 				for ( value of this.range ) {
 					if ( !value.node.hasAttr( oldAttr ) ) {
 						/**
-						 * The attribute which should be removed does not exists for given node.
+						 * The attribute which should be removed does not exists for the given node.
 						 *
 						 * @error operation-change-no-attr-to-remove
-						 * @param {document.operations.ChangeOperation} changeOperation
+						 * @param {document.operations.ChangeOperation} op
 						 * @param {document.Node} node
 						 * @param {document.Attribute} attr
 						 */
 						throw new CKEditorError(
 							'operation-change-no-attr-to-remove: The attribute which should be removed does not exists for given node.',
-							{ changeOperation: this, node: value.node, attr: oldAttr } );
+							{ op: this, node: value.node, attr: oldAttr } );
 					}
 
 					// There is no use in removing attribute if we will overwrite it later.
-					// Still it is profitable to run throw the loop to check if all nodes in the range has old attribute.
+					// Still it is profitable to run through the loop to check if all nodes in the range has old attribute.
 					if ( newAttr === null ) {
 						value.node.removeAttr( oldAttr.key );
 					}
@@ -110,16 +107,16 @@ CKEDITOR.define( [ 'document/operations/operation', 'ckeditorerror' ], function(
 				for ( value of this.range ) {
 					if ( oldAttr === null && value.node.hasAttr( newAttr.key ) ) {
 						/**
-						 * The attribute with given key already exists for given node.
+						 * The attribute with given key already exists for the given node.
 						 *
 						 * @error operation-change-attr-exists
-						 * @param {document.operations.ChangeOperation} changeOperation
+						 * @param {document.operations.ChangeOperation} op
 						 * @param {document.Node} node
 						 * @param {document.Attribute} attr
 						 */
 						throw new CKEditorError(
 							'operation-change-attr-exists: The attribute with given key already exists.',
-							{ changeOperation: this, node: value.node, attr: newAttr } );
+							{ op: this, node: value.node, attr: newAttr } );
 					}
 
 					value.node.setAttr( newAttr );
@@ -127,9 +124,6 @@ CKEDITOR.define( [ 'document/operations/operation', 'ckeditorerror' ], function(
 			}
 		}
 
-		/**
-		 * See {@link document.operations.Operation#getReversed}.
-		 */
 		getReversed() {
 			return new ChangeOperation( this.range, this.newAttr, this.oldAttr, this.baseVersion + 1 );
 		}

+ 2 - 8
packages/ckeditor5-utils/src/document/operations/insertoperation.js

@@ -11,7 +11,7 @@ CKEDITOR.define( [
 	'document/operations/removeoperation'
 ], function( Operation, NodeList ) {
 	/**
-	 * Operation to insert list of nodes on the given position.
+	 * Operation to insert list of nodes on the given position in the tree data model.
 	 *
 	 * @class document.operations.InsertOperation
 	 */
@@ -20,7 +20,7 @@ CKEDITOR.define( [
 		 * Creates an insert operation.
 		 *
 		 * @param {document.Position} position Position of insertion.
-		 * @param {document.Node|document.Text|document.NodeList|String|Iterable} nodes List of nodes to be inserted.
+		 * @param {document.Node|document.Text|document.NodeList|String|Iterable} nodes The list of nodes to be inserted.
 		 * List of nodes can be any type accepted by the {@link document.NodeList} constructor.
 		 * @param {Number} baseVersion {@link document.Document#version} on which operation can be applied.
 		 * @constructor
@@ -45,16 +45,10 @@ CKEDITOR.define( [
 			this.nodeList = new NodeList( nodes );
 		}
 
-		/**
-		 * See {@link document.operations.Operation#_execute}.
-		 */
 		_execute() {
 			this.position.parent.insertChildren( this.position.offset, this.nodeList );
 		}
 
-		/**
-		 * See {@link document.operations.Operation#getReversed}.
-		 */
 		getReversed() {
 			// Because of circular dependencies we need to re-require remove operation here.
 			var RemoveOperation = CKEDITOR.require( 'document/operations/removeoperation' );

+ 10 - 16
packages/ckeditor5-utils/src/document/operations/moveoperation.js

@@ -12,7 +12,7 @@ CKEDITOR.define( [
 	'utils'
 ], function( Operation, NodeList, CKEditorError, utils ) {
 	/**
-	 * Operation to move list of following nodes from the one position in the document to another.
+	 * Operation to move list of subsequent nodes from one position in the document to another.
 	 *
 	 * @class document.operations.MoveOperation
 	 */
@@ -22,7 +22,7 @@ CKEDITOR.define( [
 		 *
 		 * @param {document.Position} sourcePosition Position before the first element to move.
 		 * @param {document.Position} targetPosition Position where moved elements will be inserted.
-		 * @param {Number} howMany How many consecutive nodes to move, starting from sourcePosition.
+		 * @param {Number} howMany How many consecutive nodes to move, starting from `sourcePosition`.
 		 * @param {Number} baseVersion {@link document.Document#version} on which operation can be applied.
 		 * @constructor
 		 */
@@ -51,9 +51,6 @@ CKEDITOR.define( [
 			this.howMany = howMany;
 		}
 
-		/**
-		 * See {@link document.operations.Operation#_execute}.
-		 */
 		_execute() {
 			var sourceElement = this.sourcePosition.parent;
 			var targetElement = this.targetPosition.parent;
@@ -68,33 +65,33 @@ CKEDITOR.define( [
 				 * Source position or target position is invalid.
 				 *
 				 * @error operation-move-position-invalid
-				 * @param {document.operations.MoveOperation} moveOperation
+				 * @param {document.operations.MoveOperation} op
 				 */
 				throw new CKEditorError(
 					'operation-move-position-invalid: Source position or target position is invalid.',
-					{ moveOperation: this }
+					{ op: this }
 				);
 			} else if ( sourceOffset + this.howMany > sourceElement.getChildCount() ) {
 				/**
 				 * The nodes which should be moved do not exist.
 				 *
 				 * @error operation-move-nodes-do-not-exist
-				 * @param {document.operations.MoveOperation} moveOperation
+				 * @param {document.operations.MoveOperation} op
 				 */
 				throw new CKEditorError(
 					'operation-move-nodes-do-not-exist: The nodes which should be moved do not exist.',
-					{ moveOperation: this }
+					{ op: this }
 				);
 			} else if ( sourceElement === targetElement && sourceOffset <= targetOffset && targetOffset < sourceOffset + this.howMany ) {
 				/**
 				 * Trying to move a range of nodes into the middle of that range.
 				 *
 				 * @error operation-move-range-into-itself
-				 * @param {document.operations.MoveOperation} moveOperation
+				 * @param {document.operations.MoveOperation} op
 				 */
 				throw new CKEditorError(
 					'operation-move-range-into-itself: Trying to move a range of nodes to the inside of that range.',
-					{ moveOperation: this }
+					{ op: this }
 				);
 			} else {
 				var sourcePath = this.sourcePosition.getParentPath();
@@ -108,11 +105,11 @@ CKEDITOR.define( [
 						 * Trying to move a range of nodes into one of nodes from that range.
 						 *
 						 * @error operation-move-node-into-itself
-						 * @param {document.operations.MoveOperation} moveOperation
+						 * @param {document.operations.MoveOperation} op
 						 */
 						throw new CKEditorError(
 							'operation-move-node-into-itself: Trying to move a range of nodes into one of nodes from that range.',
-							{ moveOperation: this }
+							{ op: this }
 						);
 					}
 				}
@@ -130,9 +127,6 @@ CKEDITOR.define( [
 			targetElement.insertChildren( targetOffset, removedNodes );
 		}
 
-		/**
-		 * See {@link document.operations.Operation#getReversed}.
-		 */
 		getReversed() {
 			return new MoveOperation( this.targetPosition, this.sourcePosition, this.howMany, this.baseVersion + 1 );
 		}

+ 16 - 18
packages/ckeditor5-utils/src/document/operations/operation.js

@@ -9,23 +9,24 @@ CKEDITOR.define( [], function() {
 	/**
 	 * Abstract base operation class.
 	 *
+	 * @abstract
 	 * @class document.operations.Operation
 	 */
 	class Operation {
 		/**
 		 * Base operation constructor.
 		 *
-		 * @param {Number} baseVersion {@link document.Document#version} on which operation can be applied.
+		 * @param {Number} baseVersion {@link document.Document#version} on which the operation can be applied.
 		 * @constructor
 		 */
 		constructor( baseVersion ) {
 			/**
 			 * {@link document.Document#version} on which operation can be applied. If you try to
-			 * {@link document.Document#applyOperation apply} operation with different base version than
+			 * {@link document.Document#applyOperation apply} operation with different base version than the
 			 * {@link document.Document#version document version} the {@link document-applyOperation-wrong-version}
 			 * error is thrown.
 			 *
-			 * @property {Number} baseVersion
+			 * @property {Number}
 			 */
 			this.baseVersion = baseVersion;
 
@@ -33,8 +34,6 @@ CKEDITOR.define( [], function() {
 			 * Executes the operation - modifications described by the operation attributes
 			 * will be applied to the tree model.
 			 *
-			 * This method has to be defined in deriving operation class.
-			 *
 			 * @method _execute
 			 * @protected
 			 */
@@ -46,33 +45,32 @@ CKEDITOR.define( [], function() {
 			 *
 			 * Keep in mind that tree model state may change since executing the original operation,
 			 * so reverse operation will be "outdated". In that case you will need to
-			 * {@link #getTransformedBy transform} it by all operations that were executed after the original operation
-			 *
-			 * This method has to be defined in deriving operation class.
+			 * {@link #getTransformedBy transform} it by all operations that were executed after the original operation.
 			 *
 			 * @method getReversed
 			 * @returns {document.operations.Operation} Reversed operation.
 			 */
 
 			/**
-			 * Creates and returns a clone of this operation that is transformed by given operation.
-			 * When operation is transformed it's parameters may change accordingly to the operation which it is
-			 * transformed by. If given operation applied any modifications to the tree model that are
-			 * affecting ranges / positions / nodes connected with this operation, those changes will be reflected
-			 * in parameters of returned operation.
+			 * Creates and returns a clone of this operation which is transformed by the given operation.
+			 * When operation is transformed its parameters may change accordingly to the operation which it is
+			 * transformed by. If the given operation applied to the tree model any modifications which are
+			 * affecting ranges/positions/nodes connected with this operation, those changes will be reflected
+			 * in the parameters of the returned operation.
 			 *
-			 * Whenever a {@link document.Document document} has different {@link document.Document#baseVersion}
-			 * than an operation you want to {@link document.Document#applyOperation apply}, you need to transform that
-			 * operation by all the operations that were executed on the {@link document.Document document} since it has
+			 * Whenever the {@link document.Document document} has different {@link document.Document#baseVersion}
+			 * than an operation you want to {@link document.Document#applyOperation apply}, you need to transform
+			 * all the operations that were executed on the {@link document.Document document} since it has
 			 * {@link document.Document#baseVersion} same as the operation (transform in the same order as those
 			 * operations were executed). This way all modifications done to the tree model will be reflected
 			 * in the operation parameters and the operation will "work" on "up-to-date" version of the tree model.
 			 *
-			 * This method has to be defined in deriving operation class.
+			 * **TODO**: So far we think that transforming one operation by another one may result in more than one
+			 * operation. This needs to be clarified in this documentation.
 			 *
 			 * @method getTransformedBy
 			 * @param {document.operations.Operation} operation Operation by which this operation will be transformed.
-			 * @returns {document.operations.Operation} A result of transformation of this operation by the given operation.
+			 * @returns {document.operations.Operation[]} A result of transformation of this operation by the given operation.
 			 */
 		}
 	}

+ 0 - 3
packages/ckeditor5-utils/src/document/operations/reinsertoperation.js

@@ -21,9 +21,6 @@ CKEDITOR.define( [
 	 * @class document.operations.ReinsertOperation
 	 */
 	class ReinsertOperation extends MoveOperation {
-		/**
-		 * See {@link document.operations.Operation#getReversed}.
-		 */
 		getReversed() {
 			// Because of circular dependencies we need to re-require reinsert operation here.
 			var RemoveOperation = CKEDITOR.require( 'document/operations/removeoperation' );

+ 1 - 6
packages/ckeditor5-utils/src/document/operations/removeoperation.js

@@ -27,17 +27,12 @@ CKEDITOR.define( [
 		constructor( position, howMany, baseVersion ) {
 			var graveyard = position.root.document._graveyard;
 
-			/**
-			 * Position in a graveyard where nodes were moved.
-			 */
+			// Position in a graveyard where nodes were moved.
 			var graveyardPosition = Position.createFromParentAndOffset( graveyard, 0 );
 
 			super( position, graveyardPosition, howMany, baseVersion );
 		}
 
-		/**
-		 * See {@link document.operations.Operation#getReversed}.
-		 */
 		getReversed() {
 			// Because of circular dependencies we need to re-require reinsert operation here.
 			var ReinsertOperation = CKEDITOR.require( 'document/operations/reinsertoperation' );

+ 65 - 62
packages/ckeditor5-utils/src/document/position.js

@@ -7,7 +7,7 @@
 
 CKEDITOR.define( [ 'utils', 'ckeditorerror' ], function( utils, CKEditorError ) {
 	/**
-	 * Position is always before or after a node.
+	 * Position in the tree. Position is always located before or after a node.
 	 * See {@link #path} property for more information.
 	 *
 	 * @class document.Position
@@ -36,7 +36,7 @@ CKEDITOR.define( [ 'utils', 'ckeditorerror' ], function( utils, CKEditorError )
 			 *        |- a   Before: [ 1, 1, 1 ] After: [ 1, 1, 2 ]
 			 *        |- r   Before: [ 1, 1, 2 ] After: [ 1, 1, 3 ]
 			 *
-			 * @type {Array}
+			 * @type {Number[]}
 			 */
 			this.path = path;
 
@@ -49,59 +49,7 @@ CKEDITOR.define( [ 'utils', 'ckeditorerror' ], function( utils, CKEditorError )
 		}
 
 		/**
-		 * Create position from the parent element and the offset in that element.
-		 *
-		 * @param {document.Element} parent Position parent element.
-		 * @param {Number} offset Position offset.
-		 */
-		static createFromParentAndOffset( parent, offset ) {
-			var path = parent.getPath();
-
-			path.push( offset );
-
-			return new Position( path, parent.root );
-		}
-
-		/**
-		 * Set the position before given node.
-		 *
-		 * @param {document.node} node Node the position should be directly before.
-		 */
-		static createBefore( node ) {
-			if ( !node.parent ) {
-				/**
-				 * You can not make position before root.
-				 *
-				 * @error position-before-root
-				 * @param {document.Node} root
-				 */
-				throw new CKEditorError( 'position-before-root: You can not make position before root.', { root: node } );
-			}
-
-			return Position.createFromParentAndOffset( node.parent, node.positionInParent );
-		}
-
-		/**
-		 * Set the position after given node.
-		 *
-		 * @param {document.Node} node Node the position should be directly after.
-		 */
-		static createAfter( node ) {
-			if ( !node.parent ) {
-				/**
-				 * You can not make position after root.
-				 *
-				 * @error position-after-root
-				 * @param {document.Node} root
-				 */
-				throw new CKEditorError( 'position-after-root: You can not make position after root.', { root: node } );
-			}
-
-			return Position.createFromParentAndOffset( node.parent, node.positionInParent + 1 );
-		}
-
-		/**
-		 * Element which is a parent of the position.
+		 * Parent element of the position. The position is located at {@link #offset} in this element.
 		 *
 		 * @readonly
 		 * @property {document.Element} parent
@@ -119,7 +67,7 @@ CKEDITOR.define( [ 'utils', 'ckeditorerror' ], function( utils, CKEditorError )
 		}
 
 		/**
-		 * Position offset in the parent, which is the last element of the path.
+		 * Offset at which the position is located in the {@link #parent}.
 		 *
 		 * @readonly
 		 * @property {Number} offset
@@ -142,32 +90,87 @@ CKEDITOR.define( [ 'utils', 'ckeditorerror' ], function( utils, CKEditorError )
 		 * Node directly after the position.
 		 *
 		 * @readonly
-		 * @type {document.Node}
+		 * @property {document.Node}
 		 */
 		get nodeAfter() {
 			return this.parent.getChild( this.offset ) || null;
 		}
 
 		/**
-		 * Two positions equals if paths equal.
+		 * Two positions equal if paths are equal.
 		 *
 		 * @param {document.Position} otherPosition Position to compare.
-		 * @returns {Boolean} true if positions equal.
+		 * @returns {Boolean} True if positions equal.
 		 */
 		isEqual( otherPosition ) {
 			return utils.isEqual( this.path, otherPosition.path );
 		}
 
 		/**
-		 * Return the path to the parent, which is the {@link document.Position#path} without the last element.
+		 * Returns the path to the parent, which is the {@link document.Position#path} without the last element.
 		 *
-		 * This method return the parent path even if the parent does not exists.
+		 * This method returns the parent path even if the parent does not exists.
 		 *
-		 * @returns {Array} Path to the parent.
+		 * @returns {Number[]} Path to the parent.
 		 */
 		getParentPath() {
 			return this.path.slice( 0, -1 );
 		}
+
+		/**
+		 * Creates a new position from the parent element and the offset in that element.
+		 *
+		 * @param {document.Element} parent Position parent element.
+		 * @param {Number} offset Position offset.
+		 * @returns {document.Position}
+		 */
+		static createFromParentAndOffset( parent, offset ) {
+			var path = parent.getPath();
+
+			path.push( offset );
+
+			return new Position( path, parent.root );
+		}
+
+		/**
+		 * Creates a new position before the given node.
+		 *
+		 * @param {document.node} node Node the position should be directly before.
+		 * @returns {document.Position}
+		 */
+		static createBefore( node ) {
+			if ( !node.parent ) {
+				/**
+				 * You can not make position before root.
+				 *
+				 * @error position-before-root
+				 * @param {document.Node} root
+				 */
+				throw new CKEditorError( 'position-before-root: You can not make position before root.', { root: node } );
+			}
+
+			return Position.createFromParentAndOffset( node.parent, node.positionInParent );
+		}
+
+		/**
+		 * Creates a new position after given node.
+		 *
+		 * @param {document.Node} node Node the position should be directly after.
+		 * @returns {document.Position}
+		 */
+		static createAfter( node ) {
+			if ( !node.parent ) {
+				/**
+				 * You can not make position after root.
+				 *
+				 * @error position-after-root
+				 * @param {document.Node} root
+				 */
+				throw new CKEditorError( 'position-after-root: You can not make position after root.', { root: node } );
+			}
+
+			return Position.createFromParentAndOffset( node.parent, node.positionInParent + 1 );
+		}
 	}
 
 	return Position;

+ 21 - 13
packages/ckeditor5-utils/src/document/positioniterator.js

@@ -21,7 +21,7 @@ CKEDITOR.define( [
 	 */
 	class PositionIterator {
 		/**
-		 * Create a range iterator.
+		 * Creates a range iterator.
 		 *
 		 * @param {document.Range} [boundaries] Range to define boundaries of the iterator.
 		 * @param {document.Position} [iteratorPosition] Starting position.
@@ -42,8 +42,10 @@ CKEDITOR.define( [
 			 */
 
 			/**
-			 * Iterator boundaries. When {@link #next} is called on end boundary or {@link #previous} on the
-			 * first then `{ done: true }` is returned.
+			 * Iterator boundaries.
+			 *
+			 * When the {@link #next} method is called on the end boundary or the {@link #previous} method
+			 * on the start boundary, then `{ done: true }` is returned.
 			 *
 			 * If boundaries are not defined they are set before first and after last child of the root node.
 			 *
@@ -52,14 +54,14 @@ CKEDITOR.define( [
 		}
 
 		/**
-		 * Move {@link #position} to the next position and returned skipped value.
+		 * Moves the {@link #position} to the next position and returns the enctountered value.
 		 *
-		 * @returns {Object} Value between last and new {@link #position}.
+		 * @returns {Object} Value between the previous and the new {@link #position}.
 		 * @returns {Boolean} return.done True if iterator is done.
 		 * @returns {Object} return.value
-		 * @returns {Number} return.value.type Skipped value type, possible options: {@link PositionIterator#ELEMENT_ENTER},
+		 * @returns {Number} return.value.type Encountered value type, possible options: {@link PositionIterator#ELEMENT_ENTER},
 		 * {@link PositionIterator#ELEMENT_LEAVE} or {@link PositionIterator#CHARACTER}.
-		 * @returns {Node} return.value.node Skipped node.
+		 * @returns {document.Node} return.value.node Encountered node.
 		 */
 		next() {
 			var position = this.position;
@@ -92,14 +94,14 @@ CKEDITOR.define( [
 		}
 
 		/**
-		 * Move {@link #position} to the previous position and returned skipped value.
+		 * Moves the {@link #position} to the previous position and returns the encountered value.
 		 *
-		 * @returns {Object} Value between last and new {@link #position}.
+		 * @returns {Object} Value between the previous and the new {@link #position}.
 		 * @returns {Boolean} return.done True if iterator is done.
 		 * @returns {Object} return.value
-		 * @returns {Number} return.value.type Skipped value type, possible options: {@link PositionIterator#ELEMENT_ENTER},
+		 * @returns {Number} return.value.type Encountered value type, possible options: {@link PositionIterator#ELEMENT_ENTER},
 		 * {@link PositionIterator#ELEMENT_LEAVE} or {@link PositionIterator#CHARACTER}.
-		 * @returns {Node} return.value.node Skipped node.
+		 * @returns {document.Node} return.value.node Scanned node.
 		 */
 		previous() {
 			var position = this.position;
@@ -143,23 +145,29 @@ CKEDITOR.define( [
 	}
 
 	/**
-	 * Flag for element entering.
+	 * Flag for entering element.
 	 *
+	 * @static
 	 * @readonly
+	 * @property {Number}
 	 */
 	PositionIterator.ELEMENT_ENTER = ELEMENT_ENTER;
 
 	/**
-	 * Flag for element leaving.
+	 * Flag for leaving element.
 	 *
+	 * @static
 	 * @readonly
+	 * @property {Number}
 	 */
 	PositionIterator.ELEMENT_LEAVE = ELEMENT_LEAVE;
 
 	/**
 	 * Flag for character.
 	 *
+	 * @static
 	 * @readonly
+	 * @property {Number}
 	 */
 	PositionIterator.CHARACTER = CHARACTER;
 

+ 3 - 3
packages/ckeditor5-utils/src/document/range.js

@@ -13,7 +13,7 @@ CKEDITOR.define( [ 'document/positioniterator' ], function( PositionIterator ) {
 	 */
 	class Range {
 		/**
-		 * Create an range.
+		 * Creates a range.
 		 *
 		 * @param {document.Position} start Start position.
 		 * @param {document.Position} end End position.
@@ -23,14 +23,14 @@ CKEDITOR.define( [ 'document/positioniterator' ], function( PositionIterator ) {
 			/**
 			 * Start position.
 			 *
-			 * @type {document.Position}
+			 * @property {document.Position}
 			 */
 			this.start = start;
 
 			/**
 			 * End position.
 			 *
-			 * @type {document.Position}
+			 * @property {document.Position}
 			 */
 			this.end = end;
 		}

+ 5 - 5
packages/ckeditor5-utils/src/document/text.js

@@ -7,14 +7,14 @@
 
 CKEDITOR.define( [], function() {
 	/**
-	 * Data structure for text with attributes. Note that Text is not a node, because it will never be part of document
-	 * tree, {@link document.Character is a node}.
+	 * Data structure for text with attributes. Note that the `Text` is not a {@link document.Node},
+	 * because it will never be part of the document tree. {@link document.Character is a node}.
 	 *
 	 * @class document.Text
 	 */
 	class Text {
 		/**
-		 * Creates text with attributes.
+		 * Creates a text with attributes.
 		 *
 		 * @param {String} text Described text.
 		 * @param {Iterable} attrs Iterable collection of {@link document.Attribute attributes}.
@@ -25,14 +25,14 @@ CKEDITOR.define( [], function() {
 			 * Text.
 			 *
 			 * @readonly
-			 * @property {String} text
+			 * @property {String}
 			 */
 			this.text = text;
 
 			/**
 			 * Iterable collection of {@link document.Attribute attributes}.
 			 *
-			 * @property {Iterable} attr
+			 * @property {Iterable}
 			 */
 			this.attrs = attrs;
 		}