ソースを参照

API docs: Cleaned up Iterable/Iterator/Generator confusion. See https://github.com/ckeditor/ckeditor5/issues/755. [skip ci]

Piotrek Koszuliński 8 年 前
コミット
72cd67e752

+ 8 - 5
packages/ckeditor5-engine/src/conversion/definition-based-converters.js

@@ -323,11 +323,14 @@ function createViewElementFromDefinition( viewElementDefinition, ViewElementClas
 }
 
 /**
- * Defines conversion details. It is used in configuration based converters:
- * - {@link module:engine/conversion/definition-based-converters~modelAttributeToViewAttributeElement}
- * - {@link module:engine/conversion/definition-based-converters~modelElementToViewContainerElement}
- * - {@link module:engine/conversion/definition-based-converters~viewToModelAttribute}
- * - {@link module:engine/conversion/definition-based-converters~viewToModelElement}
+ * Defines conversion details. It is used in configuration-based converters:
+ *
+ * * {@link module:engine/conversion/definition-based-converters~modelAttributeToViewAttributeElement}
+ * * {@link module:engine/conversion/definition-based-converters~modelElementToViewContainerElement}
+ * * {@link module:engine/conversion/definition-based-converters~viewToModelAttribute}
+ * * {@link module:engine/conversion/definition-based-converters~viewToModelElement}
+ *
+ * See the above converters for examples how to use the converter definition.
  *
  * @typedef {Object} ConverterDefinition
  * @property {String} model Defines to model conversion. When using to element conversion

+ 1 - 1
packages/ckeditor5-engine/src/model/documentfragment.js

@@ -54,7 +54,7 @@ export default class DocumentFragment {
 	/**
 	 * Returns an iterator that iterates over all nodes contained inside this document fragment.
 	 *
-	 * @returns {Iterator.<module:engine/model/node~Node>}
+	 * @returns {Iterable.<module:engine/model/node~Node>}
 	 */
 	[ Symbol.iterator ]() {
 		return this.getChildren();

+ 3 - 3
packages/ckeditor5-engine/src/model/documentselection.js

@@ -521,7 +521,7 @@ export default class DocumentSelection extends Selection {
 	 * `directChange` parameter).
 	 *
 	 * @private
-	 * @param {Iterable|Object} attrs Iterable object containing attributes to be set.
+	 * @param {Map} attrs Iterable object containing attributes to be set.
 	 * @param {Boolean} [directChange=true] `true` if the change is caused by `Selection` API, `false` if change
 	 * is caused by `Batch` API.
 	 * @returns {Set.<String>} Changed attribute keys.
@@ -606,7 +606,7 @@ export default class DocumentSelection extends Selection {
 	 * Sets selection attributes stored in current selection's parent node to given set of attributes.
 	 *
 	 * @private
-	 * @param {Iterable|Object} attrs Iterable object containing attributes to be set.
+	 * @param {Iterable} attrs Iterable object containing attributes to be set.
 	 */
 	_setStoredAttributesTo( attrs ) {
 		const selectionParent = this.anchor.parent;
@@ -741,7 +741,7 @@ export default class DocumentSelection extends Selection {
 // It takes model item, checks whether it is a text node (or text proxy) and, if so, returns it's attributes. If not, returns `null`.
 //
 // @param {module:engine/model/item~Item|null}  node
-// @returns {Boolean}
+// @returns {Boolean|Iterable}
 function getAttrsIfCharacter( node ) {
 	if ( node instanceof TextProxy || node instanceof Text ) {
 		return node.getAttributes();

+ 1 - 1
packages/ckeditor5-engine/src/model/history.js

@@ -76,7 +76,7 @@ export default class History {
 	 * that deltas from the first one will be returned.
 	 * @param {Number} [to=Number.POSITIVE_INFINITY] Base version up to which deltas should be returned (exclusive).
 	 * Defaults to `Number.POSITIVE_INFINITY` which means that deltas up to the last one will be returned.
-	 * @returns {Iterator.<module:engine/model/delta/delta~Delta>} Deltas added to the history from given base versions range.
+	 * @returns {Iterable.<module:engine/model/delta/delta~Delta>} Deltas added to the history from given base versions range.
 	 */
 	* getDeltas( from = 0, to = Number.POSITIVE_INFINITY ) {
 		// No deltas added, nothing to yield.

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

@@ -39,9 +39,11 @@ export default class MarkerCollection {
 	}
 
 	/**
-	 * Returns an iterator that iterates over all {@link ~Marker markers} added to the collection.
+	 * Iterable interface.
 	 *
-	 * @returns {Iterator}
+	 * Iterates over all {@link ~Marker markers} added to the collection.
+	 *
+	 * @returns {Iterable}
 	 */
 	[ Symbol.iterator ]() {
 		return this._markers.values();
@@ -131,7 +133,7 @@ export default class MarkerCollection {
 	 * Returns iterator that iterates over all markers, which ranges contain given {@link module:engine/model/position~Position position}.
 	 *
 	 * @param {module:engine/model/position~Position} position
-	 * @returns {Iterator.<module:engine/model/markercollection~Marker>}
+	 * @returns {Iterable.<module:engine/model/markercollection~Marker>}
 	 */
 	* getMarkersAtPosition( position ) {
 		for ( const marker of this ) {
@@ -165,7 +167,7 @@ export default class MarkerCollection {
 	 *		Array.from( markersCollection.getMarkersGroup( 'a' ) ); // []
 	 *
 	 * @param prefix
-	 * @returns {Iterator.<module:engine/model/markercollection~Marker>}
+	 * @returns {Iterable.<module:engine/model/markercollection~Marker>}
 	 */
 	* getMarkersGroup( prefix ) {
 		for ( const marker of this._markers.values() ) {

+ 1 - 1
packages/ckeditor5-engine/src/model/node.js

@@ -324,7 +324,7 @@ export default class Node {
 	/**
 	 * Returns iterator that iterates over this node's attribute keys.
 	 *
-	 * @returns {Iterator.<String>}
+	 * @returns {Iterable.<String>}
 	 */
 	getAttributeKeys() {
 		return this._attrs.keys();

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

@@ -36,9 +36,11 @@ export default class NodeList {
 	}
 
 	/**
-	 * Returns an iterator that iterates over all nodes contained inside this node list.
+	 * Iterable interface.
 	 *
-	 * @returns {Iterator.<module:engine/model/node~Node>}
+	 * Iterates over all nodes contained inside this node list.
+	 *
+	 * @returns {Iterable.<module:engine/model/node~Node>}
 	 */
 	[ Symbol.iterator ]() {
 		return this._nodes[ Symbol.iterator ]();

+ 3 - 1
packages/ckeditor5-engine/src/model/range.js

@@ -42,7 +42,9 @@ export default class Range {
 	}
 
 	/**
-	 * Returns an iterator that iterates over all {@link module:engine/model/item~Item items} that are in this range and returns
+	 * Iterable interface.
+	 *
+	 * Iterates over all {@link module:engine/model/item~Item items} that are in this range and returns
 	 * them together with additional information like length or {@link module:engine/model/position~Position positions},
 	 * grouped as {@link module:engine/model/treewalker~TreeWalkerValue}.
 	 * It iterates over all {@link module:engine/model/textproxy~TextProxy text contents} that are inside the range

+ 5 - 3
packages/ckeditor5-engine/src/model/schema.js

@@ -907,9 +907,11 @@ export class SchemaContext {
 	}
 
 	/**
-	 * Returns an iterator that iterates over all context items.
+	 * Iterable interface.
 	 *
-	 * @returns {Iterator.<module:engine/model/schema~SchemaContextItem>}
+	 * Iterates over all context items.
+	 *
+	 * @returns {Iterable.<module:engine/model/schema~SchemaContextItem>}
 	 */
 	[ Symbol.iterator ]() {
 		return this._items[ Symbol.iterator ]();
@@ -927,7 +929,7 @@ export class SchemaContext {
 	/**
 	 * Returns the names of items.
 	 *
-	 * @returns {Iterator.<String>}
+	 * @returns {Iterable.<String>}
 	 */
 	* getNames() {
 		yield* this._items.map( item => item.name );

+ 3 - 3
packages/ckeditor5-engine/src/model/selection.js

@@ -176,7 +176,7 @@ export default class Selection {
 	/**
 	 * Returns an iterator that iterates over copies of selection ranges.
 	 *
-	 * @returns {Iterator.<module:engine/model/range~Range>}
+	 * @returns {Iterable.<module:engine/model/range~Range>}
 	 */
 	* getRanges() {
 		for ( const range of this._ranges ) {
@@ -487,7 +487,7 @@ export default class Selection {
 	/**
 	 * Returns iterator that iterates over this selection's attribute keys.
 	 *
-	 * @returns {Iterator.<String>}
+	 * @returns {Iterable.<String>}
 	 */
 	getAttributeKeys() {
 		return this._attrs.keys();
@@ -629,7 +629,7 @@ export default class Selection {
 	 *		<paragraph>b</paragraph>
 	 *		<paragraph>]c</paragraph> // this block will not be returned
 	 *
-	 * @returns {Iterator.<module:engine/model/element~Element>}
+	 * @returns {Iterable.<module:engine/model/element~Element>}
 	 */
 	* getSelectedBlocks() {
 		const visited = new WeakSet();

+ 1 - 1
packages/ckeditor5-engine/src/model/textproxy.js

@@ -256,7 +256,7 @@ export default class TextProxy {
 	/**
 	 * Returns iterator that iterates over this node's attribute keys.
 	 *
-	 * @returns {Iterator.<String>}
+	 * @returns {Iterable.<String>}
 	 */
 	getAttributeKeys() {
 		return this.textNode.getAttributeKeys();

+ 5 - 4
packages/ckeditor5-engine/src/model/treewalker.js

@@ -146,7 +146,9 @@ export default class TreeWalker {
 	}
 
 	/**
-	 * Iterator interface.
+	 * Iterable interface.
+	 *
+	 * @returns {Iterable.<module:engine/model/treewalker~TreeWalkerValue>}
 	 */
 	[ Symbol.iterator ]() {
 		return this;
@@ -181,10 +183,9 @@ export default class TreeWalker {
 	}
 
 	/**
-	 * Iterator interface method.
-	 * Detects walking direction and makes step forward or backward.
+	 * Gets the next tree walker's value.
 	 *
-	 * @returns {Object} Object implementing iterator interface, returning information about taken step.
+	 * @returns {module:engine/model/treewalker~TreeWalkerValue} Next tree walker's value.
 	 */
 	next() {
 		if ( this.direction == 'forward' ) {

+ 5 - 1
packages/ckeditor5-engine/src/view/documentfragment.js

@@ -38,7 +38,11 @@ export default class DocumentFragment {
 	}
 
 	/**
-	 * Iterates over nodes added to this DocumentFragment.
+	 * Iterable interface.
+	 *
+	 * Iterates over nodes added to this document fragment.
+	 *
+	 * @returns {Iterable.<module:engine/view/node~Node>}
 	 */
 	[ Symbol.iterator ]() {
 		return this._children[ Symbol.iterator ]();

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

@@ -233,7 +233,7 @@ export default class Element extends Node {
 	/**
 	 * Returns an iterator that contains the keys for attributes. Order of inserting attributes is not preserved.
 	 *
-	 * @returns {Iterator.<String>} Keys for attributes.
+	 * @returns {Iterable.<String>} Keys for attributes.
 	 */
 	* getAttributeKeys() {
 		if ( this._classes.size > 0 ) {
@@ -528,7 +528,7 @@ export default class Element extends Node {
 	/**
 	 * Returns iterator that contains all class names.
 	 *
-	 * @returns {Iterator.<String>}
+	 * @returns {Iterable.<String>}
 	 */
 	getClassNames() {
 		return this._classes.keys();
@@ -575,7 +575,7 @@ export default class Element extends Node {
 	/**
 	 * Returns iterator that contains all style names.
 	 *
-	 * @returns {Iterator.<String>}
+	 * @returns {Iterable.<String>}
 	 */
 	getStyleNames() {
 		return this._styles.keys();
@@ -671,7 +671,7 @@ export default class Element extends Node {
 
 	/**
 	 * Returns an iterator which iterates over this element's custom properties.
-	 * Iterator provides [key, value] pair for each stored property.
+	 * Iterator provides `[ key, value ]` pairs for each stored property.
 	 *
 	 * @returns {Iterable.<*>}
 	 */

+ 3 - 1
packages/ckeditor5-engine/src/view/range.js

@@ -39,7 +39,9 @@ export default class Range {
 	}
 
 	/**
-	 * Returns an iterator that iterates over all {@link module:engine/view/item~Item view items} that are in this range and returns
+	 * Iterable interface.
+	 *
+	 * Iterates over all {@link module:engine/view/item~Item view items} that are in this range and returns
 	 * them together with additional information like length or {@link module:engine/view/position~Position positions},
 	 * grouped as {@link module:engine/view/treewalker~TreeWalkerValue}.
 	 *

+ 1 - 1
packages/ckeditor5-engine/src/view/selection.js

@@ -224,7 +224,7 @@ export default class Selection {
 	/**
 	 * Returns an iterator that contains copies of all ranges added to the selection.
 	 *
-	 * @returns {Iterator.<module:engine/view/range~Range>}
+	 * @returns {Iterable.<module:engine/view/range~Range>}
 	 */
 	* getRanges() {
 		for ( const range of this._ranges ) {

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

@@ -132,7 +132,9 @@ export default class TreeWalker {
 	}
 
 	/**
-	 * Iterator interface.
+	 * Iterable interface.
+	 *
+	 * @returns {Iterable.<module:engine/view/treewalker~TreeWalkerValue>}
 	 */
 	[ Symbol.iterator ]() {
 		return this;
@@ -165,10 +167,10 @@ export default class TreeWalker {
 	}
 
 	/**
-	 * Iterator interface method.
-	 * Detects walking direction and makes step forward or backward.
+	 * Gets the next tree walker's value.
 	 *
-	 * @returns {Object} Object implementing iterator interface, returning information about taken step.
+	 * @returns {module:engine/view/treewalker~TreeWalkerValue} Object implementing iterator interface, returning
+	 * information about taken step.
 	 */
 	next() {
 		if ( this.direction == 'forward' ) {