Переглянути джерело

Documentation: update core.treemodel documentation.

Maciej Gołaszewski 9 роки тому
батько
коміт
9f49751ab4

+ 13 - 10
packages/ckeditor5-engine/src/treemodel/batch-base.js

@@ -8,12 +8,6 @@
 import CKEditorError from '../ckeditorerror.js';
 
 /**
- * Creates Batch instance. Not recommended to use directly, use {@link treeModel.Document#batch} instead.
- *
- * @param {treeModel.Document} doc Document which this Batch changes.
- *
- * @class core.treeModel.Batch
- * @classdesc
  * The Batch class groups document changes (deltas). All deltas grouped in a single Batch can be
  * reverted together, so you can think about the Batch as a single undo step. If you want to extend one
  * undo step you can call another method on the same Batch object. If you want to create a separate undo step
@@ -34,22 +28,30 @@ import CKEditorError from '../ckeditorerror.js';
  *
  *		doc.batch().insert( firstPosition, 'foo' ).insert( secondPosition, 'bar' );
  *
+ * @memberOf core.treeModel
  */
 export default class Batch {
+	/**
+	 * Creates Batch instance. Not recommended to use directly, use {@link core.treeModel.Document#batch} instead.
+	 *
+	 * @param {core.treeModel.Document} doc Document which this Batch changes.
+	 */
 	constructor( doc ) {
 		/**
 		 * Document which this Batch changes.
 		 *
+		 * @member core.treeModel.Batch#doc
 		 * @readonly
-		 * @type {treeModel.Document}
+		 * @type {core.treeModel.Document}
 		 */
 		this.doc = doc;
 
 		/**
 		 * Array of deltas which compose Batch.
 		 *
+		 * @member core.treeModel.Batch#deltas
 		 * @readonly
-		 * @type {Array.<treeModel.delta.Delta>}
+		 * @type {Array.<core.treeModel.delta.Delta>}
 		 */
 		this.deltas = [];
 	}
@@ -58,8 +60,8 @@ export default class Batch {
 	 * Adds delta to the Batch instance. All modification methods (insert, remove, split, etc.) use this method
 	 * to add created deltas.
 	 *
-	 * @param {treeModel.delta.Delta} delta Delta to add.
-	 * @return {treeModel.delta.Delta} Added delta.
+	 * @param {core.treeModel.delta.Delta} delta Delta to add.
+	 * @return {core.treeModel.delta.Delta} Added delta.
 	 */
 	addDelta( delta ) {
 		delta.batch = this;
@@ -100,6 +102,7 @@ export default class Batch {
  *			return this;
  *		} );
  *
+ * @method core.treeModel.Batch.register
  * @param {String} name Method name.
  * @param {Function} creator Method body.
  */

+ 9 - 9
packages/ckeditor5-engine/src/treemodel/characterproxy.js

@@ -18,21 +18,21 @@ import Node from './node.js';
  *
  * CharacterProxy is created on the fly basing on tree model. It is not an explicit node in a tree model but
  * rather represents it. Because of this, it is not advised to store or compare instances of CharacterProxy class.
- * If you want to keep live reference to a point in a text, you should use {@link treeModel.LivePosition}.
+ * If you want to keep live reference to a point in a text, you should use {@link core.treeModel.LivePosition}.
  *
  * You should never create an instance of this class by your own. When passing parameters to constructors,
- * use string literals or {@link treeModel.Text} instead.
+ * use string literals or {@link core.treeModel.Text} instead.
  *
- * @class treeModel.CharacterProxy
+ * @memberOf core.treeModel
+ * @extends core.treeModel.Node
  */
 export default class CharacterProxy extends Node {
 	/**
 	 * Creates character node proxy.
 	 *
-	 * @param {treeModel.NodeListText} nodeListText Reference to a text object in a node list containing this character.
+	 * @param {core.treeModel.NodeListText} nodeListText Reference to a text object in a node list containing this character.
 	 * @param {Number} index Index of the character in `nodeListText`.
 	 * @protected
-	 * @constructor
 	 */
 	constructor( nodeListText, index ) {
 		super( nodeListText._attrs );
@@ -42,7 +42,7 @@ export default class CharacterProxy extends Node {
 		 *
 		 * @protected
 		 * @readonly
-		 * @type {treeModel.NodeListText}
+		 * @member {core.treeModel.NodeListText} core.treeModel.CharacterProxy#_nodeListText
 		 */
 		this._nodeListText = nodeListText;
 
@@ -51,7 +51,7 @@ export default class CharacterProxy extends Node {
 		 *
 		 * @protected
 		 * @readonly
-		 * @type {Number}
+		 * @member {Number} core.treeModel.CharacterProxy#_index
 		 */
 		this._index = index;
 
@@ -60,12 +60,12 @@ export default class CharacterProxy extends Node {
 		 *
 		 * @protected
 		 * @readonly
-		 * @type {String}
+		 * @member {String} core.treeModel.CharacterProxy#character
 		 */
 		this.character = nodeListText.text.substr( index, 1 );
 
 		/**
-		 * @see {@link treeModel.Node#parent}
+		 * @inheritdoc
 		 */
 		this.parent = this._nodeListText.parent;
 	}

+ 5 - 5
packages/ckeditor5-engine/src/treemodel/delta/delta.js

@@ -14,18 +14,18 @@
  * Delta is a single, from the user action point of view, change in the editable document, like insert, split or
  * rename element. Delta is composed of operations, which are unit changes needed to be done to execute user action.
  *
- * Multiple deltas are grouped into a single {@link treeModel.Batch}.
+ * Multiple deltas are grouped into a single {@link core.treeModel.Batch}.
  *
  * @class core.treeModel.delta.Delta
  */
 export default class Delta {
 	constructor() {
 		/**
-		 * {@link treeModel.Batch} which delta is a part of. This property is null by default and set by the
-		 * {@link treeModel.Batch#addDelta} method.
+		 * {@link core.treeModel.Batch} which delta is a part of. This property is null by default and set by the
+		 * {@link core.treeModel.Batch#addDelta} method.
 		 *
 		 * @readonly
-		 * @type {treeModel.Batch}
+		 * @type {core.treeModel.Batch}
 		 */
 		this.batch = null;
 
@@ -33,7 +33,7 @@ export default class Delta {
 		 * Array of operations which compose delta.
 		 *
 		 * @readonly
-		 * @type {treeModel.operation.Operation[]}
+		 * @type {core.treeModel.operation.Operation[]}
 		 */
 		this.operations = [];
 	}

+ 35 - 36
packages/ckeditor5-engine/src/treemodel/document.js

@@ -15,40 +15,39 @@ import utils from '../utils.js';
 const graveyardSymbol = Symbol( 'graveyard' );
 
 /**
- * Document tree model describes all editable data in the editor. It may contain multiple {@link #roots root elements},
- * for example if the editor have multiple editable areas, each area will be represented by the separate root.
+ * Document tree model describes all editable data in the editor. It may contain multiple
+ * {@link core.treeModel.Document#roots root elements}, for example if the editor have multiple editable areas, each area will be
+ * represented by the separate root.
  *
- * All changes in the document are done by {@link treeModel.operation.Operation operations}. To create operations in
- * the simple way use use the {@link treeModel.Batch} API, for example:
+ * All changes in the document are done by {@link core.treeModel.operation.Operation operations}. To create operations in
+ * the simple way use use the {@link core.treeModel.Batch} API, for example:
  *
  *		doc.batch().insert( position, nodes ).split( otherPosition );
  *
- * @see #batch
+ * @see core.treeModel.Document#batch
  *
- * @class treeModel.Document
+ * @memberOf core.treeModel
  */
 export default class Document {
 	/**
-	 * Creates an empty document instance with no {@link #roots} (other than graveyard).
-	 *
-	 * @constructor
+	 * Creates an empty document instance with no {@link core.treeModel.Document#roots} (other than graveyard).
 	 */
 	constructor() {
 		/**
 		 * List of roots that are owned and managed by this document.
 		 *
 		 * @readonly
-		 * @type {Map}
+		 * @member {Map} core.treeModel.Document#roots
 		 */
 		this.roots = new Map();
 
 		/**
 		 * 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 treeModel.operation.Operation#baseVersion} will
+		 * operations are applied on the proper document version. If the {@link core.treeModel.operation.Operation#baseVersion} will
 		 * not match document version the {@link document-applyOperation-wrong-version} error is thrown.
 		 *
 		 * @readonly
-		 * @type {Number}
+		 * @member {Number} core.treeModel.Document#version
 		 */
 		this.version = 0;
 
@@ -56,10 +55,10 @@ export default class Document {
 		this.createRoot( graveyardSymbol );
 
 		/**
-		 * Array of pending changes. See: {@link #enqueueChanges}.
+		 * Array of pending changes. See: {@link core.treeModel.Document#enqueueChanges}.
 		 *
 		 * @private
-		 * @type {Array.<Function>}
+		 * @member {Array.<Function>} core.treeModel.Document#_pendingChanges
 		 */
 		this._pendingChanges = [];
 
@@ -67,7 +66,7 @@ export default class Document {
 		 * Selection done on this document.
 		 *
 		 * @readonly
-		 * @type {treeModel.Selection}
+		 * @member {core.treeModel.Selection} core.treeModel.Document#selection
 		 */
 		this.selection = new Selection();
 	}
@@ -76,7 +75,7 @@ export default class Document {
 	 * Graveyard tree root. Document always have a graveyard root, which stores removed nodes.
 	 *
 	 * @readonly
-	 * @type {treeModel.RootElement}
+	 * @type {core.treeModel.RootElement}
 	 */
 	get graveyard() {
 		return this.getRoot( graveyardSymbol );
@@ -84,12 +83,12 @@ export default class Document {
 
 	/**
 	 * This is the entry point for all document changes. All changes on the document are done using
-	 * {@link treeModel.operation.Operation operations}. To create operations in the simple way use the
-	 * {@link treeModel.Batch} API available via {@link #batch} method.
+	 * {@link core.treeModel.operation.Operation operations}. To create operations in the simple way use the
+	 * {@link core.treeModel.Batch} API available via {@link core.treeModel.Document#batch} method.
 	 *
-	 * This method calls {@link #change} event.
+	 * This method calls {@link core.treeModel.Document#change} event.
 	 *
-	 * @param {treeModel.operation.Operation} operation Operation to be applied.
+	 * @param {core.treeModel.operation.Operation} operation Operation to be applied.
 	 */
 	applyOperation( operation ) {
 		if ( operation.baseVersion !== this.version ) {
@@ -97,7 +96,7 @@ export default class Document {
 			 * Only operations with matching versions can be applied.
 			 *
 			 * @error document-applyOperation-wrong-version
-			 * @param {treeModel.operation.Operation} operation
+			 * @param {core.treeModel.operation.Operation} operation
 			 */
 			throw new CKEditorError(
 				'document-applyOperation-wrong-version: Only operations with matching versions can be applied.',
@@ -113,9 +112,9 @@ export default class Document {
 	}
 
 	/**
-	 * Creates a {@link treeModel.Batch} instance which allows to change the document.
+	 * Creates a {@link core.treeModel.Batch} instance which allows to change the document.
 	 *
-	 * @returns {treeModel.Batch} Batch instance.
+	 * @returns {core.treeModel.Batch} Batch instance.
 	 */
 	batch() {
 		return new Batch( this );
@@ -125,7 +124,7 @@ export default class Document {
 	 * Creates a new top-level root.
 	 *
 	 * @param {String|Symbol} name Unique root name.
-	 * @returns {treeModel.RootElement} Created root.
+	 * @returns {core.treeModel.RootElement} Created root.
 	 */
 	createRoot( name ) {
 		if ( this.roots.has( name ) ) {
@@ -133,7 +132,7 @@ export default class Document {
 			 * Root with specified name already exists.
 			 *
 			 * @error document-createRoot-name-exists
-			 * @param {treeModel.Document} doc
+			 * @param {core.treeModel.Document} doc
 			 * @param {String} name
 			 */
 			throw new CKEditorError(
@@ -149,12 +148,12 @@ export default class Document {
 	}
 
 	/**
-	 * Enqueue a callback with document changes. Any changes to be done on document (mostly using {@link #batch} should
+	 * Enqueue a callback with document changes. Any changes to be done on document (mostly using {@link core.treeModel.Document#batch} should
 	 * be placed in the queued callback. If no other plugin is changing document at the moment, the callback will be
 	 * called immediately. Otherwise it will wait for all previously queued changes to finish happening. This way
 	 * queued callback will not interrupt other callbacks.
 	 *
-	 * When all queued changes are done {@link #changesDone} event is fired.
+	 * When all queued changes are done {@link core.treeModel.Document#changesDone} event is fired.
 	 *
 	 * @param {Function} callback Callback to enqueue.
 	 */
@@ -175,7 +174,7 @@ export default class Document {
 	 * Returns top-level root by it's name.
 	 *
 	 * @param {String|Symbol} name Name of the root to get.
-	 * @returns {treeModel.RootElement} Root registered under given name.
+	 * @returns {core.treeModel.RootElement} Root registered under given name.
 	 */
 	getRoot( name ) {
 		if ( !this.roots.has( name ) ) {
@@ -208,25 +207,25 @@ export default class Document {
 	 * Change event is fired after the change is done. This means that any ranges or positions passed in
 	 * `changeInfo` are referencing nodes and paths in updated tree model.
 	 *
-	 * @event change
+	 * @event core.treeModel.Document.change
 	 * @param {String} type Change type, possible option: 'insert', 'remove', 'reinsert', 'move', 'attribute'.
 	 * @param {Object} changeInfo Additional information about the change.
-	 * @param {treeModel.Range} changeInfo.range Range containing changed nodes. Note that for 'remove' the range will be in the
-	 * {@link #graveyard graveyard root}.
-	 * @param {treeModel.Position} [changeInfo.sourcePosition] Change source position. Exists for 'remove', 'reinsert' and 'move'.
-	 * Note that for 'reinsert' the source position will be in the {@link #graveyard graveyard root}.
+	 * @param {core.treeModel.Range} changeInfo.range Range containing changed nodes. Note that for 'remove' the range will be in the
+	 * {@link core.treeModel.Document#graveyard graveyard root}.
+	 * @param {core.treeModel.Position} [changeInfo.sourcePosition] Change source position. Exists for 'remove', 'reinsert' and 'move'.
+	 * Note that for 'reinsert' the source position will be in the {@link core.treeModel.Document#graveyard graveyard root}.
 	 * @param {String} [changeInfo.key] Only for 'attribute' type. Key of changed / inserted / removed attribute.
 	 * @param {*} [changeInfo.oldValue] Only for 'attribute' type. If the type is 'attribute' and `oldValue`
 	 * is `undefined` it means that new attribute was inserted. Otherwise it contains changed or removed attribute value.
 	 * @param {*} [changeInfo.newValue] Only for 'attribute' type. If the type is 'attribute' and `newValue`
 	 * is `undefined` it means that attribute was removed. Otherwise it contains changed or inserted attribute value.
-	 * @param {treeModel.Batch} {@link treeModel.Batch} of changes which this change is a part of.
+	 * @param {core.treeModel.Batch} batch A {@link core.treeModel.Batch batch} of changes which this change is a part of.
 	 */
 
 	/**
-	 * Fired when all queued document changes are done. See {@link #enqueueChanges}.
+	 * Fired when all queued document changes are done. See {@link core.treeModel.Document#enqueueChanges}.
 	 *
-	 * @event changesDone
+	 * @event core.treeModel.Document.changesDone
 	 */
 }
 

+ 26 - 16
packages/ckeditor5-engine/src/treemodel/element.js

@@ -12,7 +12,7 @@ import utils from '../utils.js';
 /**
  * Tree data model element.
  *
- * @class treeModel.Element
+ * @memberOf core.treeModel
  */
 export default class Element extends Node {
 	/**
@@ -20,9 +20,8 @@ export default class Element extends Node {
 	 *
 	 * @param {String} name Node name.
 	 * @param {Iterable} attrs Iterable collection of attributes.
-	 * @param {treeModel.NodeSet} children List of nodes to be inserted
-	 * into created element. List of nodes can be of any type accepted by the {@link treeModel.NodeList} constructor.
-	 * @constructor
+	 * @param {core.treeModel.NodeSet} children List of nodes to be inserted
+	 * into created element. List of nodes can be of any type accepted by the {@link core.treeModel.NodeList} constructor.
 	 */
 	constructor( name, attrs, children ) {
 		super( attrs );
@@ -39,7 +38,7 @@ export default class Element extends Node {
 		 * List of children nodes.
 		 *
 		 * @protected
-		 * @type {treeModel.NodeList}
+		 * @type {core.treeModel.NodeList}
 		 */
 		this._children = new NodeList();
 
@@ -51,8 +50,9 @@ export default class Element extends Node {
 	/**
 	 * Gets child at the given index.
 	 *
+	 * @method core.treeModel.Element#getChild
 	 * @param {Number} index Index of child.
-	 * @returns {treeModel.Node} Child node.
+	 * @returns {core.treeModel.Node} Child node.
 	 */
 	getChild( index ) {
 		return this._children.get( index );
@@ -61,6 +61,7 @@ export default class Element extends Node {
 	/**
 	 * Gets the number of element's children.
 	 *
+	 * @method core.treeModel.Element#getChildCount
 	 * @returns {Number} The number of element's children.
 	 */
 	getChildCount() {
@@ -70,7 +71,8 @@ export default class Element extends Node {
 	/**
 	 * Gets index of the given child node.
 	 *
-	 * @param {treeModel.Node} node Child node.
+	 * @method core.treeModel.Element#getChildIndex
+	 * @param {core.treeModel.Node} node Child node.
 	 * @returns {Number} Index of the child node.
 	 */
 	getChildIndex( node ) {
@@ -78,13 +80,14 @@ export default class Element extends Node {
 	}
 
 	/**
-	 * {@link treeModel.Element#insert Inserts} a child node or a list of child nodes at the end of this node and sets
+	 * {@link core.treeModel.Element#insert Inserts} a child node or a list of child nodes at the end of this node and sets
 	 * the parent of these nodes to this element.
 	 *
 	 * 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 treeModel.operation.InsertOperation}.
+	 * All attached nodes should be modified using the {@link core.treeModel.operation.InsertOperation}.
 	 *
-	 * @param {treeModel.NodeSet} nodes The list of nodes to be inserted.
+	 * @method core.treeModel.Element#appendChildren
+	 * @param {core.treeModel.NodeSet} nodes The list of nodes to be inserted.
 	 */
 	appendChildren( nodes ) {
 		this.insertChildren( this.getChildCount(), nodes );
@@ -94,11 +97,12 @@ export default class Element extends Node {
 	 * Inserts a list of child nodes on the given index and sets the parent of these nodes to this element.
 	 *
 	 * 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 treeModel.operation.InsertOperation}.
+	 * All attached nodes should be modified using the {@link core.treeModel.operation.InsertOperation}.
 	 *
+	 * @method core.treeModel.Element#insertChildren
 	 * @param {Number} index Position where nodes should be inserted.
-	 * @param {treeModel.NodeSet} nodes The list of nodes to be inserted.
-	 * The list of nodes can be of any type accepted by the {@link treeModel.NodeList} constructor.
+	 * @param {core.treeModel.NodeSet} nodes The list of nodes to be inserted.
+	 * The list of nodes can be of any type accepted by the {@link core.treeModel.NodeList} constructor.
 	 */
 	insertChildren( index, nodes ) {
 		let nodeList = new NodeList( nodes );
@@ -114,11 +118,12 @@ export default class Element extends Node {
 	 * Removes number of child nodes starting at the given index and set the parent of these nodes to `null`.
 	 *
 	 * 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 treeModel.operation.RemoveOperation}.
+	 * All attached nodes should be modified using the {@link core.treeModel.operation.RemoveOperation}.
 	 *
+	 * @method core.treeModel.Element#removeChildren
 	 * @param {Number} index Position of the first node to remove.
 	 * @param {Number} number Number of nodes to remove.
-	 * @returns {treeModel.NodeList} The list of removed nodes.
+	 * @returns {core.treeModel.NodeList} The list of removed nodes.
 	 */
 	removeChildren( index, number ) {
 		let nodeList = this._children.remove( index, number );
@@ -133,6 +138,7 @@ export default class Element extends Node {
 	/**
 	 * Sets attribute on the element. If attribute with the same key already is set, it overwrites its values.
 	 *
+	 * @method core.treeModel.Element#setAttribute
 	 * @param {String} key Key of attribute to set.
 	 * @param {*} value Attribute value.
 	 */
@@ -143,7 +149,8 @@ export default class Element extends Node {
 	/**
 	 * Removes all attributes from the element and sets given attributes.
 	 *
-	 * @param {Iterable|Object} attrs Iterable object containing attributes to be set. See {@link treeModel.Node#getAttributes}.
+	 * @method core.treeModel.Element#setAttributesTo
+	 * @param {Iterable|Object} attrs Iterable object containing attributes to be set. See {@link core.treeModel.Node#getAttributes}.
 	 */
 	setAttributesTo( attrs ) {
 		this._attrs = utils.toMap( attrs );
@@ -152,6 +159,7 @@ export default class Element extends Node {
 	/**
 	 * Removes an attribute with given key from the element.
 	 *
+	 * @method core.treeModel.Element#removeAttribute
 	 * @param {String} key Key of attribute to remove.
 	 * @returns {Boolean} `true` if the attribute was set on the element, `false` otherwise.
 	 */
@@ -161,6 +169,8 @@ export default class Element extends Node {
 
 	/**
 	 * Removes all attributes from the element.
+	 *
+	 * @method core.treeModel.Element#clearAttributes
 	 */
 	clearAttributes() {
 		this._attrs.clear();

+ 45 - 39
packages/ckeditor5-engine/src/treemodel/liveposition.js

@@ -10,29 +10,23 @@ import Range from './range.js';
 import EmitterMixin from '../emittermixin.js';
 import utils from '../utils.js';
 
-/**
- * Enum representing how position is "sticking" with their neighbour nodes.
- * Possible values: `'STICKS_TO_NEXT'`, `'STICKS_TO_PREVIOUS'`.
- * @typedef {String} treeModel.PositionStickiness
- */
-
 /**
  * LivePosition is a position in the Tree Model that updates itself as the tree changes. It may be used as a bookmark.
  * **Note:** Be very careful when dealing with LivePosition. Each LivePosition instance bind events that might
- * have to be unbound. Use {@link #detach} whenever you don't need LivePosition anymore.
+ * have to be unbound. Use {@link core.treeModel.LivePosition#detach} whenever you don't need LivePosition anymore.
  *
- * @class treeModel.LivePosition
+ * @memberOf core.treeModel
+ * @extends core.treeModel.Position
  */
-
 export default class LivePosition extends Position {
 	/**
 	 * Creates a live position.
 	 *
-	 * @see {@link treeModel.Position}
-	 * @param root
-	 * @param path
-	 * @param {treeModel.PositionStickiness} [stickiness] Defaults to `'STICKS_TO_NEXT'`. See {@link #stickiness}.
-	 * @constructor
+	 * @see @link core.treeModel.Position
+	 * @param {core.treeModel.RootElement} root
+	 * @param {Array.<Number>} path
+	 * @param {core.treeModel.PositionStickiness} [stickiness] Defaults to `'STICKS_TO_NEXT'`. See
+	 *  {@link core.treeModel.LivePosition#stickiness}.
 	 */
 	constructor( root, path, stickiness ) {
 		super( root, path );
@@ -46,15 +40,15 @@ export default class LivePosition extends Position {
 		 * Examples:
 		 * Insert:
 		 * Position is at | and we insert at the same position, marked as ^:
-		 * | sticks to previous node: `<p>f|^oo</p>` => `<p>f|baroo</p>`
-		 * | sticks to next node: `<p>f^|oo</p>` => `<p>fbar|oo</p>`
+		 * - | sticks to previous node: `<p>f|^oo</p>` => `<p>f|baroo</p>`
+		 * - | sticks to next node: `<p>f^|oo</p>` => `<p>fbar|oo</p>`
 		 *
 		 * Move:
 		 * Position is at | and range [ ] is moved to position ^:
-		 * | sticks to previous node: `<p>f|[oo]</p><p>b^ar</p>` => `<p>f|</p><p>booar</p>`
-		 * | sticks to next node: `<p>f|[oo]</p><p>b^ar</p>` => `<p>f</p><p>b|ooar</p>`
+		 * - | sticks to previous node: `<p>f|[oo]</p><p>b^ar</p>` => `<p>f|</p><p>booar</p>`
+		 * - | sticks to next node: `<p>f|[oo]</p><p>b^ar</p>` => `<p>f</p><p>b|ooar</p>`
 		 *
-		 * @type {treeModel.PositionStickiness}
+		 * @member {treeModel.PositionStickiness} core.treeModel.LivePosition#stickiness
 		 */
 		this.stickiness = stickiness || 'STICKS_TO_NEXT';
 
@@ -65,6 +59,8 @@ export default class LivePosition extends Position {
 	 * Unbinds all events previously bound by LivePosition. Use it whenever you don't need LivePosition instance
 	 * anymore (i.e. when leaving scope in which it was declared or before re-assigning variable that was
 	 * referring to it).
+	 *
+	 * @method core.treeModel.LivePosition#detach
 	 */
 	detach() {
 		this.stopListening();
@@ -72,43 +68,44 @@ export default class LivePosition extends Position {
 
 	/**
 	 * @static
-	 * @method createAfter
-	 * @see {@link treeModel.Position#createAfter}
-	 * @param {treeModel.Node} node
-	 * @returns {treeModel.LivePosition}
+	 * @method core.treeModel.LivePosition.createAfter
+	 * @see {@link core.treeModel.Position#createAfter}
+	 * @param {core.treeModel.Node} node
+	 * @returns {core.treeModel.LivePosition}
 	 */
 
 	/**
 	 * @static
-	 * @method createBefore
-	 * @see {@link treeModel.Position#createBefore}
-	 * @param {treeModel.Node} node
-	 * @returns {treeModel.LivePosition}
+	 * @method core.treeModel.LivePosition.createBefore
+	 * @see {@link core.treeModel.Position#createBefore}
+	 * @param {core.treeModel.Node} node
+	 * @returns {core.treeModel.LivePosition}
 	 */
 
 	/**
 	 * @static
-	 * @method createFromParentAndOffset
-	 * @see {@link treeModel.Position#createFromParentAndOffset}
-	 * @param {treeModel.Element} parent
+	 * @method core.treeModel.LivePosition.createFromParentAndOffset
+	 * @see {@link core.treeModel.Position#createFromParentAndOffset}
+	 * @param {core.treeModel.Element} parent
 	 * @param {Number} offset
-	 * @returns {treeModel.LivePosition}
+	 * @returns {core.treeModel.LivePosition}
 	 */
 
 	/**
 	 * @static
-	 * @method createFromPosition
-	 * @see {@link treeModel.Position#createFromPosition}
-	 * @param {treeModel.Position} position
-	 * @returns {treeModel.LivePosition}
+	 * @method core.treeModel.LivePosition.createFromPosition
+	 * @see {@link core.treeModel.Position#createFromPosition}
+	 * @param {core.treeModel.Position} position
+	 * @returns {core.treeModel.LivePosition}
 	 */
 }
 
 /**
- * Binds this LivePosition to the {@link treeModel.Document} that owns this position {@link treeModel.RootElement root}.
+ * Binds this LivePosition to the {@link core.treeModel.Document} that owns this position {@link core.treeModel.RootElement root}.
  *
+ * @ignore
  * @private
- * @method bindWithDocument
+ * @method core.treeModel.LivePosition.bindWithDocument
  */
 function bindWithDocument() {
 	/*jshint validthis: true */
@@ -126,11 +123,12 @@ function bindWithDocument() {
 /**
  * Updates this position accordingly to the updates applied to the Tree Model. Bases on change events.
  *
+ * @ignore
  * @private
  * @method transform
  * @param {String} type Type of changes applied to the Tree Model.
- * @param {treeModel.Range} range Range containing the result of applied change.
- * @param {treeModel.Position} [position] Additional position parameter provided by some change events.
+ * @param {core.treeModel.Range} range Range containing the result of applied change.
+ * @param {core.treeModel.Position} [position] Additional position parameter provided by some change events.
  */
 function transform( type, range, position ) {
 	/*jshint validthis: true */
@@ -168,3 +166,11 @@ function transform( type, range, position ) {
 }
 
 utils.mix( LivePosition, EmitterMixin );
+
+/**
+ * Enum representing how position is "sticking" with their neighbour nodes.
+ * Possible values: `'STICKS_TO_NEXT'`, `'STICKS_TO_PREVIOUS'`.
+ *
+ * @typedef {String} core.treeModel.PositionStickiness
+ */
+

+ 28 - 27
packages/ckeditor5-engine/src/treemodel/liverange.js

@@ -12,18 +12,17 @@ import utils from '../utils.js';
 
 /**
  * LiveRange is a Range in the Tree Model that updates itself as the tree changes. It may be used as a bookmark.
- * **Note:** Constructor creates it's own {@link treeModel.LivePosition} instances basing on passed values.
+ * **Note:** Constructor creates it's own {@link core.treeModel.LivePosition} instances basing on passed values.
  * **Note:** Be very careful when dealing with LiveRange. Each LiveRange instance bind events that might
- * have to be unbound. Use {@link #detach} whenever you don't need LiveRange anymore.
+ * have to be unbound. Use {@link core.treeModel.LiveRange#detach detach} whenever you don't need LiveRange anymore.
  *
- * @class treeModel.LiveRange
+ * @memberOf core.treeModel
  */
 export default class LiveRange extends Range {
 	/**
 	 * Creates a live range.
 	 *
-	 * @see {treeModel.Range}
-	 * @constructor
+	 * @see core.treeModel.Range
 	 */
 	constructor( start, end ) {
 		super( start, end );
@@ -46,47 +45,48 @@ export default class LiveRange extends Range {
 	}
 
 	/**
-	 * @see {@link treeModel.Range#createFromElement}
+	 * @see {@link core.treeModel.Range#createFromElement}
 	 * @static
-	 * @method createFromElement
-	 * @param {treeModel.Element} element
-	 * @returns {treeModel.LiveRange}
+	 * @method core.treeModel.LiveRange.createFromElement
+	 * @param {core.treeModel.Element} element
+	 * @returns {core.treeModel.LiveRange}
 	 */
 
 	/**
-	 * @see {@link treeModel.Range#createFromPositionAndShift}
+	 * @see {@link core.treeModel.Range#createFromPositionAndShift}
 	 * @static
-	 * @method createFromPositionAndShift
-	 * @param {treeModel.Position} position
+	 * @method core.treeModel.LiveRange.createFromPositionAndShift
+	 * @param {core.treeModel.Position} position
 	 * @param {Number} shift
-	 * @returns {treeModel.LiveRange}
+	 * @returns {core.treeModel.LiveRange}
 	 */
 
 	/**
-	 * @see {@link treeModel.Range#createFromParentsAndOffsets}
+	 * @see {@link core.treeModel.Range#createFromParentsAndOffsets}
 	 * @static
-	 * @method createFromParentsAndOffsets
-	 * @param {treeModel.Element} startElement
+	 * @method core.treeModel.LiveRange.createFromParentsAndOffsets
+	 * @param {core.treeModel.Element} startElement
 	 * @param {Number} startOffset
-	 * @param {treeModel.Element} endElement
+	 * @param {core.treeModel.Element} endElement
 	 * @param {Number} endOffset
-	 * @returns {treeModel.LiveRange}
+	 * @returns {core.treeModel.LiveRange}
 	 */
 
 	/**
-	 * @see {@link treeModel.Range#createFromRange}
+	 * @see {@link core.treeModel.Range#createFromRange}
 	 * @static
-	 * @method createFromRange
-	 * @param {treeModel.Range} range
-	 * @returns {treeModel.LiveRange}
+	 * @method core.treeModel.LiveRange.createFromRange
+	 * @param {core.treeModel.Range} range
+	 * @returns {core.treeModel.LiveRange}
 	 */
 }
 
 /**
- * Binds this LiveRange to the {@link treeModel.Document} that owns this range.
+ * Binds this LiveRange to the {@link core.treeModel.Document} that owns this range.
  *
+ * @ignore
  * @private
- * @method bindWithDocument
+ * @method core.treeModel.LiveRange#bindWithDocument
  */
 function bindWithDocument() {
 	/*jshint validthis: true */
@@ -102,15 +102,16 @@ function bindWithDocument() {
 }
 
 /**
- * LiveRange boundaries are instances of {@link treeModel.LivePosition}, so it is updated thanks to them. This method
+ * LiveRange boundaries are instances of {@link core.treeModel.LivePosition}, so it is updated thanks to them. This method
  * additionally fixes the results of updating live positions taking into account that those live positions
  * are boundaries of a range. An example case for fixing live positions is end boundary is moved before start boundary.
  *
+ * @ignore
  * @private
  * @method fixBoundaries
  * @param {String} type Type of changes applied to the Tree Model.
- * @param {treeModel.Range} range Range containing the result of applied change.
- * @param {treeModel.Position} [position] Additional position parameter provided by some change events.
+ * @param {core.treeModel.Range} range Range containing the result of applied change.
+ * @param {core.treeModel.Position} [position] Additional position parameter provided by some change events.
  */
 function fixBoundaries( type, range, position ) {
 	/* jshint validthis: true */

+ 25 - 20
packages/ckeditor5-engine/src/treemodel/node.js

@@ -10,37 +10,36 @@ import utils from '../utils.js';
 import CKEditorError from '../ckeditorerror.js';
 
 /**
- * Abstract document tree node class.
+ * Creates a tree node.
+ *
+ * This is an abstract class, so this constructor should not be used directly.
+ *
+ * @param {Iterable|Object} attrs Iterable collection of attributes.
  *
  * @abstract
- * @class treeModel.Node
+ * @class core.treeModel.Node
+ * @classdesc Abstract document tree node class.
  */
 export default class Node {
-	/**
-	 * Creates a tree node.
-	 *
-	 * This is an abstract class, so this constructor should not be used directly.
-	 *
-	 * @param {Iterable|Object} attrs Iterable collection of attributes.
-	 * @constructor
-	 */
 	constructor( attrs ) {
 		/**
-		 * Parent element. Null by default. Set by {@link treeModel.Element#insertChildren}.
+		 * Parent element. Null by default. Set by {@link core.treeModel.Element#insertChildren}.
 		 *
+		 * @member core.treeModel.Node#parent
 		 * @readonly
-		 * @type {treeModel.Element|null}
+		 * @member {core.treeModel.Element|null} core.treeModel.Node#parent
 		 */
 		this.parent = null;
 
 		/**
 		 * List of attributes set on this node.
+		 *
 		 * **Note:** It is **important** that attributes of nodes already attached to the document must be changed
-		 * only by an {@link treeModel.operation.AttributeOperation}. Do not set attributes of such nodes
-		 * using {@link treeModel.Node} methods.
+		 * only by an {@link core.treeModel.operation.AttributeOperation}. Do not set attributes of such nodes
+		 * using {@link core.treeModel.Node} methods.
 		 *
 		 * @protected
-		 * @type {Map}
+		 * @member {Map} core.treeModel.Node#_attrs
 		 */
 		this._attrs = utils.toMap( attrs );
 	}
@@ -49,7 +48,7 @@ export default class Node {
 	 * Depth of the node, which equals to total number of its parents.
 	 *
 	 * @readonly
-	 * @type {Number}
+	 * @member {Number} core.treeModel.Node#depth
 	 */
 	get depth() {
 		let depth = 0;
@@ -68,7 +67,7 @@ export default class Node {
 	 * Nodes next sibling or `null` if it is the last child.
 	 *
 	 * @readonly
-	 * @type {treeModel.Node|null}
+	 * @member {core.treeModel.Node|null} core.treeModel.Node#nextSibling
 	 */
 	get nextSibling() {
 		const index = this.getIndex();
@@ -80,7 +79,7 @@ export default class Node {
 	 * Nodes previous sibling or null if it is the last child.
 	 *
 	 * @readonly
-	 * @type {treeModel.Node|null}
+	 * @member {core.treeModel.Node|null} core.treeModel.Node#previousSibling
 	 */
 	get previousSibling() {
 		const index = this.getIndex();
@@ -92,7 +91,7 @@ export default class Node {
 	 * The top parent for the node. If node has no parent it is the root itself.
 	 *
 	 * @readonly
-	 * @type {Number}
+	 * @member {Number} core.treeModel.Node#root
 	 */
 	get root() {
 		let root = this;
@@ -109,6 +108,7 @@ export default class Node {
 	 *
 	 * Throws error if the parent element does not contain this node.
 	 *
+	 * @method core.treeModel.Node#getIndes
 	 * @returns {Number|Null} Index of the node in the parent element or null if the node has not parent.
 	 */
 	getIndex() {
@@ -132,8 +132,9 @@ export default class Node {
 
 	/**
 	 * 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 treeModel.Position}.
+	 * will be `[ 1, 2 ]`. This path can be used as a parameter of {@link core.treeModel.Position}.
 	 *
+	 * @method core.treeModel.Node#getPath
 	 * @returns {Number[]} The path.
 	 */
 	getPath() {
@@ -151,6 +152,7 @@ export default class Node {
 	/**
 	 * Custom toJSON method to solve child-parent circular dependencies.
 	 *
+	 * @method core.treeModel.Node#toJSON
 	 * @returns {Object} Clone of this object with the parent property replaced with its name.
 	 */
 	toJSON() {
@@ -165,6 +167,7 @@ export default class Node {
 	/**
 	 * Checks if the node has an attribute for given key.
 	 *
+	 * @method core.treeModel.Node#hasAttribute
 	 * @param {String} key Key of attribute to check.
 	 * @returns {Boolean} `true` if attribute with given key is set on node, `false` otherwise.
 	 */
@@ -175,6 +178,7 @@ export default class Node {
 	/**
 	 * Gets an attribute value for given key or undefined if that attribute is not set on node.
 	 *
+	 * @method core.treeModel.Node#getAttribute
 	 * @param {String} key Key of attribute to look for.
 	 * @returns {*} Attribute value or null.
 	 */
@@ -185,6 +189,7 @@ export default class Node {
 	/**
 	 * Returns iterator that iterates over this node attributes.
 	 *
+	 * @method core.treeModel.Node#getAttributes
 	 * @returns {Iterable.<*>}
 	 */
 	getAttributes() {

+ 28 - 28
packages/ckeditor5-engine/src/treemodel/nodelist.js

@@ -12,27 +12,14 @@ import clone from '../lib/lodash/clone.js';
 import CKEditorError from '../ckeditorerror.js';
 
 /**
- * Value that is convertible to an item kept in {@link treeModel.NodeList} or an iterable collection of such items.
- * In other words, this is anything that {@link treeModel.NodeList#constructor} is able to take and convert to node:
- * * {@link treeModel.Element} will be left as is
- * * {@link treeModel.CharacterProxy} will be left as is
- * * {@link treeModel.Text} and {String} will be converted to a set of {@link treeModel.CharacterProxy}
- * * {@link treeModel.NodeList} will clone a node list (but not the nodes inside, so the new and passed list will
- * point to the same nodes.
- * * Iterable collection of above items will be iterated over and all items will be added to the node list.
- *
- * @typedef {treeModel.Element|treeModel.CharacterProxy|treeModel.Text|String|treeModel.NodeList|Iterable} treeModel.NodeSet
- */
-
-/**
- * This is a private helper-class for {@link treeModel.NodeList} text compression utility.
+ * This is a private helper-class for {@link core.treeModel.NodeList} text compression utility.
  *
  * @protected
- * @class treeModel.NodeListText
+ * @memberOf core.treeModel
  */
 class NodeListText extends Text {
 	/**
-	 * @see {@link treeModel.Text#constructor}
+	 * @see {@link core.treeModel.Text#constructor}
 	 * @protected
 	 * @constructor
 	 */
@@ -43,10 +30,10 @@ class NodeListText extends Text {
 	}
 
 	/**
-	 * Gets a character at given index and creates a {@link treeModel.CharacterProxy} out of it.
+	 * Gets a character at given index and creates a {@link core.treeModel.CharacterProxy} out of it.
 	 *
 	 * @param {Number} index Character index.
-	 * @returns {treeModel.CharacterProxy}
+	 * @returns {core.treeModel.CharacterProxy}
 	 */
 	getCharAt( index ) {
 		index = index && index >= 0 ? index : 0;
@@ -70,14 +57,14 @@ class NodeListText extends Text {
 
 /**
  * List of nodes. It is used to represent multiple nodes with a given order, for example children of
- * {@link treeModel.Element} object or nodes inserted using {@link treeModel.operation.InsertOperation}.
+ * {@link core.treeModel.Element} object or nodes inserted using {@link core.treeModel.operation.InsertOperation}.
  *
  * Thanks to the constructor, which accepts various arguments, this class lets you easily create desired list of nodes.
  *
- * Parameters passed to constructor are converted and internally kept as an array of {@link treeModel.Node}
- * and {@link treeModel.Text} instances.
+ * Parameters passed to constructor are converted and internally kept as an array of {@link core.treeModel.Node}
+ * and {@link core.treeModel.Text} instances.
  *
- * @class treeModel.NodeList
+ * @memberOf core.treeModel
  */
 export default class NodeList {
 	/**
@@ -106,9 +93,9 @@ export default class NodeList {
 	 *		nodeListA === nodeListB // true
 	 *		nodeListB.length // 3
 	 *
-	 * @see {@link treeModel.NodeSet} for more explanation.
+	 * @see {@link core.treeModel.NodeSet} for more explanation.
 	 *
-	 * @param {treeModel.NodeSet} nodes List of nodes.
+	 * @param {core.treeModel.NodeSet} nodes List of nodes.
 	 * @constructor
 	 */
 	constructor( nodes ) {
@@ -208,7 +195,7 @@ export default class NodeList {
 	 * Returns node at the given index.
 	 *
 	 * @param {Number} index Node index.
-	 * @returns {treeModel.Node} Node at given index.
+	 * @returns {core.treeModel.Node} Node at given index.
 	 */
 	get( index ) {
 		let realIndex = this._indexMap[ index ];
@@ -224,7 +211,7 @@ export default class NodeList {
 	/**
 	 * Search for the element in the node list.
 	 *
-	 * @param {treeModel.Node} node Node to find.
+	 * @param {core.treeModel.Node} node Node to find.
 	 * @returns {Number} Position of the element in the list or -1 if not found.
 	 */
 	indexOf( node ) {
@@ -243,7 +230,7 @@ export default class NodeList {
 	 * 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 {treeModel.NodeList} nodeList List of nodes to insert.
+	 * @param {core.treeModel.NodeList} nodeList List of nodes to insert.
 	 */
 	insert( index, nodeList ) {
 		if ( this._nodes.length === 0 ) {
@@ -283,7 +270,7 @@ export default class NodeList {
 	 *
 	 * @param {Number} index Position of the first node to remove.
 	 * @param {Number} number Number of nodes to remove.
-	 * @returns {treeModel.NodeList} List of removed nodes.
+	 * @returns {core.treeModel.NodeList} List of removed nodes.
 	 */
 	remove( index, number ) {
 		if ( this._nodes.length === 0 ) {
@@ -451,3 +438,16 @@ export default class NodeList {
 		return index - this._indexMap.indexOf( this._indexMap[ index ] );
 	}
 }
+
+/**
+ * Value that is convertible to an item kept in {@link core.treeModel.NodeList} or an iterable collection of such items.
+ * In other words, this is anything that {@link core.treeModel.NodeList#constructor} is able to take and convert to node:
+ * * {@link core.treeModel.Element} will be left as is
+ * * {@link core.treeModel.CharacterProxy} will be left as is
+ * * {@link core.treeModel.Text} and {String} will be converted to a set of {@link core.treeModel.CharacterProxy}
+ * * {@link core.treeModel.NodeList} will clone a node list (but not the nodes inside, so the new and passed list will
+ * point to the same nodes.
+ * * Iterable collection of above items will be iterated over and all items will be added to the node list.
+ *
+ * @typedef {treeModel.Element|treeModel.CharacterProxy|treeModel.Text|String|treeModel.NodeList|Iterable} core.treeModel.NodeSet
+ */

+ 1 - 1
packages/ckeditor5-engine/src/treemodel/operation/nooperation.js

@@ -15,7 +15,7 @@ import Operation from './operation.js';
  * It still has some parameters defined for transformation purposes.
  *
  * In most cases this operation is a result of transforming operations. When transformation returns
- * {@link treeModel.operation.NoOperation} it means that changes done by the transformed operation
+ * {@link core.treeModel.operation.NoOperation} it means that changes done by the transformed operation
  * have already been applied.
  * @extends core.treeModel.operation.Operation
  */

+ 2 - 2
packages/ckeditor5-engine/src/treemodel/operation/reinsertoperation.js

@@ -12,8 +12,8 @@ import RemoveOperation from './removeoperation.js';
  * @class core.treeModel.operation.ReinsertOperation
  * @classdesc
  * Operation to reinsert previously removed nodes back to the non-graveyard root.
- * This is basically {@link treeModel.operation.MoveOperation} but it returns
- * {@link treeModel.operation.RemoveOperation} when reversed.
+ * This is basically {@link core.treeModel.operation.MoveOperation} but it returns
+ * {@link core.treeModel.operation.RemoveOperation} when reversed.
  *
  * With this class, we achieve two goals: by having separate classes it's easier to distinguish whether move
  * operation is actually a remove/reinsert operation and fire proper events. Also it

+ 41 - 42
packages/ckeditor5-engine/src/treemodel/position.js

@@ -10,26 +10,18 @@ import CKEditorError from '../ckeditorerror.js';
 import last from '../lib/lodash/last.js';
 import utils from '../utils.js';
 
-/**
- * A flag indicating whether this position is `'BEFORE'` or `'AFTER'` or `'SAME'` as given position.
- * If positions are in different roots `'DIFFERENT'` flag is returned.
- *
- * @typedef {String} treeModel.PositionRelation
- */
-
 /**
  * Position in the tree. Position is always located before or after a node.
  * See {@link #path} property for more information.
  *
- * @class treeModel.Position
+ * @memberOf core.treeModel
  */
 export default class Position {
 	/**
 	 * Creates a position.
 	 *
-	 * @param {treeModel.RootElement} root Root element for the path. Note that this element can not have a parent.
+	 * @param {core.treeModel.RootElement} root Root element for the path. Note that this element can not have a parent.
 	 * @param {Array.<Number>} path Position path. Must contain at least one item. See {@link #path} property for more information.
-	 * @constructor
 	 */
 	constructor( root, path ) {
 		if ( !( root instanceof RootElement ) ) {
@@ -45,7 +37,7 @@ export default class Position {
 		/**
 		 * Root element for the path. Note that this element can not have a parent.
 		 *
-		 * @type {treeModel.RootElement}
+		 * @type {core.treeModel.RootElement}
 		 */
 		this.root = root;
 
@@ -83,7 +75,7 @@ export default class Position {
 	 * Node directly after the position.
 	 *
 	 * @readonly
-	 * @type {treeModel.Node}
+	 * @type {core.treeModel.Node}
 	 */
 	get nodeAfter() {
 		return this.parent.getChild( this.offset ) || null;
@@ -93,7 +85,7 @@ export default class Position {
 	 * Node directly before the position.
 	 *
 	 * @readonly
-	 * @type {treeModel.Node}
+	 * @type {Node}
 	 */
 	get nodeBefore() {
 		return this.parent.getChild( this.offset - 1 ) || null;
@@ -120,7 +112,7 @@ export default class Position {
 	 * Parent element of the position. The position is located at {@link #offset} in this element.
 	 *
 	 * @readonly
-	 * @type {treeModel.Element}
+	 * @type {core.treeModel.Element}
 	 */
 	get parent() {
 		let parent = this.root;
@@ -137,8 +129,8 @@ export default class Position {
 	/**
 	 * Checks whether this position is before or after given position.
 	 *
-	 * @param {treeModel.Position} otherPosition Position to compare with.
-	 * @returns {treeModel.PositionRelation}
+	 * @param {core.treeModel.Position} otherPosition Position to compare with.
+	 * @returns {core.treeModel.PositionRelation}
 	 */
 	compareWith( otherPosition ) {
 		if ( this.root != otherPosition.root ) {
@@ -167,7 +159,7 @@ export default class Position {
 	}
 
 	/**
-	 * Returns the path to the parent, which is the {@link treeModel.Position#path} without the last element.
+	 * Returns the path to the parent, which is the {@link core.treeModel.Position#path} without the last element.
 	 *
 	 * This method returns the parent path even if the parent does not exists.
 	 *
@@ -181,7 +173,7 @@ export default class Position {
 	 * Returns a new instance of Position with offset incremented by `shift` value.
 	 *
 	 * @param {Number} shift How position offset should get changed. Accepts negative values.
-	 * @returns {treeModel.Position} Shifted position.
+	 * @returns {core.treeModel.Position} Shifted position.
 	 */
 	getShiftedBy( shift ) {
 		let shifted = Position.createFromPosition( this );
@@ -196,9 +188,9 @@ export default class Position {
 	 * Returns this position after being updated by removing `howMany` nodes starting from `deletePosition`.
 	 * It may happen that this position is in a removed node. If that is the case, `null` is returned instead.
 	 *
-	 * @param {treeModel.Position} deletePosition Position before the first removed node.
+	 * @param {core.treeModel.Position} deletePosition Position before the first removed node.
 	 * @param {Number} howMany How many nodes are removed.
-	 * @returns {treeModel.Position|null} Transformed position or `null`.
+	 * @returns {core.treeModel.Position|null} Transformed position or `null`.
 	 */
 	getTransformedByDeletion( deletePosition, howMany ) {
 		let transformed = Position.createFromPosition( this );
@@ -242,12 +234,12 @@ export default class Position {
 	/**
 	 * Returns this position after being updated by inserting `howMany` nodes at `insertPosition`.
 	 *
-	 * @param {treeModel.Position} insertPosition Position where nodes are inserted.
+	 * @param {core.treeModel.Position} insertPosition Position where nodes are inserted.
 	 * @param {Number} howMany How many nodes are inserted.
 	 * @param {Boolean} insertBefore Flag indicating whether nodes are inserted before or after `insertPosition`.
 	 * This is important only when `insertPosition` and this position are same. If that is the case and the flag is
 	 * set to `true`, this position will get transformed. If the flag is set to `false`, it won't.
-	 * @returns {treeModel.Position} Transformed position.
+	 * @returns {core.treeModel.Position} Transformed position.
 	 */
 	getTransformedByInsertion( insertPosition, howMany, insertBefore ) {
 		let transformed = Position.createFromPosition( this );
@@ -281,13 +273,13 @@ export default class Position {
 	/**
 	 * Returns this position after being updated by moving `howMany` attributes from `sourcePosition` to `targetPosition`.
 	 *
-	 * @param {treeModel.Position} sourcePosition Position before the first element to move.
-	 * @param {treeModel.Position} targetPosition Position where moved elements will be inserted.
+	 * @param {core.treeModel.Position} sourcePosition Position before the first element to move.
+	 * @param {core.treeModel.Position} targetPosition Position where moved elements will be inserted.
 	 * @param {Number} howMany How many consecutive nodes to move, starting from `sourcePosition`.
 	 * @param {Boolean} insertBefore Flag indicating whether moved nodes are pasted before or after `insertPosition`.
 	 * This is important only when `targetPosition` and this position are same. If that is the case and the flag is
 	 * set to `true`, this position will get transformed by range insertion. If the flag is set to `false`, it won't.
-	 * @returns {treeModel.Position} Transformed position.
+	 * @returns {core.treeModel.Position} Transformed position.
 	 */
 	getTransformedByMove( sourcePosition, targetPosition, howMany, insertBefore ) {
 		// Moving a range removes nodes from their original position. We acknowledge this by proper transformation.
@@ -311,7 +303,7 @@ export default class Position {
 	 *
 	 * **Note:** see {treeModel.Position#isBefore}.
 	 *
-	 * @param {treeModel.Position} otherPosition Position to compare with.
+	 * @param {core.treeModel.Position} otherPosition Position to compare with.
 	 * @returns {Boolean} True if this position is after given position.
 	 */
 	isAfter( otherPosition ) {
@@ -346,7 +338,7 @@ export default class Position {
 	 *    // do A.
 	 *  }
 	 *
-	 * @param {treeModel.Position} otherPosition Position to compare with.
+	 * @param {core.treeModel.Position} otherPosition Position to compare with.
 	 * @returns {Boolean} True if this position is before given position.
 	 */
 	isBefore( otherPosition ) {
@@ -356,7 +348,7 @@ export default class Position {
 	/**
 	 * Checks whether this position equals given position.
 	 *
-	 * @param {treeModel.Position} otherPosition Position to compare with.
+	 * @param {core.treeModel.Position} otherPosition Position to compare with.
 	 * @returns {Boolean} True if positions are same.
 	 */
 	isEqual( otherPosition ) {
@@ -368,7 +360,7 @@ export default class Position {
 	 * or empty nodes in a range between them. Technically, those positions are not equal but in many cases
 	 * they are very similar or even indistinguishable when they touch.
 	 *
-	 * @param {treeModel.Position} otherPosition Position to compare with.
+	 * @param {core.treeModel.Position} otherPosition Position to compare with.
 	 * @returns {Boolean} True if positions touch.
 	 */
 	isTouching( otherPosition ) {
@@ -419,8 +411,8 @@ export default class Position {
 	/**
 	 * Creates a new position after given node.
 	 *
-	 * @param {treeModel.Node} node Node the position should be directly after.
-	 * @returns {treeModel.Position}
+	 * @param {core.treeModel.Node} node Node the position should be directly after.
+	 * @returns {core.treeModel.Position}
 	 */
 	static createAfter( node ) {
 		if ( !node.parent ) {
@@ -428,7 +420,7 @@ export default class Position {
 			 * You can not make position after root.
 			 *
 			 * @error position-after-root
-			 * @param {treeModel.Node} root
+			 * @param {core.treeModel.Node} root
 			 */
 			throw new CKEditorError( 'position-after-root: You can not make position after root.', { root: node } );
 		}
@@ -439,8 +431,8 @@ export default class Position {
 	/**
 	 * Creates a new position before the given node.
 	 *
-	 * @param {treeModel.node} node Node the position should be directly before.
-	 * @returns {treeModel.Position}
+	 * @param {core.treeModel.node} node Node the position should be directly before.
+	 * @returns {core.treeModel.Position}
 	 */
 	static createBefore( node ) {
 		if ( !node.parent ) {
@@ -448,7 +440,7 @@ export default class Position {
 			 * You can not make position before root.
 			 *
 			 * @error position-before-root
-			 * @param {treeModel.Node} root
+			 * @param {core.treeModel.Node} root
 			 */
 			throw new CKEditorError( 'position-before-root: You can not make position before root.', { root: node } );
 		}
@@ -459,9 +451,9 @@ export default class Position {
 	/**
 	 * Creates a new position from the parent element and the offset in that element.
 	 *
-	 * @param {treeModel.Element} parent Position parent element.
+	 * @param {core.treeModel.Element} parent Position parent element.
 	 * @param {Number} offset Position offset.
-	 * @returns {treeModel.Position}
+	 * @returns {core.treeModel.Position}
 	 */
 	static createFromParentAndOffset( parent, offset ) {
 		const path = parent.getPath();
@@ -474,8 +466,8 @@ export default class Position {
 	/**
 	 * Creates and returns a new instance of Position, which is equal to passed position.
 	 *
-	 * @param {treeModel.Position} position Position to be cloned.
-	 * @returns {treeModel.Position}
+	 * @param {core.treeModel.Position} position Position to be cloned.
+	 * @returns {core.treeModel.Position}
 	 */
 	static createFromPosition( position ) {
 		return new this( position.root, position.path.slice() );
@@ -507,9 +499,9 @@ export default class Position {
 	 * Finally, the transformed position will point to `[ 1, 1, 4, 1 ]`.
 	 *
 	 * @protected
-	 * @param {treeModel.Position} source Beginning of the moved range.
-	 * @param {treeModel.Position} target Position where the range is moved.
-	 * @returns {treeModel.Position} Combined position.
+	 * @param {core.treeModel.Position} source Beginning of the moved range.
+	 * @param {core.treeModel.Position} target Position where the range is moved.
+	 * @returns {core.treeModel.Position} Combined position.
 	 */
 	_getCombined( source, target ) {
 		const i = source.path.length - 1;
@@ -529,3 +521,10 @@ export default class Position {
 		return combined;
 	}
 }
+
+/**
+ * A flag indicating whether this position is `'BEFORE'` or `'AFTER'` or `'SAME'` as given position.
+ * If positions are in different roots `'DIFFERENT'` flag is returned.
+ *
+ * @typedef {String} core.treeModel.PositionRelation
+ */

+ 53 - 52
packages/ckeditor5-engine/src/treemodel/range.js

@@ -12,29 +12,30 @@ import utils from '../utils.js';
 /**
  * Range class. Range is iterable.
  *
- * @class treeModel.Range
+ * @memberOf core.treeModel
  */
 export default class Range {
 	/**
 	 * Creates a range spanning from `start` position to `end` position.
-	 * **Note:** Constructor creates it's own {@link treeModel.Position} instances basing on passed values.
+	 * **Note:** Constructor creates it's own {@link core.treeModel.Position} instances basing on passed values.
 	 *
-	 * @param {treeModel.Position} start Start position.
-	 * @param {treeModel.Position} end End position.
-	 * @constructor
+	 * @param {core.treeModel.Position} start Start position.
+	 * @param {core.treeModel.Position} end End position.
 	 */
 	constructor( start, end ) {
 		/**
 		 * Start position.
 		 *
-		 * @type {treeModel.Position}
+		 * @private
+		 * @member {core.treeModel.Position}  core.treeModel.Range#start
 		 */
 		this.start = Position.createFromPosition( start );
 
 		/**
 		 * End position.
 		 *
-		 * @type {treeModel.Position}
+		 * @private
+		 * @member {core.treeModel.Position} core.treeModel.Range#end
 		 */
 		this.end = Position.createFromPosition( end );
 	}
@@ -60,7 +61,7 @@ export default class Range {
 	/**
 	 * Range root element. Equals to the root of start position (which should be same as root of end position).
 	 *
-	 * @type {treeModel.RootElement}
+	 * @type {core.treeModel.RootElement}
 	 */
 	get root() {
 		return this.start.root;
@@ -69,35 +70,35 @@ export default class Range {
 	/**
 	 * Range iterator.
 	 *
-	 * @see treeModel.TreeWalker
+	 * @see core.treeModel.TreeWalker
 	 */
 	[ Symbol.iterator ]() {
 		return new TreeWalker( { boundaries: this } );
 	}
 
 	/**
-	 * Checks whether this contains given {@link treeModel.Position position}.
+	 * Checks whether this contains given {@link core.treeModel.Position position}.
 	 *
-	 * @param {treeModel.Position} position Position to check.
-	 * @returns {Boolean} True if given {@link treeModel.Position position} is contained.
+	 * @param {core.treeModel.Position} position Position to check.
+	 * @returns {Boolean} True if given {@link core.treeModel.Position position} is contained.
 	 */
 	containsPosition( position ) {
 		return position.isAfter( this.start ) && position.isBefore( this.end );
 	}
 
 	/**
-	 * Checks whether this range contains given {@link treeModel.Range range}.
+	 * Checks whether this range contains given {@link core.treeModel.Range range}.
 	 *
-	 * @param {treeModel.Range} otherRange Range to check.
-	 * @returns {Boolean} True if given {@link treeModel.Range range} boundaries are contained by this range.
+	 * @param {core.treeModel.Range} otherRange Range to check.
+	 * @returns {Boolean} True if given {@link core.treeModel.Range range} boundaries are contained by this range.
 	 */
 	containsRange( otherRange ) {
 		return this.containsPosition( otherRange.start ) && this.containsPosition( otherRange.end );
 	}
 
 	/**
-	 * Gets a part of this {@link treeModel.Range range} which is not a part of given {@link treeModel.Range range}. Returned
-	 * array contains zero, one or two {@link treeModel.Range ranges}.
+	 * Gets a part of this {@link core.treeModel.Range range} which is not a part of given {@link core.treeModel.Range range}. Returned
+	 * array contains zero, one or two {@link core.treeModel.Range ranges}.
 	 *
 	 * Examples:
 	 *
@@ -114,8 +115,8 @@ export default class Range {
 	 *		transformed = range.getDifference( otherRange );
 	 *		// transformed array has two ranges: from [ 2, 7 ] to [ 3 ] and from [ 4 ] to [ 4, 0, 1 ]
 	 *
-	 * @param {treeModel.Range} otherRange Range to differentiate against.
-	 * @returns {Array.<treeModel.Range>} The difference between ranges.
+	 * @param {core.treeModel.Range} otherRange Range to differentiate against.
+	 * @returns {Array.<core.treeModel.Range>} The difference between ranges.
 	 */
 	getDifference( otherRange ) {
 		const ranges = [];
@@ -143,7 +144,7 @@ export default class Range {
 	}
 
 	/**
-	 * Returns an intersection of this {@link treeModel.Range range} and given {@link treeModel.Range range}. Intersection
+	 * Returns an intersection of this {@link core.treeModel.Range range} and given {@link core.treeModel.Range range}. Intersection
 	 * is a common part of both of those ranges. If ranges has no common part, returns `null`.
 	 *
 	 * Examples:
@@ -155,8 +156,8 @@ export default class Range {
 	 *		otherRange = new Range( new Position( root, [ 3 ] ), new Position( root, [ 5 ] ) );
 	 *		transformed = range.getIntersection( otherRange ); // range from [ 3 ] to [ 4, 0, 1 ]
 	 *
-	 * @param {treeModel.Range} otherRange Range to check for intersection.
-	 * @returns {treeModel.Range|null} A common part of given ranges or null if ranges have no common part.
+	 * @param {core.treeModel.Range} otherRange Range to check for intersection.
+	 * @returns {core.treeModel.Range|null} A common part of given ranges or null if ranges have no common part.
 	 */
 	getIntersection( otherRange ) {
 		if ( this.isIntersecting( otherRange ) ) {
@@ -217,7 +218,7 @@ export default class Range {
 	 * **Note:** this method is not returning flat ranges that contain no nodes. It may also happen that not-collapsed
 	 * range will return an empty array of flat ranges.
 	 *
-	 * @returns {Array.<treeModel.Range>} Array of flat ranges.
+	 * @returns {Array.<core.treeModel.Range>} Array of flat ranges.
 	 */
 	getMinimalFlatRanges() {
 		let ranges = [];
@@ -260,20 +261,20 @@ export default class Range {
 	}
 
 	/**
-	 * Returns an iterator that iterates over all {@link treeModel.Node nodes} that are in this range and returns them.
-	 * A node is in the range when it is after a {@link treeModel.Position position} contained in this range.
-	 * In other words, this iterates over all text characters that are inside the range and all the {@link treeModel.Element}s
+	 * Returns an iterator that iterates over all {@link core.treeModel.Node nodes} that are in this range and returns them.
+	 * A node is in the range when it is after a {@link core.treeModel.Position position} contained in this range.
+	 * In other words, this iterates over all text characters that are inside the range and all the {@link core.treeModel.Element}s
 	 * we enter into when iterating over this range.
 	 *
-	 * **Note:** this method will not return a parent node of start position. This is in contrary to {@link treeModel.TreeWalker}
-	 * which will return that node with `'ELEMENT_END'` type. This method also returns each {@link treeModel.Element} once,
-	 * while simply used {@link treeModel.TreeWalker} might return it twice: for `'ELEMENT_START'` and `'ELEMENT_END'`.
+	 * **Note:** this method will not return a parent node of start position. This is in contrary to {@link core.treeModel.TreeWalker}
+	 * which will return that node with `'ELEMENT_END'` type. This method also returns each {@link core.treeModel.Element} once,
+	 * while simply used {@link core.treeModel.TreeWalker} might return it twice: for `'ELEMENT_START'` and `'ELEMENT_END'`.
 	 *
 	 * @see {treeModel.TreeWalker}
 	 * @param {Boolean} [mergeCharacters] Flag indicating whether all consecutive characters with the same attributes
-	 * should be returned as one {@link treeModel.TextFragment} (`true`) or one by one as multiple {@link treeModel.CharacterProxy}
+	 * should be returned as one {@link core.treeModel.TextFragment} (`true`) or one by one as multiple {@link core.treeModel.CharacterProxy}
 	 * (`false`) objects. Defaults to `false`.
-	 * @returns {Iterable.<treeModel.Node|treeModel.TextFragment>}
+	 * @returns {Iterable.<core.treeModel.Node|treeModel.TextFragment>}
 	 */
 	*getAllNodes( mergeCharacters ) {
 		let it = new TreeWalker( { boundaries: this, mergeCharacters: mergeCharacters } );
@@ -289,13 +290,13 @@ export default class Range {
 	}
 
 	/**
-	 * Returns an iterator that iterates over all {@link treeModel.Position positions} that are boundaries or
+	 * Returns an iterator that iterates over all {@link core.treeModel.Position positions} that are boundaries or
 	 * contained in this range.
 	 *
 	 * @param {Boolean} [mergeCharacters] Flag indicating whether all consecutive characters with the same attributes
-	 * should be returned as one {@link treeModel.TextFragment} (`true`) or one by one as multiple {@link treeModel.CharacterProxy}
+	 * should be returned as one {@link core.treeModel.TextFragment} (`true`) or one by one as multiple {@link core.treeModel.CharacterProxy}
 	 * (`false`) objects. Defaults to `false`.
-	 * @returns {Iterable.<treeModel.Position>}
+	 * @returns {Iterable.<core.treeModel.Position>}
 	 */
 	*getPositions( mergeCharacters ) {
 		let it = new TreeWalker( { boundaries: this, mergeCharacters: mergeCharacters } );
@@ -306,14 +307,14 @@ export default class Range {
 	}
 
 	/**
-	 * Returns an iterator that iterates over all {@link treeModel.Node nodes} that are top-level nodes in this range
+	 * Returns an iterator that iterates over all {@link core.treeModel.Node nodes} that are top-level nodes in this range
 	 * and returns them. A node is a top-level node when it is in the range but it's parent is not. In other words,
 	 * this function splits the range into separate sub-trees and iterates over their roots.
 	 *
 	 * @param {Boolean} [mergeCharacters] Flag indicating whether all consecutive characters with the same attributes
-	 * should be returned as one {@link treeModel.TextFragment} (`true`) or one by one as multiple {@link treeModel.CharacterProxy}
+	 * should be returned as one {@link core.treeModel.TextFragment} (`true`) or one by one as multiple {@link core.treeModel.CharacterProxy}
 	 * (`false`) objects. Defaults to `false`.
-	 * @returns {Iterable.<treeModel.Node|treeModel.TextFragment>}
+	 * @returns {Iterable.<core.treeModel.Node|treeModel.TextFragment>}
 	 */
 	*getTopLevelNodes( mergeCharacters ) {
 		let flatRanges = this.getMinimalFlatRanges();
@@ -348,8 +349,8 @@ export default class Range {
 
 	/**
 	 * Returns an array containing one or two {treeModel.Range ranges} that are a result of transforming this
-	 * {@link treeModel.Range range} by inserting `howMany` nodes at `insertPosition`. Two {@link treeModel.Range ranges} are
-	 * returned if the insertion was inside this {@link treeModel.Range range}.
+	 * {@link core.treeModel.Range range} by inserting `howMany` nodes at `insertPosition`. Two {@link core.treeModel.Range ranges} are
+	 * returned if the insertion was inside this {@link core.treeModel.Range range}.
 	 *
 	 * Examples:
 	 *
@@ -363,11 +364,11 @@ export default class Range {
 	 *		transformed = range.getTransformedByInsertion( new Position( root, [ 3, 2 ] ), 4, true );
 	 *		// transformed array has one range which is equal to `range`. This is because of spreadOnlyOnSameLevel flag.
 	 *
-	 * @param {treeModel.Position} insertPosition Position where nodes are inserted.
+	 * @param {core.treeModel.Position} insertPosition Position where nodes are inserted.
 	 * @param {Number} howMany How many nodes are inserted.
 	 * @param {Boolean} spreadOnlyOnSameLevel Flag indicating whether this {treeModel.Range range} should be spread
 	 * if insertion was inside a node from this {treeModel.Range range} but not in the range itself.
-	 * @returns {Array.<treeModel.Range>} Result of the transformation.
+	 * @returns {Array.<core.treeModel.Range>} Result of the transformation.
 	 */
 	getTransformedByInsertion( insertPosition, howMany, spreadOnlyOnSameLevel ) {
 		// Flag indicating whether this whole range and given insertPosition is on the same tree level.
@@ -402,7 +403,7 @@ export default class Range {
 	/**
 	 * Two ranges equal if their start and end positions equal.
 	 *
-	 * @param {treeModel.Range} otherRange Range to compare with.
+	 * @param {core.treeModel.Range} otherRange Range to compare with.
 	 * @returns {Boolean} True if ranges equal.
 	 */
 	isEqual( otherRange ) {
@@ -412,7 +413,7 @@ export default class Range {
 	/**
 	 * Checks and returns whether this range intersects with given range.
 	 *
-	 * @param {treeModel.Range} otherRange Range to compare with.
+	 * @param {core.treeModel.Range} otherRange Range to compare with.
 	 * @returns {Boolean} True if ranges intersect.
 	 */
 	isIntersecting( otherRange ) {
@@ -422,8 +423,8 @@ export default class Range {
 	/**
 	 * Creates a range inside an element which starts before the first child and ends after the last child.
 	 *
-	 * @param {treeModel.Element} element Element which is a parent for the range.
-	 * @returns {treeModel.Range} Created range.
+	 * @param {core.treeModel.Element} element Element which is a parent for the range.
+	 * @returns {core.treeModel.Range} Created range.
 	 */
 	static createFromElement( element ) {
 		return this.createFromParentsAndOffsets( element, 0, element, element.getChildCount() );
@@ -432,9 +433,9 @@ export default class Range {
 	/**
 	 * Creates a new range spreading from specified position to the same position moved by given shift.
 	 *
-	 * @param {treeModel.Position} position Beginning of the range.
+	 * @param {core.treeModel.Position} position Beginning of the range.
 	 * @param {Number} shift How long the range should be.
-	 * @returns {treeModel.Range}
+	 * @returns {core.treeModel.Range}
 	 */
 	static createFromPositionAndShift( position, shift ) {
 		return new this( position, position.getShiftedBy( shift ) );
@@ -443,11 +444,11 @@ export default class Range {
 	/**
 	 * Creates a range from given parents and offsets.
 	 *
-	 * @param {treeModel.Element} startElement Start position parent element.
+	 * @param {core.treeModel.Element} startElement Start position parent element.
 	 * @param {Number} startOffset Start position offset.
-	 * @param {treeModel.Element} endElement End position parent element.
+	 * @param {core.treeModel.Element} endElement End position parent element.
 	 * @param {Number} endOffset End position offset.
-	 * @returns {treeModel.Range} Created range.
+	 * @returns {core.treeModel.Range} Created range.
 	 */
 	static createFromParentsAndOffsets( startElement, startOffset, endElement, endOffset ) {
 		return new this(
@@ -459,8 +460,8 @@ export default class Range {
 	/**
 	 * Creates and returns a new instance of Range which is equal to passed range.
 	 *
-	 * @param {treeModel.Range} range Range to clone.
-	 * @returns {treeModel.Range}
+	 * @param {core.treeModel.Range} range Range to clone.
+	 * @returns {core.treeModel.Range}
 	 */
 	static createFromRange( range ) {
 		return new this( range.start, range.end );

+ 5 - 5
packages/ckeditor5-engine/src/treemodel/rootelement.js

@@ -10,23 +10,23 @@ import Element from './element.js';
 /**
  * Class for nodes that are roots of trees in tree data model.
  *
- * @class treeModel.RootElement
+ * @memberOf core.treeModel
+ * @extends core.treeModel.Element
  */
 export default class RootElement extends Element {
 	/**
 	 * Creates tree root node.
 	 *
-	 * @param {treeModel.Document} doc {@link treeModel.Document} that is an owner of the root.
-	 * @constructor
+	 * @param {Document} doc {@link Document} that is an owner of the root.
 	 */
 	constructor( doc ) {
 		super( 'root' );
 
 		/**
-		 * {@link treeModel.Document} that is an owner of this root.
+		 * {@link core.treeModel.Document} that is an owner of this root.
 		 *
 		 * @readonly
-		 * @type {treeModel.Document}
+		 * @member {core.treeModel.Document} core.treeModel.RootElement#doc
 		 */
 		this.document = doc;
 	}

+ 18 - 20
packages/ckeditor5-engine/src/treemodel/selection.js

@@ -11,23 +11,21 @@ import CKEditorError from '../ckeditorerror.js';
 import utils from '../utils.js';
 
 /**
- * Represents a selection that is made on nodes in {@link treeModel.Document}. Selection instance is
- * created by {@link treeModel.Document}. In most scenarios you should not need to create an instance of Selection.
+ * Represents a selection that is made on nodes in {@link core.treeModel.Document}. Selection instance is
+ * created by {@link core.treeModel.Document}. In most scenarios you should not need to create an instance of Selection.
  *
- * @class treeModel.Selection
+ * @memberOf core.treeModel
  */
 export default class Selection {
 	/**
 	 * Creates an empty selection.
-	 *
-	 * @constructor
 	 */
 	constructor() {
 		/**
 		 * List of attributes set on current selection.
 		 *
 		 * @protected
-		 * @type {Map}
+		 * @member {Map} core.treeModel.Selection#_attrs
 		 */
 		this._attrs = new Map();
 
@@ -35,7 +33,7 @@ export default class Selection {
 		 * Stores all ranges that are selected.
 		 *
 		 * @private
-		 * @type {Array.<LiveRange>}
+		 * @member {Array.<core.treeModel.LiveRange>} core.treeModel.Selection#_ranges
 		 */
 		this._ranges = [];
 
@@ -43,7 +41,7 @@ export default class Selection {
 		 * Specifies whether the last added range was added as a backward or forward range.
 		 *
 		 * @private
-		 * @type {Boolean}
+		 * @member {Boolean} core.treeModel.Selection#_lastRangeBackward
 		 */
 		this._lastRangeBackward = false;
 	}
@@ -55,7 +53,7 @@ export default class Selection {
 	 * Anchor is always a start or end of the most recent added range. It may be a bit unintuitive when
 	 * there are multiple ranges in selection.
 	 *
-	 * @type {treeModel.LivePosition|null}
+	 * @type {core.treeModel.LivePosition|null}
 	 */
 	get anchor() {
 		if ( this._ranges.length > 0 ) {
@@ -72,7 +70,7 @@ export default class Selection {
 	 * focus is null.
 	 *
 	 * @link {#anchor}
-	 * @type {treeModel.LivePosition|null}
+	 * @type {core.treeModel.LivePosition|null}
 	 */
 	get focus() {
 		if ( this._ranges.length > 0 ) {
@@ -100,13 +98,13 @@ export default class Selection {
 	}
 
 	/**
-	 * Adds a range to the selection. Added range is copied and converted to {@link treeModel.LiveRange}. This means
+	 * Adds a range to the selection. Added range is copied and converted to {@link core.treeModel.LiveRange}. This means
 	 * that passed range is not saved in the Selection instance and you can safely operate on it. Accepts a flag
-	 * describing in which way the selection is made - passed range might be selected from {@link treeModel.Range#start}
-	 * to {@link treeModel.Range#end} or from {@link treeModel.Range#start} to {@link treeModel.Range#end}. The flag
+	 * describing in which way the selection is made - passed range might be selected from {@link core.treeModel.Range#start}
+	 * to {@link core.treeModel.Range#end} or from {@link core.treeModel.Range#start} to {@link core.treeModel.Range#end}. The flag
 	 * is used to set {@link #anchor} and {@link #focus} properties.
 	 *
-	 * @param {treeModel.Range} range Range to add.
+	 * @param {core.treeModel.Range} range Range to add.
 	 * @param {Boolean} [isBackward] Flag describing if added range was selected forward - from start to end (`false`)
 	 * or backward - from end to start (`true`). Defaults to `false`.
 	 */
@@ -152,7 +150,7 @@ export default class Selection {
 	 * is treated like the last added range and is used to set {@link #anchor} and {@link #focus}. Accepts a flag
 	 * describing in which way the selection is made (see {@link #addRange}).
 	 *
-	 * @param {Array.<treeModel.Range>} newRanges Array of ranges to set.
+	 * @param {Array.<core.treeModel.Range>} newRanges Array of ranges to set.
 	 * @param {Boolean} [isLastBackward] Flag describing if last added range was selected forward - from start to end (`false`)
 	 * or backward - from end to start (`true`). Defaults to `false`.
 	 */
@@ -235,13 +233,13 @@ export default class Selection {
 }
 
 /**
- * Converts given range to {@link treeModel.LiveRange} and adds it to internal ranges array. Throws an error
+ * Converts given range to {@link core.treeModel.LiveRange} and adds it to internal ranges array. Throws an error
  * if given range is intersecting with any range that is already stored in this selection.
  *
  * @private
  * @method pushRange
- * @memberOf {treeModel.Selection}
- * @param {treeModel.Range} range Range to add.
+ * @memberOf {core.treeModel.Selection}
+ * @param {core.treeModel.Range} range Range to add.
  */
 function pushRange( range ) {
 	/* jshint validthis: true */
@@ -251,8 +249,8 @@ function pushRange( range ) {
 			 * Trying to add a range that intersects with another range from selection.
 			 *
 			 * @error selection-range-intersects
-			 * @param {treeModel.Range} addedRange Range that was added to the selection.
-			 * @param {treeModel.Range} intersectingRange Range from selection that intersects with `addedRange`.
+			 * @param {core.treeModel.Range} addedRange Range that was added to the selection.
+			 * @param {core.treeModel.Range} intersectingRange Range from selection that intersects with `addedRange`.
 			 */
 			throw new CKEditorError(
 				'selection-range-intersects: Trying to add a range that intersects with another range from selection.',

+ 4 - 5
packages/ckeditor5-engine/src/treemodel/text.js

@@ -8,12 +8,12 @@
 import utils from '../utils.js';
 
 /**
- * Data structure for text with attributes. Note that `Text` is not a {@link treeModel.Node}. This class is used
+ * Data structure for text with attributes. Note that `Text` is not a {@link core.treeModel.Node}. This class is used
  * as an aggregator for multiple characters that have same attributes. Example usage:
  *
  *		let myElem = new Element( 'li', [], new Text( 'text with attributes', { foo: true, bar: true } ) );
  *
- * @class treeModel.Text
+ * @memberOf core.treeModel
  */
 export default class Text {
 	/**
@@ -21,14 +21,13 @@ export default class Text {
 	 *
 	 * @param {String} text Described text.
 	 * @param {Iterable|Object} attrs Iterable collection of attributes.
-	 * @constructor
 	 */
 	constructor( text, attrs ) {
 		/**
 		 * Text.
 		 *
 		 * @readonly
-		 * @type {String}
+		 * @member {String} core.treeModel.Text#text
 		 */
 		this.text = text || '';
 
@@ -36,7 +35,7 @@ export default class Text {
 		 * List of attributes bound with the text.
 		 *
 		 * @protected
-		 * @type {Map}
+		 * @member {Map} core.treeModel.Text#_attrs
 		 */
 		this._attrs = utils.toMap( attrs );
 	}

+ 16 - 16
packages/ckeditor5-engine/src/treemodel/textfragment.js

@@ -10,35 +10,35 @@ import CharacterProxy from './characterproxy.js';
 /**
  * TextFragment is an aggregator for multiple CharacterProxy instances that are placed next to each other in
  * tree model, in the same parent, and all have same attributes set. Instances of this class are created and returned
- * in various algorithms that "merge characters" (see {@link treeModel.TreeWalker}, {@link treeModel.Range}).
+ * in various algorithms that "merge characters" (see {@link core.treeModel.TreeWalker}, {@link core.treeModel.Range}).
  *
- * Difference between {@link treeModel.TextFragment} and {@link treeModel.Text} is that the former is a set of
- * nodes taken from tree model, while {@link treeModel.Text} is simply a string with attributes set.
+ * Difference between {@link core.treeModel.TextFragment} and {@link core.treeModel.Text} is that the former is a set of
+ * nodes taken from tree model, while {@link core.treeModel.Text} is simply a string with attributes set.
  *
- * You should never create an instance of this class by your own. Instead, use string literals or {@link treeModel.Text}.
+ * You should never create an instance of this class by your own. Instead, use string literals or {@link core.treeModel.Text}.
  *
- * @class treeModel.TextFragment
+ * @memberOf core.treeModel
  */
 export default class TextFragment {
 	/**
 	 * Creates a text fragment.
 	 *
-	 * @param {treeModel.CharacterProxy} firstCharacter First character node contained in {@link treeModel.TextFragment}.
-	 * @param {Number} length Whole text contained in {@link treeModel.TextFragment}.
+	 * @param {core.treeModel.CharacterProxy} firstCharacter First character node contained in {@link core.treeModel.TextFragment}.
+	 * @param {Number} length Whole text contained in {@link core.treeModel.TextFragment}.
 	 * @protected
 	 * @constructor
 	 */
 	constructor( firstCharacter, length ) {
 		/**
-		 * First character node contained in {@link treeModel.TextFragment}.
+		 * First character node contained in {@link core.treeModel.TextFragment}.
 		 *
 		 * @readonly
-		 * @type {treeModel.CharacterProxy}
+		 * @type {core.treeModel.CharacterProxy}
 		 */
 		this.first = firstCharacter;
 
 		/**
-		 * Characters contained in {@link treeModel.TextFragment}.
+		 * Characters contained in {@link core.treeModel.TextFragment}.
 		 *
 		 * @readonly
 		 * @type {String}
@@ -46,28 +46,28 @@ export default class TextFragment {
 		this.text = firstCharacter._nodeListText.text.substr( this.first._index, length );
 
 		/**
-		 * Last {@link treeModel.CharacterProxy character node} contained in {@link treeModel.TextFragment}.
+		 * Last {@link core.treeModel.CharacterProxy character node} contained in {@link core.treeModel.TextFragment}.
 		 *
 		 * @readonly
-		 * @type {treeModel.CharacterProxy}
+		 * @type {core.treeModel.CharacterProxy}
 		 */
 		this.last = this.getCharAt( this.text.length - 1 );
 	}
 
 	/**
-	 * A common parent of all character nodes contained in {@link treeModel.TextFragment}.
+	 * A common parent of all character nodes contained in {@link core.treeModel.TextFragment}.
 	 *
-	 * @type {treeModel.Element}
+	 * @type {core.treeModel.Element}
 	 */
 	get commonParent() {
 		return this.first.parent;
 	}
 
 	/**
-	 * Gets a character at given index and creates a {@link treeModel.CharacterProxy} out of it.
+	 * Gets a character at given index and creates a {@link core.treeModel.CharacterProxy} out of it.
 	 *
 	 * @param {Number} index Character index.
-	 * @returns {treeModel.CharacterProxy}
+	 * @returns {core.treeModel.CharacterProxy}
 	 */
 	getCharAt( index ) {
 		if ( index < 0 || index >= this.text.length ) {

+ 30 - 30
packages/ckeditor5-engine/src/treemodel/treewalker.js

@@ -11,37 +11,20 @@ import Element from './element.js';
 import Position from './position.js';
 import CKEditorError from '../ckeditorerror.js';
 
-/**
- * Type of the step made by {@link treeModel.TreeWalker}.
- * Possible values: `'ELEMENT_START'` if walker is at the beginning of a node, `'ELEMENT_END'` if walker is at the end of node,
- * `'CHARACTER'` if walker traversed over a character, or `'TEXT'` if walker traversed over multiple characters (available in
- * character merging mode, see {@link treeModel.TreeWalker#constructor}).
- *
- * @typedef {String} treeModel.TreeWalkerItemType
- */
-
-/**
- * Object returned by {@link treeModel.TreeWalker} when traversing tree model.
- *
- * @typedef {Object} treeModel.TreeWalkerItem
- * @property {treeModel.TreeWalkerItemType} type
- * @property {treeModel.Node|treeModel.TextFragment} item Value between old and new position of {@link treeModel.TreeWalker}.
- */
-
 /**
  * Position iterator class. It allows to iterate forward and backward over the tree document.
  *
- * @class treeModel.TreeWalker
+ * @memberOf core.treeModel
  */
 export default class TreeWalker {
 	/**
 	 * Creates a range iterator. All parameters are optional, but you have to specify either `boundaries` or `position`.
 	 *
 	 * @param {Object} options Object with configuration.
-	 * @param {treeModel.Range} [options.boundaries] Range to define boundaries of the iterator.
-	 * @param {treeModel.Position} [options.position] Starting position.
+	 * @param {core.treeModel.Range} [options.boundaries] Range to define boundaries of the iterator.
+	 * @param {core.treeModel.Position} [options.position] Starting position.
 	 * @param {Boolean} [options.mergeCharacters=false] Flag indicating whether all consecutive characters with the same attributes
-	 * should be returned as one {@link treeModel.TextFragment} (`true`) or one by one as multiple {@link treeModel.CharacterProxy}
+	 * should be returned as one {@link core.treeModel.TextFragment} (`true`) or one by one as multiple {@link core.treeModel.CharacterProxy}
 	 * (`false`) objects.
 	 * @constructor
 	 */
@@ -63,7 +46,7 @@ export default class TreeWalker {
 		 *
 		 * If boundaries are not defined they are set before first and after last child of the root node.
 		 *
-		 * @type {treeModel.Range}
+		 * @type {core.treeModel.Range}
 		 */
 		this.boundaries = options.boundaries || null;
 
@@ -71,7 +54,7 @@ export default class TreeWalker {
 		 * Start boundary cached for optimization purposes.
 		 *
 		 * @private
-		 * @type {treeModel.Element}
+		 * @type {core.treeModel.Element}
 		 */
 		this._boundaryStartParent = this.boundaries ? this.boundaries.start.parent : null;
 
@@ -79,15 +62,15 @@ export default class TreeWalker {
 		 * End boundary cached for optimization purposes.
 		 *
 		 * @private
-		 * @type {treeModel.Element}
+		 * @type {core.treeModel.Element}
 		 */
 		this._boundaryEndParent = this.boundaries ? this.boundaries.end.parent : null;
 
 		/**
 		 * Iterator position. This is alway static position, even if the initial position was a
-		 * {@link treeModel.LivePosition live position}.
+		 * {@link core.treeModel.LivePosition live position}.
 		 *
-		 * @type {treeModel.Position}
+		 * @type {core.treeModel.Position}
 		 */
 		this.position = options.position ?
 			Position.createFromPosition( options.position ) :
@@ -95,7 +78,7 @@ export default class TreeWalker {
 
 		/**
 		 * Flag indicating whether all consecutive characters with the same attributes should be
-		 * returned as one {@link treeModel.CharacterProxy} (`true`) or one by one (`false`).
+		 * returned as one {@link core.treeModel.CharacterProxy} (`true`) or one by one (`false`).
 		 *
 		 * @type {Boolean}
 		 */
@@ -105,7 +88,7 @@ export default class TreeWalker {
 		 * Parent of the most recently visited node. Cached for optimization purposes.
 		 *
 		 * @private
-		 * @type {treeModel.Element}
+		 * @type {core.treeModel.Element}
 		 */
 		this._visitedParent = this.position.parent;
 	}
@@ -115,7 +98,7 @@ export default class TreeWalker {
 	 *
 	 * @returns {Object} Object implementing iterator interface, returning information about taken step.
 	 * @returns {Boolean} return.done True if iterator is done.
-	 * @returns {treeModel.TreeWalkerItem} return.value Information about taken step.
+	 * @returns {core.treeModel.TreeWalkerItem} return.value Information about taken step.
 	 */
 	next() {
 		const position = Position.createFromPosition( this.position );
@@ -179,7 +162,7 @@ export default class TreeWalker {
 	 *
 	 * @returns {Object} Object implementing iterator interface, returning information about taken step.
 	 * @returns {Boolean} return.done True if iterator is done.
-	 * @returns {treeModel.TreeWalkerItem} return.value Information about taken step.
+	 * @returns {core.treeModel.TreeWalkerItem} return.value Information about taken step.
 	 */
 	previous() {
 		const position = Position.createFromPosition( this.position );
@@ -248,3 +231,20 @@ function formatReturnValue( type, item ) {
 		}
 	};
 }
+
+/**
+ * Type of the step made by {@link core.treeModel.TreeWalker}.
+ * Possible values: `'ELEMENT_START'` if walker is at the beginning of a node, `'ELEMENT_END'` if walker is at the end of node,
+ * `'CHARACTER'` if walker traversed over a character, or `'TEXT'` if walker traversed over multiple characters (available in
+ * character merging mode, see {@link core.treeModel.TreeWalker#constructor}).
+ *
+ * @typedef {String} core.treeModel.TreeWalkerItemType
+ */
+
+/**
+ * Object returned by {@link core.treeModel.TreeWalker} when traversing tree model.
+ *
+ * @typedef {Object} core.treeModel.TreeWalkerItem
+ * @property {treeModel.TreeWalkerItemType} type
+ * @property {treeModel.Node|treeModel.TextFragment} item Value between old and new position of {@link core.treeModel.TreeWalker}.
+ */

+ 4 - 0
packages/ckeditor5-engine/src/utils.js

@@ -14,6 +14,9 @@ import isPlainObject from './lib/lodash/isPlainObject.js';
  * @typedef {String|Number} utils.ArrayRelation
  */
 
+/**
+ * @namespace core.utils
+ */
 const utils = {
 	/**
 	 * Creates a spy function (ala Sinon.js) that can be used to inspect call to it.
@@ -22,6 +25,7 @@ const utils = {
 	 *
 	 *  * spy.called: property set to `true` if the function has been called at least once.
 	 *
+	 * @member core.utils.spy
 	 * @returns {Function} The spy function.
 	 */
 	spy() {