Sfoglia il codice sorgente

Docs for operations.

Piotr Jasiun 10 anni fa
parent
commit
a9095cb3f0

+ 47 - 0
packages/ckeditor5-utils/src/document/changeoperation.js

@@ -7,20 +7,62 @@
 
 CKEDITOR.define( [ 'document/operation', 'ckeditorerror', 'utils' ], function( Operation, CKEditorError, utils ) {
 	/**
+	 * Operation to change nodes attribute. Using this class you can add, remove or change value of the attribute.
+	 *
 	 * @class document.Operation
 	 */
 	class ChangeOperation extends Operation {
 		/**
+		 * Creates a change operation.
+		 *
+		 * If only new attribute is set it will be inserted. Note that there must be no attributes with the same key as
+		 * a new attribute in all nodes in ranges.
+		 *
+		 * If only old attribute is set it will be removed. Note that this attribute must be present in all nodes in
+		 * ranges.
+		 *
+		 * If both new and old attributes are set the operation will change the attribute value. Node 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 {Array|document.Range} ranges Range or array of ranges on which operation should be applied.
+		 * @param {document.Attribute|Null} oldAttr Old attribute to change. Null if operation inserts new attribute.
+		 * @param {document.Attribute|Null} newAttr New attribute. Null if operation removes attribute.
+		 * @param {Number} baseVersion {@link document.Document#version} on which operation can be applied.
 		 * @constructor
 		 */
 		constructor( ranges, oldAttr, newAttr, baseVersion ) {
 			super( baseVersion );
 
+			/**
+			 * Array of ranges on which operation should be applied.
+			 *
+			 * @readonly
+			 * @type {Array}
+			 */
 			this.ranges = utils.isArray( ranges ) ? ranges : [ ranges ];
+
+			/**
+			 * Old attribute to change. Null if operation inserts new attribute.
+			 *
+			 * @readonly
+			 * @type {document.Attribute|Null}
+			 */
 			this.oldAttr = oldAttr;
+
+			/**
+			 * New attribute. Null if operation removes attribute.
+			 *
+			 * @readonly
+			 * @type {document.Attribute|Null}
+			 */
 			this.newAttr = newAttr;
 		}
 
+		/**
+		 * Execute operation.
+		 *
+		 * @protected
+		 */
 		_execute() {
 			var ranges = this.ranges;
 			var oldAttr = this.oldAttr;
@@ -129,6 +171,11 @@ CKEDITOR.define( [ 'document/operation', 'ckeditorerror', 'utils' ], function( O
 			}
 		}
 
+		/**
+		 * Creates an reverse change operation.
+		 *
+		 * @returns {document.ChangeOperation} Reverse operation.
+		 */
 		reverseOperation() {
 			return new ChangeOperation( this.ranges, this.newAttr, this.oldAttr, this.baseVersion + 1 );
 		}

+ 33 - 4
packages/ckeditor5-utils/src/document/insertoperation.js

@@ -7,25 +7,54 @@
 
 CKEDITOR.define( [ 'document/operation', 'document/nodelist', 'document/removeoperation' ], function( Operation, NodeList ) {
 	/**
+	 * Operation to insert list of nodes on the given position.
 	 *
-	 *
-	 * @class document.Operation
+	 * @class document.InsertOperation
 	 */
 	class InsertOperation extends Operation {
 		/**
+		 * Creates an insert operation.
+		 *
+		 * @param {document.Position} position Position of insertion.
+		 * @param {document.Node|document.Text|document.NodeList|String|Array} nodes List of nodes to be inserted.
+		 * List of nodes can be any type accepted by the {@link document.NodeList} constructor.
+		 * @param {Number} baseVersion {@link document.Document#version} on which operation can be applied.
 		 * @constructor
 		 */
-		constructor( position, nodeList, baseVersion ) {
+		constructor( position, nodes, baseVersion ) {
 			super( baseVersion );
 
+			/**
+			 * Position of insertion.
+			 *
+			 * @readonly
+			 * @type {document.Position}
+			 */
 			this.position = position;
-			this.nodeList = new NodeList( nodeList );
+
+			/**
+			 * List of nodes to insert.
+			 *
+			 * @readonly
+			 * @type {document.NodeList}
+			 */
+			this.nodeList = new NodeList( nodes );
 		}
 
+		/**
+		 * Execute operation.
+		 *
+		 * @protected
+		 */
 		_execute() {
 			this.position.parent.insertChildren( this.position.offset, this.nodeList );
 		}
 
+		/**
+		 * Creates an reverse remove operation.
+		 *
+		 * @returns {document.RemoveOperation} Reverse operation.
+		 */
 		reverseOperation() {
 			var RemoveOperation = CKEDITOR.require( 'document/removeoperation' );
 

+ 42 - 3
packages/ckeditor5-utils/src/document/moveoperation.js

@@ -12,22 +12,56 @@ CKEDITOR.define( [
 	'utils'
 ], function( Operation, NodeList, CKEditorError, utils ) {
 	/**
-	 *
+	 * Operation to move list of following nodes from the one position in the document to another.
 	 *
 	 * @class document.Operation
 	 */
 	class MoveOperation extends Operation {
 		/**
+		 * Creates a move operation.
+		 *
+		 * Note that this constructor is used not only to create an operation on the current state of the document,
+		 * but also to create reverse operation or the result of the operational transformation. The operation also
+		 * needs to keep data needed to transform it (creates an insert operation from the move & remove combination).
+		 * This is why this constructor contains list of nodes instead of length.
+		 *
+		 * @param {document.Position} sourcePosition Source move position.
+		 * @param {document.Position} targetPosition Target move position.
+		 * @param {document.Node|document.Text|document.NodeList|String|Array} nodes List of nodes to be moved.
+		 * List of nodes can be any type accepted by the {@link document.NodeList} constructor.
+		 * @param {Number} baseVersion {@link document.Document#version} on which operation can be applied.
 		 * @constructor
 		 */
-		constructor( sourcePosition, targetPosition, nodeList, baseVersion ) {
+		constructor( sourcePosition, targetPosition, nodes, baseVersion ) {
 			super( baseVersion );
 
+			/**
+			 * Source move position.
+			 *
+			 * @type {document.Position}
+			 */
 			this.sourcePosition = sourcePosition;
+
+			/**
+			 * Target move position.
+			 *
+			 * @type {document.Position}
+			 */
 			this.targetPosition = targetPosition;
-			this.nodeList = new NodeList( nodeList );
+
+			/**
+			 * List of nodes to move.
+			 *
+			 * @type {document.NodeList}
+			 */
+			this.nodeList = new NodeList( nodes );
 		}
 
+		/**
+		 * Execute operation.
+		 *
+		 * @protected
+		 */
 		_execute() {
 			var sourceElement = this.sourcePosition.parent;
 			var targetElement = this.targetPosition.parent;
@@ -66,6 +100,11 @@ CKEDITOR.define( [
 			targetElement.insertChildren( targetOffset, this.nodeList );
 		}
 
+		/**
+		 * Creates an reverse move operation.
+		 *
+		 * @returns {document.MoveOperation} Reverse operation.
+		 */
 		reverseOperation() {
 			return new MoveOperation( this.targetPosition, this.sourcePosition, this.nodeList, this.baseVersion + 1 );
 		}

+ 13 - 0
packages/ckeditor5-utils/src/document/operation.js

@@ -7,13 +7,26 @@
 
 CKEDITOR.define( [], function() {
 	/**
+	 * Abstract base operation class.
+	 *
 	 * @class document.Operation
 	 */
 	class Operation {
 		/**
+		 * Base operation constructor.
+		 *
+		 * @param {Number} baseVersion {@link document.Document#version} on which operation can be applied.
 		 * @constructor
 		 */
 		constructor( baseVersion ) {
+			/**
+			 * {@link document.Document#version} on which operation can be applied. If you try to
+			 * {@link document.Document#applyOperation apply} operation with different base version then
+			 * {@link document.Document#version document version} the {@link document-applyOperation-wrong-version}
+			 * error is thrown.
+			 *
+			 * @type {Number}
+			 */
 			this.baseVersion = baseVersion;
 		}
 	}

+ 34 - 2
packages/ckeditor5-utils/src/document/removeoperation.js

@@ -13,21 +13,48 @@ CKEDITOR.define( [
 	'document/insertoperation'
 ], function( Operation, NodeList, CKEditorError, utils ) {
 	/**
+	 * Operation to remove list of nodes.
 	 *
-	 *
-	 * @class document.Operation
+	 * @class document.RemoveOperation
 	 */
 	class RemoveOperation extends Operation {
 		/**
+		 * Creates a remove operation.
+		 *
+		 * Note that this constructor is used not only to create an operation on the current state of the document,
+		 * but also to create reverse operation or the result of the operational transformation. The operation also
+		 * needs to keep data needed to transform it (creates an insert operation as a reverse of the remove).
+		 * This is why this constructor contains list of nodes instead of length.
+		 *
+		 * @param {document.Position} position Position before the first node to remove.
+		 * @param {document.Node|document.Text|document.NodeList|String|Array} nodes List of nodes to be remove.
+		 * List of nodes can be any type accepted by the {@link document.NodeList} constructor.
+		 * @param {Number} baseVersion {@link document.Document#version} on which operation can be applied.
 		 * @constructor
 		 */
 		constructor( position, nodes, baseVersion ) {
 			super( baseVersion );
 
+			/**
+			 * Position of insertion.
+			 *
+			 * @type {document.Position}
+			 */
 			this.position = position;
+
+			/**
+			 * List of nodes to insert.
+			 *
+			 * @type {document.NodeList}
+			 */
 			this.nodeList = new NodeList( nodes );
 		}
 
+		/**
+		 * Execute operation.
+		 *
+		 * @protected
+		 */
 		_execute() {
 			var parent = this.position.parent;
 			var offset = this.position.offset;
@@ -55,6 +82,11 @@ CKEDITOR.define( [
 			parent.removeChildren( offset, this.nodeList.length );
 		}
 
+		/**
+		 * Creates an reverse insert operation.
+		 *
+		 * @returns {document.InsertOperation} Reverse operation.
+		 */
 		reverseOperation() {
 			var InsertOperation = CKEDITOR.require( 'document/insertoperation' );
 

+ 1 - 0
packages/ckeditor5-utils/src/document/text.js

@@ -17,6 +17,7 @@ CKEDITOR.define( [], function() {
 		 * Creates text with attributes.
 		 *
 		 * @param {String} text Described character.
+		 * @param {Array} attrs Array of attributes.
 		 * @constructor
 		 */
 		constructor( text, attrs ) {