瀏覽代碼

Documentation: update core.treecontroller.operation documentation.

Maciej Gołaszewski 9 年之前
父節點
當前提交
3937121407

+ 4 - 0
packages/ckeditor5-engine/src/treemodel/operation.jsdoc

@@ -0,0 +1,4 @@
+/**
+ * Core → TreeModel → Operation namespace (`core.treeModel.operation`).
+ * @namespace core.treeModel.operation
+ */

+ 34 - 24
packages/ckeditor5-engine/src/treemodel/operation/attributeoperation.js

@@ -11,30 +11,28 @@ import CKEditorError from '../../ckeditorerror.js';
 import TextFragment from '../textfragment.js';
 
 /**
- * Operation to change nodes' attribute. Using this class you can add, remove or change value of the attribute.
+ * Creates an operation that changes, removes or adds attributes.
+ *
+ * If only the new attribute is set, then it will be inserted. Note that in all nodes in ranges there must be
+ * no attributes with the same key as the new attribute.
+ *
+ * If only the old attribute is set, then it will be removed. Note that this attribute must be present in all nodes in
+ * ranges.
  *
- * @class treeModel.operation.AttributeOperation
+ * If both new and old attributes are set, then the operation will change the attribute value. Note that both new and
+ * old attributes have to have the same key and the old attribute must be present in all nodes in ranges.
+ *
+ * @param {core.treeModel.Range} range Range on which the operation should be applied.
+ * @param {String} key Key of an attribute to change or remove.
+ * @param {*} oldValue Old value of the attribute with given key or `null` if adding a new attribute.
+ * @param {*} newValue New value to set for the attribute. If `null`, then the operation just removes the attribute.
+ * @param {Number} baseVersion {@link core.treeModel.Document#version} on which the operation can be applied.
+ * @class core.treeModel.operation.AttributeOperation
+ * @classdesc
+ * Operation to change nodes' attribute. Using this class you can add, remove or change value of the attribute.
+ * @extends core.treeModel.operation.Operation
  */
 export default class AttributeOperation extends Operation {
-	/**
-	 * Creates an operation that changes, removes or adds attributes.
-	 *
-	 * If only the new attribute is set, then it will be inserted. Note that in all nodes in ranges there must be
-	 * no attributes with the same key as the new attribute.
-	 *
-	 * If only the old attribute is set, then it will be removed. Note that this attribute must be present in all nodes in
-	 * ranges.
-	 *
-	 * If both new and old attributes are set, then the operation will change the attribute value. Note that both new and
-	 * old attributes have to have the same key and the old attribute must be present in all nodes in ranges.
-	 *
-	 * @param {treeModel.Range} range Range on which the operation should be applied.
-	 * @param {String} key Key of an attribute to change or remove.
-	 * @param {*} oldValue Old value of the attribute with given key or `null` if adding a new attribute.
-	 * @param {*} newValue New value to set for the attribute. If `null`, then the operation just removes the attribute.
-	 * @param {Number} baseVersion {@link treeModel.Document#version} on which the operation can be applied.
-	 * @constructor
-	 */
 	constructor( range, key, oldValue, newValue, baseVersion ) {
 		super( baseVersion );
 
@@ -42,7 +40,8 @@ export default class AttributeOperation extends Operation {
 		 * Range on which operation should be applied.
 		 *
 		 * @readonly
-		 * @type {treeModel.Range}
+		 * @member core.treeModel.operation.AttributeOperation#range
+		 * @type {core.treeModel.Range}
 		 */
 		this.range = Range.createFromRange( range );
 
@@ -50,6 +49,7 @@ export default class AttributeOperation extends Operation {
 		 * Key of an attribute to change or remove.
 		 *
 		 * @readonly
+		 * @member core.treeModel.operation.AttributeOperation#key
 		 * @type {String}
 		 */
 		this.key = key;
@@ -57,6 +57,7 @@ export default class AttributeOperation extends Operation {
 		/**
 		 * Old value of the attribute with given key or `null` if adding a new attribute.
 		 *
+		 * @member core.treeModel.operation.AttributeOperation#oldValue
 		 * @readonly
 		 * @type {*}
 		 */
@@ -65,6 +66,7 @@ export default class AttributeOperation extends Operation {
 		/**
 		 * New value to set for the attribute. If `null`, then the operation just removes the attribute.
 		 *
+		 * @member core.treeModel.operation.AttributeOperation#newValue
 		 * @readonly
 		 * @type {*}
 		 */
@@ -75,10 +77,18 @@ export default class AttributeOperation extends Operation {
 		return 'attr';
 	}
 
+	/**
+	 * @method core.treeModel.operation.AttributeOperation#clone
+	 * @returns {core.treeModel.operation.AttributeOperation}
+	 */
 	clone() {
 		return new AttributeOperation( this.range, this.key, this.oldValue, this.newValue, this.baseVersion );
 	}
 
+	/**
+	 * @method core.treeModel.operation.AttributeOperation#clone
+	 * @returns {core.treeModel.operation.AttributeOperation}
+	 */
 	getReversed() {
 		return new AttributeOperation( this.range, this.key, this.newValue, this.oldValue, this.baseVersion + 1 );
 	}
@@ -90,7 +100,7 @@ export default class AttributeOperation extends Operation {
 				 * The attribute which should be removed does not exists for the given node.
 				 *
 				 * @error operation-attribute-no-attr-to-remove
-				 * @param {treeModel.Node} node
+				 * @param {core.treeModel.Node} node
 				 * @param {String} key
 				 * @param {*} value
 				 */
@@ -105,7 +115,7 @@ export default class AttributeOperation extends Operation {
 				 * The attribute with given key already exists for the given node.
 				 *
 				 * @error operation-attribute-attr-exists
-				 * @param {treeModel.Node} node
+				 * @param {core.treeModel.Node} node
 				 * @param {String} key
 				 */
 				throw new CKEditorError(

+ 22 - 13
packages/ckeditor5-engine/src/treemodel/operation/insertoperation.js

@@ -12,36 +12,37 @@ import Range from '../range.js';
 import RemoveOperation from './removeoperation.js';
 
 /**
- * Operation to insert list of nodes on the given position in the tree data model.
+ * Creates an insert operation.
+ *
+ * @param {core.treeModel.Position} position Position of insertion.
+ * @param {core.treeModel.NodeSet} nodes The list of nodes to be inserted.
+ * List of nodes can be any type accepted by the {@link core.treeModel.NodeList} constructor.
+ * @param {Number} baseVersion {@link core.treeModel.Document#version} on which operation can be applied.
  *
- * @class treeModel.operation.InsertOperation
+ * @class core.treeModel.operation.InsertOperation
+ * @classdesc
+ * Operation to insert list of nodes on the given position in the tree data model.
+ * @extends core.treeModel.operation.Operation
  */
 export default class InsertOperation extends Operation {
-	/**
-	 * Creates an insert operation.
-	 *
-	 * @param {treeModel.Position} position Position of insertion.
-	 * @param {treeModel.NodeSet} nodes The list of nodes to be inserted.
-	 * List of nodes can be any type accepted by the {@link treeModel.NodeList} constructor.
-	 * @param {Number} baseVersion {@link treeModel.Document#version} on which operation can be applied.
-	 * @constructor
-	 */
 	constructor( position, nodes, baseVersion ) {
 		super( baseVersion );
 
 		/**
 		 * Position of insertion.
 		 *
+		 * @member core.treeModel.operation.InsertOperation#position
 		 * @readonly
-		 * @type {treeModel.Position}
+		 * @type {core.treeModel.Position}
 		 */
 		this.position = Position.createFromPosition( position );
 
 		/**
 		 * List of nodes to insert.
 		 *
+		 * @member core.treeModel.operation.InsertOperation#nodeList
 		 * @readonly
-		 * @type {treeModel.NodeList}
+		 * @type {core.treeModel.NodeList}
 		 */
 		this.nodeList = new NodeList( nodes );
 	}
@@ -50,10 +51,18 @@ export default class InsertOperation extends Operation {
 		return 'insert';
 	}
 
+	/**
+	 * @method core.treeModel.operation.InsertOperation#clone
+	 * @returns {core.treeModel.operation.InsertOperation}
+	 */
 	clone() {
 		return new InsertOperation( this.position, this.nodeList, this.baseVersion );
 	}
 
+	/**
+	 * @method core.treeModel.operation.InsertOperation#getReversed
+	 * @returns {core.treeModel.operation.RemoveOperation}
+	 */
 	getReversed() {
 		return new RemoveOperation( this.position, this.nodeList.length, this.baseVersion + 1 );
 	}

+ 23 - 13
packages/ckeditor5-engine/src/treemodel/operation/moveoperation.js

@@ -12,33 +12,34 @@ import CKEditorError from '../../ckeditorerror.js';
 import utils from '../../utils.js';
 
 /**
- * Operation to move list of subsequent nodes from one position in the document to another.
+ * Creates a move operation.
+ *
+ * @param {core.treeModel.Position} sourcePosition Position before the first node to move.
+ * @param {Number} howMany How many consecutive nodes to move, starting from `sourcePosition`.
+ * @param {core.treeModel.Position} targetPosition Position where moved nodes will be inserted.
+ * @param {Number} baseVersion {@link core.treeModel.Document#version} on which operation can be applied.
  *
- * @class treeModel.operation.MoveOperation
+ * @class core.treeModel.operation.MoveOperation
+ * @classdesc
+ * Operation to move list of subsequent nodes from one position in the document to another.
+ * @extends core.treeModel.operation.Operation
  */
 export default class MoveOperation extends Operation {
-	/**
-	 * Creates a move operation.
-	 *
-	 * @param {treeModel.Position} sourcePosition Position before the first node to move.
-	 * @param {Number} howMany How many consecutive nodes to move, starting from `sourcePosition`.
-	 * @param {treeModel.Position} targetPosition Position where moved nodes will be inserted.
-	 * @param {Number} baseVersion {@link treeModel.Document#version} on which operation can be applied.
-	 * @constructor
-	 */
 	constructor( sourcePosition, howMany, targetPosition, baseVersion ) {
 		super( baseVersion );
 
 		/**
 		 * Source move position.
 		 *
-		 * @type {treeModel.Position}
+		 * @member core.treeModel.operation.MoveOperation#sourcePosition
+		 * @type {core.treeModel.Position}
 		 */
 		this.sourcePosition = Position.createFromPosition( sourcePosition );
 
 		/**
 		 * How many nodes to move.
 		 *
+		 * @member core.treeModel.operation.MoveOperation#howMany
 		 * @type {Number}
 		 */
 		this.howMany = howMany;
@@ -46,7 +47,8 @@ export default class MoveOperation extends Operation {
 		/**
 		 * Target move position.
 		 *
-		 * @type {treeModel.Position}
+		 * @member core.treeModel.operation.MoveOperation#targetPosition
+		 * @type {core.treeModel.Position}
 		 */
 		this.targetPosition = Position.createFromPosition( targetPosition );
 	}
@@ -55,10 +57,18 @@ export default class MoveOperation extends Operation {
 		return 'move';
 	}
 
+	/**
+	 * @method core.treeModel.operation.MoveOperation#clone
+	 * @returns {core.treeModel.operation.MoveOperation}
+	 */
 	clone() {
 		return new this.constructor( this.sourcePosition, this.howMany, this.targetPosition, this.baseVersion );
 	}
 
+	/**
+	 * @method core.treeModel.operation.MoveOperation#getReversed
+	 * @returns {core.treeModel.operation.MoveOperation}
+	 */
 	getReversed() {
 		return new this.constructor( this.targetPosition, this.howMany, this.sourcePosition, this.baseVersion + 1 );
 	}

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

@@ -8,6 +8,8 @@
 import Operation from './operation.js';
 
 /**
+ * @class core.treeModel.operation.NoOperation
+ * @classdesc
  * Operation which is doing nothing ("empty operation", "do-nothing operation", "noop").
  * This is an operation, which when executed does not change the tree model.
  * It still has some parameters defined for transformation purposes.
@@ -15,14 +17,21 @@ import Operation from './operation.js';
  * 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
  * have already been applied.
- *
- * @class treeModel.operation.NoOperation
+ * @extends core.treeModel.operation.Operation
  */
 export default class NoOperation extends Operation {
+	/**
+	 * @method core.treeModel.operation.NoOperation#clone
+	 * @returns {core.treeModel.operation.NoOperation}
+	 */
 	clone() {
 		return new NoOperation( this.baseVersion );
 	}
 
+	/**
+	 * @method core.treeModel.operation.NoOperation#getReversed
+	 * @returns {core.treeModel.operation.NoOperation}
+	 */
 	getReversed() {
 		return new NoOperation( this.baseVersion + 1 );
 	}

+ 20 - 22
packages/ckeditor5-engine/src/treemodel/operation/operation.js

@@ -6,26 +6,22 @@
 'use strict';
 
 /**
- * Abstract base operation class.
- *
+ * Base operation constructor.
+ * @param {Number} baseVersion {@link core.treeModel.Document#version} on which the operation can be applied.
  * @abstract
- * @class treeModel.operation.Operation
+ * @class core.treeModel.operation.Operation
+ * @classdesc Abstract base operation class.
  */
 export default class Operation {
-	/**
-	 * Base operation constructor.
-	 *
-	 * @param {Number} baseVersion {@link treeModel.Document#version} on which the operation can be applied.
-	 * @constructor
-	 */
 	constructor( baseVersion ) {
 		/**
-		 * {@link treeModel.Document#version} on which operation can be applied. If you try to
-		 * {@link treeModel.Document#applyOperation apply} operation with different base version than the
-		 * {@link treeModel.Document#version document version} the {@link document-applyOperation-wrong-version}
+		 * {@link core.treeModel.Document#version} on which operation can be applied. If you try to
+		 * {@link core.treeModel.Document#applyOperation apply} operation with different base version than the
+		 * {@link core.treeModel.Document#version document version} the {@link document-applyOperation-wrong-version}
 		 * error is thrown.
 		 *
 		 * @type {Number}
+		 * @member core.treeModel.operation.Operation#baseVersion
 		 */
 		this.baseVersion = baseVersion;
 
@@ -33,21 +29,23 @@ export default class Operation {
 		 * Operation type.
 		 *
 		 * @type {String}
+		 * @member core.treeModel.operation.Operation#type
 		 */
 
 		/**
-		 * {@link treeModel.Delta Delta} which the operation is a part of. This property is set by the
-		 * {@link treeModel.Delta delta} when the operations is added to it by the
-		 * {@link treeModel.Delta#addOperation} method.
+		 * {@link core.treeModel.Delta Delta} which the operation is a part of. This property is set by the
+		 * {@link core.treeModel.Delta delta} when the operations is added to it by the
+		 * {@link core.treeModel.Delta#addOperation} method.
 		 *
-		 * @type {treeModel.Delta}
+		 * @type {core.treeModel.Delta}
+		 * @member core.treeModel.operation.Operation#delta
 		 */
 
 		/**
 		 * Creates and returns an operation that has the same parameters as this operation.
 		 *
-		 * @method clone
-		 * @returns {treeModel.operation.Operation} Clone of this operation.
+		 * @method core.treeModel.operation.Operation#clone
+		 * @returns {core.treeModel.operation.Operation} Clone of this operation.
 		 */
 
 		/**
@@ -57,10 +55,10 @@ export default class Operation {
 		 *
 		 * Keep in mind that tree model state may change since executing the original operation,
 		 * so reverse operation will be "outdated". In that case you will need to
-		 * {@link treeModel.operation.transform} it by all operations that were executed after the original operation.
+		 * {@link core.treeModel.operation.transform} it by all operations that were executed after the original operation.
 		 *
-		 * @method getReversed
-		 * @returns {treeModel.operation.Operation} Reversed operation.
+		 * @method core.treeModel.operation.Operation#getReversed
+		 * @returns {core.treeModel.operation.Operation} Reversed operation.
 		 */
 
 		/**
@@ -68,7 +66,7 @@ export default class Operation {
 		 * will be applied to the tree model.
 		 *
 		 * @protected
-		 * @method _execute
+		 * @method core.treeModel.operation.Operation#_execute
 		 * @returns {Object} Object with additional information about the applied changes. Always has `range`
 		 * property containing changed nodes. May have additional properties depending on the operation type.
 		 */

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

@@ -9,6 +9,8 @@ import MoveOperation from './moveoperation.js';
 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.
@@ -16,10 +18,13 @@ import RemoveOperation from './removeoperation.js';
  * 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
  * will be easier to expand if we need to change operation's behavior if it is remove/reinsert.
- *
- * @class treeModel.operation.ReinsertOperation
+ * @extends core.treeModel.operation.Operation
  */
 export default class ReinsertOperation extends MoveOperation {
+	/**
+	 * @method core.treeModel.operation.ReinsertOperation#getReversed
+	 * @returns {core.treeModel.operation.RemoveOperation}
+	 */
 	getReversed() {
 		return new RemoveOperation( this.targetPosition, this.howMany, this.baseVersion + 1 );
 	}
@@ -27,4 +32,4 @@ export default class ReinsertOperation extends MoveOperation {
 	get type() {
 		return 'reinsert';
 	}
-}
+}

+ 16 - 10
packages/ckeditor5-engine/src/treemodel/operation/removeoperation.js

@@ -10,19 +10,17 @@ import Position from '../position.js';
 import ReinsertOperation from './reinsertoperation.js';
 
 /**
- * Operation to remove a range of nodes.
+ * Creates a remove operation.
  *
- * @class treeModel.operation.RemoveOperation
+ * @param {core.treeModel.Position} position Position before the first node to remove.
+ * @param {Number} howMany How many nodes to remove.
+ * @param {Number} baseVersion {@link core.treeModel.Document#version} on which operation can be applied.
+ *
+ * @class core.treeModel.operation.RemoveOperation
+ * @classdesc Operation to remove a range of nodes.
+ * @extends core.treeModel.operation.Operation
  */
 export default class RemoveOperation extends MoveOperation {
-	/**
-	 * Creates a remove operation.
-	 *
-	 * @param {treeModel.Position} position Position before the first node to remove.
-	 * @param {Number} howMany How many nodes to remove.
-	 * @param {Number} baseVersion {@link treeModel.Document#version} on which operation can be applied.
-	 * @constructor
-	 */
 	constructor( position, howMany, baseVersion ) {
 		// Position in a graveyard where nodes were moved.
 		const graveyardPosition = Position.createFromParentAndOffset( position.root.document.graveyard, 0 );
@@ -34,10 +32,18 @@ export default class RemoveOperation extends MoveOperation {
 		return 'remove';
 	}
 
+	/**
+	 * @method core.treeModel.operation.ReinsertOperation#getReversed
+	 * @returns {core.treeModel.operation.ReinsertOperation}
+	 */
 	getReversed() {
 		return new ReinsertOperation( this.targetPosition, this.howMany, this.sourcePosition, this.baseVersion + 1 );
 	}
 
+	/**
+	 * @method core.treeModel.operation.RemoveOperation#clone
+	 * @returns {core.treeModel.operation.RemoveOperation}
+	 */
 	clone() {
 		return new RemoveOperation( this.sourcePosition, this.howMany, this.baseVersion );
 	}

+ 13 - 11
packages/ckeditor5-engine/src/treemodel/operation/transform.js

@@ -15,19 +15,20 @@ import isEqual from '../../lib/lodash/isEqual.js';
 import utils from '../../utils.js';
 
 /**
- * Transforms given {treeModel.operation.Operation} by another {treeModel.operation.Operation} and returns the result of
- * that transformation as an array containing one or more {treeModel.operation.Operation} elements.
+ * Transforms given {@link core.treeModel.operation.Operation operation} by another {@link core.treeModel.operation.Operation operation} and
+ * returns the result of that transformation as an array containing one or more {@link core.treeModel.operation.Operation operation}
+ * elements.
  *
- * Operations work on specified positions, passed to them when they are created. Whenever {@link treeModel.Document document}
+ * Operations work on specified positions, passed to them when they are created. Whenever {@link core.treeModel.Document document}
  * changes, we have to reflect those modifications by updating or "transforming" operations which are not yet applied.
  * When an operation is transformed, its parameters may change based on the operation by which it is transformed.
  * If the transform-by operation applied any modifications to the Tree Data Model which affect positions or nodes
  * connected with transformed operation, those changes will be reflected in the parameters of the returned operation(s).
  *
- * Whenever the {@link treeModel.Document document} has different {@link treeModel.Document#baseVersion}
- * than the operation you want to {@link treeModel.Document#applyOperation apply}, you need to transform that
- * operation by all operations which were already applied to the {@link treeModel.Document document} and have greater
- * {@link treeModel.Document#baseVersion} than the operation being applied. Transform them in the same order as those
+ * Whenever the {@link core.treeModel.Document document} has different {@link core.treeModel.Document#baseVersion}
+ * than the operation you want to {@link core.treeModel.Document#applyOperation apply}, you need to transform that
+ * operation by all operations which were already applied to the {@link core.treeModel.Document document} and have greater
+ * {@link core.treeModel.Document#baseVersion} than the operation being applied. Transform them in the same order as those
  * operations which were applied. This way all modifications done to the Tree Data Model will be reflected
  * in the operation parameters and the operation will "operate" on "up-to-date" version of the Tree Data Model.
  * This is mostly the case with Operational Transformations but it might be needed in particular features as well.
@@ -44,12 +45,13 @@ import utils from '../../utils.js';
  * `a` by `b` and also `b` by `a`. In both transformations the same operation has to be the important one. If we assume
  * that first or the second passed operation is always more important we won't be able to solve this case.
  *
- * @function treeModel.operation.transform
- * @param {treeModel.operation.Operation} a Operation that will be transformed.
- * @param {treeModel.operation.Operation} b Operation to transform by.
+ * @external core.treeModel.operation
+ * @function core.treeModel.operation.transform
+ * @param {core.treeModel.operation.Operation} a Operation that will be transformed.
+ * @param {core.treeModel.operation.Operation} b Operation to transform by.
  * @param {Boolean} isAMoreImportantThanB Flag indicating whether the operation which will be transformed (`a`) should be treated
  * as more important when resolving conflicts.
- * @returns {Array.<treeModel.operation.Operation>} Result of the transformation.
+ * @returns {Array.<core.treeModel.operation.Operation>} Result of the transformation.
  */
 
 export default transform;