Szymon Cofalik před 9 roky
rodič
revize
7b79abaf81

+ 9 - 10
packages/ckeditor5-engine/src/model/document.js

@@ -256,16 +256,6 @@ export default class Document {
 	}
 
 	/**
-	 * Gets names of all roots (without the {@link engine.model.Document#graveyard}).
-	 *
-	 * @readonly
-	 * @type {Iterable.<String>}
-	 */
-	getRootNames() {
-		return Array.from( this._roots.keys() ).filter( ( name ) => name != graveyardName );
-	}
-
-	/**
 	 * Checks if root with given name is defined.
 	 *
 	 * @param {String} name Name of root to check.
@@ -276,6 +266,15 @@ export default class Document {
 	}
 
 	/**
+	 * Returns array with names of all roots (without the {@link engine.model.Document#graveyard}) added to the document.
+	 *
+	 * @returns {Array.<String>} Roots names.
+	 */
+	getRootNames() {
+		return Array.from( this._roots.keys() ).filter( ( name ) => name != graveyardName );
+	}
+
+	/**
 	 * Custom toJSON method to solve child-parent circular dependencies.
 	 *
 	 * @returns {Object} Clone of this object with the document property changed to string.

+ 9 - 6
packages/ckeditor5-engine/src/model/documentfragment.js

@@ -44,27 +44,30 @@ export default class DocumentFragment {
 	}
 
 	/**
-	 * Returns the number of this document fragment's children.
+	 * Number of this document fragment's children.
 	 *
-	 * @returns {Number}
+	 * @readonly
+	 * @type {Number}
 	 */
 	get childCount() {
 		return this._children.length;
 	}
 
 	/**
-	 * Returns the sum of {engine.model.Node#offsetSize offset sizes} of all of this document fragment's children.
+	 * Sum of {engine.model.Node#offsetSize offset sizes} of all of this document fragment's children.
 	 *
-	 * @returns {Number}
+	 * @readonly
+	 * @type {Number}
 	 */
 	get maxOffset() {
 		return this._children.maxOffset;
 	}
 
 	/**
-	 * Returns `true` if there are no nodes inside this document fragment, `false` otherwise.
+	 * Is `true` if there are no nodes inside this document fragment, `false` otherwise.
 	 *
-	 * @returns {Boolean}
+	 * @readonly
+	 * @type {Boolean}
 	 */
 	get isEmpty() {
 		return this.childCount === 0;

+ 9 - 6
packages/ckeditor5-engine/src/model/element.js

@@ -50,27 +50,30 @@ export default class Element extends Node {
 	}
 
 	/**
-	 * Returns the number of this element's children.
+	 * Number of this element's children.
 	 *
-	 * @returns {Number}
+	 * @readonly
+	 * @type {Number}
 	 */
 	get childCount() {
 		return this._children.length;
 	}
 
 	/**
-	 * Returns the sum of {engine.model.Node#offsetSize offset sizes} of all of this element's children.
+	 * Sum of {engine.model.Node#offsetSize offset sizes} of all of this element's children.
 	 *
-	 * @returns {Number}
+	 * @readonly
+	 * @type {Number}
 	 */
 	get maxOffset() {
 		return this._children.maxOffset;
 	}
 
 	/**
-	 * Returns `true` if there are no nodes inside this element, `false` otherwise.
+	 * Is `true` if there are no nodes inside this element, `false` otherwise.
 	 *
-	 * @returns {Boolean}
+	 * @readonly
+	 * @type {Boolean}
 	 */
 	get isEmpty() {
 		return this.childCount === 0;

+ 6 - 3
packages/ckeditor5-engine/src/model/node.js

@@ -66,9 +66,11 @@ export default class Node {
 	/**
 	 * Index of this node in it's parent or `null` if the node has no parent.
 	 *
-	 * Throws error if the parent element does not contain this node. This means that model tree got broken.
+	 * Accessing this property throws an error if this node's parent element does not contain it.
+	 * This means that model tree got broken.
 	 *
-	 * @returns {Number|null}
+	 * @readonly
+	 * @type {Number|null}
 	 */
 	get index() {
 		let pos;
@@ -93,7 +95,8 @@ export default class Node {
 	 * Offset at which this node starts in it's parent. It is equal to the sum of {@link engine.model.Node#offsetSize offsetSize}
 	 * of all it's previous siblings. Equals to `null` if node has no parent.
 	 *
-	 * Throws error if the parent element does not contain this node. This means that model tree got broken.
+	 * Accessing this property throws an error if this node's parent element does not contain it.
+	 * This means that model tree got broken.
 	 *
 	 * @readonly
 	 * @type {Number|Null}

+ 6 - 4
packages/ckeditor5-engine/src/model/nodelist.js

@@ -40,18 +40,20 @@ export default class NodeList {
 	}
 
 	/**
-	 * Returns the number of nodes contained inside this node list.
+	 * Number of nodes contained inside this node list.
 	 *
-	 * @returns {Number}
+	 * @readonly
+	 * @type {Number}
 	 */
 	get length() {
 		return this._nodes.length;
 	}
 
 	/**
-	 * Returns the sum of {engine.model.Node#offsetSize offset sizes} of all nodes contained inside this node list.
+	 * Sum of {@link engine.model.Node#offsetSize offset sizes} of all nodes contained inside this node list.
 	 *
-	 * @returns {Number}
+	 * @readonly
+	 * @type {Number}
 	 */
 	get maxOffset() {
 		return this._nodes.reduce( ( sum, node ) => sum + node.offsetSize, 0 );

+ 6 - 4
packages/ckeditor5-engine/src/model/position.js

@@ -187,18 +187,20 @@ export default class Position {
 	}
 
 	/**
-	 * Returns `true` if position is at the beginning of its {@link engine.model.Position#parent parent}, `false` otherwise.
+	 * Is `true` if position is at the beginning of its {@link engine.model.Position#parent parent}, `false` otherwise.
 	 *
-	 * @returns {Boolean}
+	 * @readonly
+	 * @type {Boolean}
 	 */
 	get isAtStart() {
 		return this.offset === 0;
 	}
 
 	/**
-	 * Returns `true` if position is at the end of its {@link engine.model.Position#parent parent}, `false` otherwise.
+	 * Is `true` if position is at the end of its {@link engine.model.Position#parent parent}, `false` otherwise.
 	 *
-	 * @returns {Boolean}
+	 * @readonly
+	 * @type {Boolean}
 	 */
 	get isAtEnd() {
 		return this.offset == this.parent.maxOffset;

+ 3 - 2
packages/ckeditor5-engine/src/model/textproxy.js

@@ -129,7 +129,7 @@ export default class TextProxy {
 	 * Root of this text proxy, which is same as root of text node represented by this text proxy.
 	 *
 	 * @readonly
-	 * @type {engine.model.Element|engine.model.DocumentFragment}
+	 * @type {engine.model.Node|engine.model.DocumentFragment}
 	 */
 	get root() {
 		return this.textNode.root;
@@ -139,7 +139,8 @@ export default class TextProxy {
 	 * {@link engine.model.Document Document} that owns text node represented by this text proxy or `null` if the text node
 	 * has no parent or is inside a {@link engine.model.DocumentFragment DocumentFragment}.
 	 *
-	 * @returns {engine.model.Document|null}
+	 * @readonly
+	 * @type {engine.model.Document|null}
 	 */
 	get document() {
 		return this.textNode.document;

+ 6 - 4
packages/ckeditor5-engine/src/view/documentfragment.js

@@ -42,18 +42,20 @@ export default class DocumentFragment {
 	}
 
 	/**
-	 * Gets the number of elements in fragment.
+	 * Number of child nodes in this document fragment.
 	 *
-	 * @returns {Number} The number of elements.
+	 * @readonly
+	 * @type {Number} The number of elements.
 	 */
 	get childCount() {
 		return this._children.length;
 	}
 
 	/**
-	 * Returns `true` if there are no nodes inside this document fragment, `false` otherwise.
+	 * Is `true` if there are no nodes inside this document fragment, `false` otherwise.
 	 *
-	 * @returns {Boolean}
+	 * @readonly
+	 * @type {Boolean}
 	 */
 	get isEmpty() {
 		return this.childCount === 0;

+ 2 - 2
packages/ckeditor5-engine/src/view/editableelement.js

@@ -62,9 +62,9 @@ export default class EditableElement extends ContainerElement {
 	}
 
 	/**
-	 * Gets the {@link engine.view.Document} reference.
+	 * {@link engine.view.Document View document} reference that owns this editable element.
 	 *
-	 * @returns {engine.view.Document|null} View Document of the node or `null`.
+	 * @type {engine.view.Document|null}
 	 */
 	get document() {
 		return this._document;

+ 6 - 4
packages/ckeditor5-engine/src/view/element.js

@@ -103,18 +103,20 @@ export default class Element extends Node {
 	}
 
 	/**
-	 * Gets the number of element's children.
+	 * Number of element's children.
 	 *
-	 * @returns {Number} The number of element's children.
+	 * @readonly
+	 * @type {Number}
 	 */
 	get childCount() {
 		return this._children.length;
 	}
 
 	/**
-	 * Returns `true` if there are no nodes inside this element, `false` otherwise.
+	 * Is `true` if there are no nodes inside this element, `false` otherwise.
 	 *
-	 * @returns {Boolean}
+	 * @readonly
+	 * @type {Boolean}
 	 */
 	get isEmpty() {
 		return this._children.length === 0;

+ 18 - 12
packages/ckeditor5-engine/src/view/node.js

@@ -30,11 +30,13 @@ export default class Node {
 	}
 
 	/**
-	 * Returns index of the node in the parent element or null if the node has no parent.
+	 * Index of the node in the parent element or null if the node has no parent.
 	 *
-	 * Throws error if the parent element does not contain this node.
+	 * Accessing this property throws an error if this node's parent element does not contain it.
+	 * This means that view tree got broken.
 	 *
-	 * @returns {Number|null} Index of the node in the parent element or null if the node has not parent.
+	 * @readonly
+	 * @type {Number|null}
 	 */
 	get index() {
 		let pos;
@@ -57,9 +59,10 @@ export default class Node {
 	}
 
 	/**
-	 * Returns nodes next sibling or `null` if it is the last child.
+	 * Node's next sibling, or `null` if it is the last child.
 	 *
-	 * @returns {engine.view.Node|null} Nodes next sibling or `null` if it is the last child.
+	 * @readonly
+	 * @type {engine.view.Node|null}
 	 */
 	get nextSibling() {
 		const index = this.index;
@@ -68,9 +71,10 @@ export default class Node {
 	}
 
 	/**
-	 * Returns nodes previous sibling or `null` if it is the first child.
+	 * Node's previous sibling, or `null` if it is the first child.
 	 *
-	 * @returns {engine.view.Node|null} Nodes previous sibling or `null` if it is the first child.
+	 * @readonly
+	 * @type {engine.view.Node|null}
 	 */
 	get previousSibling() {
 		const index = this.index;
@@ -79,9 +83,10 @@ export default class Node {
 	}
 
 	/**
-	 * Gets the top parent for the node. If node has no parent it is the root itself.
+	 * Top-most ancestor of the node. If the node has no parent it is the root itself.
 	 *
-	 * @returns {engine.view.Node|engine.view.DocumentFragment}
+	 * @readonly
+	 * @type {engine.view.Node|engine.view.DocumentFragment}
 	 */
 	get root() {
 		let root = this;
@@ -94,10 +99,11 @@ export default class Node {
 	}
 
 	/**
-	 * Gets {@link engine.view.Document} reference, from the {@link engine.view.Node#getRoot root} or
-	 * returns null if the root has no reference to the {@link engine.view.Document}.
+	 * {@link engine.view.Document View document} that owns this node, or `null` if the node is inside
+	 * {@link engine.view.DocumentFragment document fragment}.
 	 *
-	 * @returns {engine.view.Document|null} View document of the node or null.
+	 * @readonly
+	 * @type {engine.view.Document|null}
 	 */
 	get document() {
 		// Parent might be Node, null or DocumentFragment.

+ 12 - 8
packages/ckeditor5-engine/src/view/position.js

@@ -69,18 +69,20 @@ export default class Position {
 	}
 
 	/**
-	 * Returns `true` if position is at the beginning of its {@link engine.view.Position#parent parent}, `false` otherwise.
+	 * Is `true` if position is at the beginning of its {@link engine.view.Position#parent parent}, `false` otherwise.
 	 *
-	 * @returns {Boolean}
+	 * @readonly
+	 * @type {Boolean}
 	 */
 	get isAtStart() {
 		return this.offset === 0;
 	}
 
 	/**
-	 * Returns `true` if position is at the end of its {@link engine.view.Position#parent parent}, `false` otherwise.
+	 * Is `true` if position is at the end of its {@link engine.view.Position#parent parent}, `false` otherwise.
 	 *
-	 * @returns {Boolean}
+	 * @readonly
+	 * @type {Boolean}
 	 */
 	get isAtEnd() {
 		const endOffset = this.parent instanceof Text ? this.parent.data.length : this.parent.childCount;
@@ -89,18 +91,20 @@ export default class Position {
 	}
 
 	/**
-	 * Returns position root, that is the root of the position's parent element.
+	 * Position's root, that is the root of the position's parent element.
 	 *
-	 * @returns {engine.view.Node|engine.view.DocumentFragment} Position's root.
+	 * @readonly
+	 * @type {engine.view.Node|engine.view.DocumentFragment}
 	 */
 	get root() {
 		return this.parent.root;
 	}
 
 	/**
-	 * Returns {@link engine.view.EditableElement EditableElement} instance that contains this position.
+	 * {@link engine.view.EditableElement EditableElement} instance that contains this position, or `null` if
+	 * position is not inside an editable element.
 	 *
-	 * @returns {engine.view.EditableElement|null} Returns closest EditableElement or null if none is found.
+	 * @type {engine.view.EditableElement|null}
 	 */
 	get editableElement() {
 		let editable = this.parent;

+ 3 - 2
packages/ckeditor5-engine/src/view/selection.js

@@ -111,9 +111,10 @@ export default class Selection {
 	}
 
 	/**
-	 * Returns {@link engine.view.EditableElement EditableElement} instance that contains this selection.
+	 * {@link engine.view.EditableElement EditableElement} instance that contains this selection, or `null`
+	 * if the selection is not inside an editable element.
 	 *
-	 * @returns {engine.view.EditableElement|null} Returns closest EditableElement or null if none is found.
+	 * @type {engine.view.EditableElement|null}
 	 */
 	get editableElement() {
 		if ( this.rangeCount ) {

+ 8 - 6
packages/ckeditor5-engine/src/view/textproxy.js

@@ -68,7 +68,7 @@ export default class TextProxy {
 	}
 
 	/**
-	 * Element that is a parent of this text proxy.
+	 * Parent of this text proxy, which is same as parent of text node represented by this text proxy.
 	 *
 	 * @readonly
 	 * @type {engine.view.Element|engine.view.DocumentFragment|null}
@@ -78,19 +78,21 @@ export default class TextProxy {
 	}
 
 	/**
-	 * Gets the top parent for the {#textNode}. If there is no parent {#textNode} is the root.
+	 * Root of this text proxy, which is same as root of text node represented by this text proxy.
 	 *
-	 * @returns {engine.view.Node}
+	 * @readonly
+	 * @type {engine.view.Node|engine.view.DocumentFragment}
 	 */
 	get root() {
 		return this.textNode.root;
 	}
 
 	/**
-	 * Gets {@link engine.view.Document} reference, from the {@link engine.view.Node#getRoot root} of
-	 * {#textNode} or returns null if the root has no reference to the {@link engine.view.Document}.
+	 * {@link engine.view.Document View document} that owns this text proxy, or `null` if the text proxy is inside
+	 * {@link engine.view.DocumentFragment document fragment}.
 	 *
-	 * @returns {engine.view.Document|null} View Document of the text proxy or null.
+	 * @readonly
+	 * @type {engine.view.Document|null}
 	 */
 	get document() {
 		return this.textNode.document;