|
|
@@ -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.
|
|
|
*/
|
|
|
}
|
|
|
}
|