Browse Source

Docs: update docs.

Piotr Jasiun 10 years ago
parent
commit
b1bcaf7c59

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

@@ -29,6 +29,14 @@ CKEDITOR.define( [
 			 */
 			this.root = new Element( 'root' );
 
+			/**
+			 * 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.Operation#baseVersion} will
+			 * not match document version an {@link document-applyOperation-wrong-version} error is fired.
+			 *
+			 * @readonly
+			 * @property {Number} version
+			 */
 			this.version = 0;
 		}
 

+ 15 - 4
packages/ckeditor5-utils/src/document/element.js

@@ -17,9 +17,9 @@ CKEDITOR.define( [ 'document/node', 'document/nodelist' ], function( Node, NodeL
 		 *
 		 * This constructor should be used only internally by the document.
 		 *
-		 * @param {document.Element|Null} parent Node parent.
 		 * @param {String} name Node name.
-		 * @param {Array} attrs Array of attributes.
+		 * @param {Array} attrs Array of {@link document.Attribute attributes}.
+		 * @param {Array} children Array of {@link document.Node nodes}.
 		 */
 		constructor( name, attrs, children ) {
 			super( attrs );
@@ -33,9 +33,10 @@ CKEDITOR.define( [ 'document/node', 'document/nodelist' ], function( Node, NodeL
 			this.name = name;
 
 			/**
-			 * Array of children nodes.
+			 * List of children nodes.
 			 *
-			 * @property {Array} children
+			 * @readonly
+			 * @property {document.NodeList} children
 			 */
 			this.children = new NodeList();
 
@@ -44,6 +45,16 @@ CKEDITOR.define( [ 'document/node', 'document/nodelist' ], function( Node, NodeL
 			}
 		}
 
+		/**
+		 * Insert a list of nodes on the given index.
+		 *
+		 * Note that list of children can be modified only in elements not attached yet to the document.
+		 * All attached nodes should be modified using the {@link document.InsertOperation}.
+		 *
+		 * @param {Nuber} index Position where nodes should be inserted.
+		 * @param {document.Node|document.Text|document.NodeList|String|Array} nodes List of nodes to be inserted.
+		 * List of nodes can be any type accepted by the {@link document.NodeList} constructor.
+		 */
 		insertChildren( index, nodes ) {
 			this.children.insert( index, new NodeList( nodes ) );
 

+ 32 - 4
packages/ckeditor5-utils/src/document/node.js

@@ -17,30 +17,47 @@ CKEDITOR.define( [ 'document/attribute', 'utils' ], function( Attribute, utils )
 		 *
 		 * This is an abstract class, it should not be created directly.
 		 *
-		 * @param {document.Element|Null} parent Node parent.
+		 * Created node has no parent. Parent of the node is set when it is attached to the {@link document.Element}.
+		 *
 		 * @param {Array} attrs Array of attributes.
 		 */
 		constructor( attrs ) {
 			/**
-			 * Parent element.
+			 * Parent element. Null by default.
 			 *
-			 * @readonly
-			 * @property {document.Element} parent
+			 * @property {document.Element|Null} parent
 			 */
 			this.parent = null;
 
 			/**
 			 * Array of attributes.
 			 *
+			 * Attributes of nodes attached to the document can be changed only be the {@link document.ChangeOpeation}.
+			 *
 			 * @property {Array} attr
 			 */
 			this.attrs = attrs || [];
 		}
 
+		/**
+		 * 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( attr ) {
 			return this.getAttr( attr ) !== null;
 		}
 
+		/**
+		 * 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( attr ) {
 			var i, len;
 
@@ -137,6 +154,12 @@ CKEDITOR.define( [ 'document/attribute', 'utils' ], function( Attribute, utils )
 			return ( pos !== null && this.parent.children.get( pos - 1 ) ) || null;
 		}
 
+		/**
+		 * 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 {Array} Path, array of numbers.
+		 */
 		getPath() {
 			var path = [];
 			var node = this; // jscs:ignore safeContextKeyword
@@ -149,6 +172,11 @@ CKEDITOR.define( [ 'document/attribute', 'utils' ], function( Attribute, utils )
 			return path;
 		}
 
+		/**
+		 * Custom toJSON method to solve child-parent circular dependencies.
+		 *
+		 * @returns {Object} Clone of this object with the parent property replaced with its name.
+		 */
 		toJSON() {
 			var json = utils.clone( this );
 

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

@@ -12,17 +12,58 @@ CKEDITOR.define( [
 	'utils'
 ], function( Character, Text, Node, utils ) {
 	/**
+	 * List of nodes. It is used to represent multiple nodes with a given order, for example children of
+	 * elements {@link document.Element}.
+	 *
+	 * This class let you modify list of nodes, for example nodes to insert and pass the reference for such list.
+	 *
+	 * Thanks to the constructor which accept various structure, this class let you easily create list of text node.
+	 *
+	 * It also may internally compress nodes.
+	 *
 	 * @class document.NodeList
 	 */
 	class NodeList {
+		/**
+		 * Constructor let you create a list of nodes in many ways. See examples:
+		 *
+		 *		var nodeList = new NodeList( [ new Element( p1 ), new Element( p1 ) ] );
+		 *		nodeList.length // 2
+		 *
+		 *		var nodeList = new NodeList( new Element( p ) );
+		 *		nodeList.length // 1
+		 *
+		 *		var nodeList = new NodeList( [ 'foo', new Element( p ), 'bar' ] );
+		 *		nodeList.length // 7
+		 *
+		 *		var nodeList = new NodeList( 'foo' );
+		 *		nodeList.length // 3
+		 *
+		 *		var nodeList = new NodeList( new Text( 'foo', [ attrA, attrB ] ) );
+		 *		nodeList.length // 3
+		 *		nodeList.get( 0 ).attrs.length // 2
+		 *		nodeList.get( 1 ).attrs.length // 2
+		 *		nodeList.get( 2 ).attrs.length // 2
+		 *
+		 *		var nodeListA = new NodeList( 'foo' );
+		 *		var nodeListB = new NodeList( nodeListA );
+		 *		nodeListA === nodeListB // true
+		 *		nodeListB.length // 3
+		 *
+		 * @param {document.Node|document.Text|document.NodeList|String|Array} nodes List of nodes.
+		 */
 		constructor( nodes ) {
 			if ( nodes instanceof NodeList ) {
 				// We do not clone anything.
 				return nodes;
 			}
 
-			// debugger;
-
+			/**
+			 * Internal array to store nodes.
+			 *
+			 * @private
+			 * @property {Array} _nodes
+			 */
 			this._nodes = [];
 
 			if ( nodes ) {
@@ -35,13 +76,18 @@ CKEDITOR.define( [
 				for ( i = 0, nodesLen = nodes.length; i < nodesLen; i++ ) {
 					node = nodes[ i ];
 
+					// Node.
 					if ( node instanceof Node ) {
 						this._nodes.push( node );
-					} else if ( node instanceof Text ) {
+					}
+					// Text.
+					else if ( node instanceof Text ) {
 						for ( j = 0, nodeLen = node.text.length; j < nodeLen; j++ ) {
 							this._nodes.push( new Character( node.text[ j ], utils.clone( node.attrs ) ) );
 						}
-					} else {
+					}
+					// String.
+					else {
 						for ( j = 0, nodeLen = node.length; j < nodeLen; j++ ) {
 							this._nodes.push( new Character( node[ j ] ) );
 						}
@@ -50,26 +96,60 @@ CKEDITOR.define( [
 			}
 		}
 
+		/**
+		 * Returns node at the given index.
+		 *
+		 * @param {Number} index Node index.
+		 * @returns {document.Node} Node at given index.
+		 */
 		get( index ) {
 			return this._nodes[ index ];
 		}
 
+		/**
+		 * Inserts nodes from the given node list into this node list at the given index.
+		 *
+		 * @param {Number} index Position where nodes should be inserted.
+		 * @param {document.NodeList} nodeList List of nodes to insert.
+		 */
 		insert( index, nodeList ) {
 			this._nodes.splice.apply( this._nodes, [ index, 0 ].concat( nodeList._nodes ) );
 		}
 
+		/**
+		 * Removes number of nodes starting at the given index.
+		 *
+		 * @param {Number} index Position of the first node to remove.
+		 * @param {Number} number Number of nodes to remove.
+		 */
 		remove( index, number ) {
 			this._nodes.splice( index, number );
 		}
 
+		/**
+		 * 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.
+		 */
 		indexOf( node ) {
 			return this._nodes.indexOf( node );
 		}
 
+		/**
+		 * Number of nodes in the node list.
+		 *
+		 * @readonly
+		 * @property {Number} length
+		 */
 		get length() {
 			return this._nodes.length;
 		}
 
+		/**
+		 * Node list iterator.
+		 */
 		[ Symbol.iterator ]() {
 			return this._nodes[ Symbol.iterator ]();
 		}

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

@@ -17,7 +17,7 @@ CKEDITOR.define( [ 'utils', 'ckeditorerror' ], function( utils, CKEditorError )
 		 * Creates a position.
 		 *
 		 * @param {Array} path Position path. See {@link #path} property for more information.
-		 * @param {document.Document} doc Document which position refers to.
+		 * @param {document.Element} root Root element for the path. Note that this element can not have a parent.
 		 */
 		constructor( path, root ) {
 			/**
@@ -40,9 +40,9 @@ CKEDITOR.define( [ 'utils', 'ckeditorerror' ], function( utils, CKEditorError )
 			this.path = path;
 
 			/**
-			 * Document which position refers to.
+			 * Root element for the path. Note that this element can not have a parent.
 			 *
-			 * @type {document.Document}
+			 * @type {document.Element}
 			 */
 			this.root = root;
 		}

+ 2 - 1
packages/ckeditor5-utils/src/document/positioniterator.js

@@ -23,7 +23,8 @@ CKEDITOR.define( [
 		/**
 		 * Create a range iterator.
 		 *
-		 * @param {document.range} boundaries Range to define boundaries of the iterator.
+		 * @param {document.Range} [boundaries] Range to define boundaries of the iterator.
+		 * @param {document.Position} [iteratorPosition] Starting position.
 		 */
 		constructor( boundaries, iteratorPosition ) {
 			if ( boundaries instanceof Position ) {

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

@@ -47,7 +47,7 @@ CKEDITOR.define( [ 'document/positioniterator' ], function( PositionIterator ) {
 		/**
 		 * Range iterator.
 		 *
-		 * @async see document.PositionIterator
+		 * @see document.PositionIterator
 		 */
 		[ Symbol.iterator ]() {
 			return new PositionIterator( this );