Răsfoiți Sursa

Operation.getTransformedBy() docs updated, Operation.clone() docs introduced.

Szymon Cofalik 10 ani în urmă
părinte
comite
c84d2dd2b9
1 a modificat fișierele cu 29 adăugiri și 14 ștergeri
  1. 29 14
      packages/ckeditor5-utils/src/document/operation/operation.js

+ 29 - 14
packages/ckeditor5-utils/src/document/operation/operation.js

@@ -60,25 +60,40 @@ CKEDITOR.define( [], () => {
 			 */
 
 			/**
-			 * Creates and returns a clone of this operation which is transformed by the given operation.
-			 * When operation is transformed its parameters may change accordingly to the operation which it is
-			 * transformed by. If the given operation applied to the tree model any modifications which are
-			 * affecting ranges/positions/nodes connected with this operation, those changes will be reflected
-			 * in the parameters of the returned operation.
+			 * Creates and returns an array containing one or more operations, that are the result of
+			 * transforming this operation by the given operation. When operation is transformed its parameters
+			 * may change accordingly to the operation by which it is transformed. If the given operation
+			 * applied any modifications to the tree model that affects ranges/positions/nodes connected with this
+			 * operation, those changes will be reflected in the parameters of the returned operation(s).
 			 *
-			 * Whenever the {@link document.Document document} has different {@link document.Document#baseVersion}
-			 * than an operation you want to {@link document.Document#applyOperation apply}, you need to transform
-			 * all the operations that were executed on the {@link document.Document document} since it has
-			 * {@link document.Document#baseVersion} same as the operation (transform in the same order as those
-			 * operations were executed). This way all modifications done to the tree model will be reflected
-			 * in the operation parameters and the operation will "work" on "up-to-date" version of the tree model.
+			 * In some cases, when given operation apply changes to the same nodes as this operation, there is a need
+			 * to create two operations as a result. It would be impossible to create just one operation that handles
+			 * modifications needed to be applied to the tree. This is why array is returned instead of single object.
+			 * In those cases, returned Array will contain two or more objects. All of those operations has to be
+			 * applied or further transformed.
 			 *
-			 * **TODO**: So far we think that transforming one operation by another one may result in more than one
-			 * operation. This needs to be clarified in this documentation.
+			 * Whenever the {@link document.Document document} has different {@link document.Document#baseVersion}
+			 * than an operation you want to {@link document.Document#applyOperation apply}, you need to transform that
+			 * operation by all the operations that were executed on the {@link document.Document document} since it has
+			 * {@link document.Document#baseVersion} same as the operation. Transform them in the same order as those
+			 * operations were applied. This way all modifications done to the tree model will be reflected
+			 * in the operation parameters and the operation will "operate" on "up-to-date" version of the tree model.
+			 * This is mostly the case with Operational Transformation but it might be needed in features code.
 			 *
 			 * @method getTransformedBy
 			 * @param {document.operation.Operation} operation Operation by which this operation will be transformed.
-			 * @returns {document.operation.Operation[]} A result of transformation of this operation by the given operation.
+			 * @param {Boolean} isStrong Flag indicating whether this operation should be treated as more important
+			 * when resolving conflicts.
+			 * @returns {Array.<document.operation.Operation>} Result of the transformation.
+			 */
+
+			/**
+			 * Creates and returns an operation that has the same parameters as this operation.
+			 *
+			 * @method clone
+			 * @param {Number|null} baseVersion New baseVersion for cloned operation. Will copy this operation's
+			 * baseVersion if omitted.
+			 * @returns {document.operation.Operation} Clone of this operation.
 			 */
 		}
 	}