浏览代码

Transaction docs.

Piotr Jasiun 10 年之前
父节点
当前提交
8513eb1892

+ 2 - 0
packages/ckeditor5-engine/src/document/delta/register.js

@@ -5,6 +5,8 @@
 
 'use strict';
 
+// Register method exposed for deltas, which needs only this method, to make code simpler, more beautiful and, first of
+// all, to solve circular dependencies.
 CKEDITOR.define( [
 	'document/delta/transaction-base'
 ], ( Transaction ) => {

+ 71 - 0
packages/ckeditor5-engine/src/document/delta/transaction-base.js

@@ -7,10 +7,33 @@
 
 CKEDITOR.define( [ 'ckeditorerror' ], ( CKEditorError ) => {
 	/**
+	 * The transaction class groups document changes (deltas). All deltas grouped in a single transactions can be
+	 * reverted together, so you can think about the transaction as a single undo step. If you want to extend one
+	 * undo step you can call another method on the same transaction object. If you want to create a separate undo step
+	 * you can create a new transaction.
+	 *
+	 * For example to create two separate undo steps you can call:
+	 *
+	 *	  doc.makeTransaction().insert( firstPosition, 'foo' );
+	 *	  doc.makeTransaction().insert( secondPosition, 'bar' );
+	 *
+	 * To create a single undo step:
+	 *
+	 *	  const transaction = doc.makeTransaction()
+	 *	  transaction.insert( firstPosition, 'foo' );
+	 *	  transaction.insert( secontPosition, 'bar' );
+	 *
+	 * Note that all document modification methods (insert, remove, split, etc.) are chainable so you can shorten code to:
+	 *
+	 *	  doc.makeTransaction().insert( firstPosition, 'foo' ).insert( secontPosition, 'bar' );
+	 *
 	 * @class document.Transaction
 	 */
 	class Transaction {
 		/**
+		 * Creates transaction instance. Not recommended to use directly, use {@link document.Document#makeTransaction}
+		 * instead.
+		 *
 		 * @constructor
 		 */
 		constructor( doc ) {
@@ -18,6 +41,14 @@ CKEDITOR.define( [ 'ckeditorerror' ], ( CKEditorError ) => {
 			this.deltas = [];
 		}
 
+		/**
+		 * Adds delta to the transaction instance. All modification methods (insert, remove, split, etc.) use this method
+		 * to add created deltas.
+		 *
+		 * @param {document.delta.Delta} delta Delta to add.
+		 *
+		 * @return {document.delta.Delta} Added delta.
+		 */
 		addDelta( delta ) {
 			delta.transaction = this;
 			this.deltas.push( delta );
@@ -25,10 +56,50 @@ CKEDITOR.define( [ 'ckeditorerror' ], ( CKEditorError ) => {
 			return delta;
 		}
 
+		/**
+		 * Transaction provides iterator interface which will iterate over deltas in the transaction.
+		 */
 		[ Symbol.iterator ]() {
 			return this.deltas[ Symbol.iterator ]();
 		}
 
+		/**
+		 * Static method to register transaction methods. To make code scalable transaction do not have modification
+		 * methods build in. They can be registered using this method.
+		 *
+		 * This method check if there is no naming collision and throw `transaction-register-taken` if the method name
+		 * is already taken.
+		 *
+		 * It also pass {@link document.Document} and {@link document.Transaction} do the creator class.
+		 *
+		 * Registered function returns `this` so they because chainable by default.
+		 *
+		 * Beside that no magic happens here, the methods is added to the Transaction prototype.
+		 *
+		 * For example:
+		 *
+		 *		Transaction.register( 'insert', ( doc, transaction, position, nodes ) => {
+		 *			// You can use a class inherit from Delta if that class should handle OT in the special way.
+		 *			const delta = new Delta();
+		 *
+		 * 			// Create operations which should be components of this delta.
+		 *			const operation = new InsertOperation( position, nodes, doc.version );
+		 *
+		 *			// Remember to apply every operation, no magic, you need to do it manually.
+		 *			doc.applyOperation( operation );
+		 *
+		 *			// Add operation to the delta.
+		 *			delta.addOperation( operation );
+		 *
+		 *			// Add delta to the transaction instance.
+		 *			transaction.addDelta( delta );
+		 *
+		 * 			// You do not need to return transaction, register method will take care to make the method chainable.
+		 *		} );
+		 *
+		 * @param {String} name Method name.
+		 * @param {Fuction} creator Method body.
+		 */
 		static register( name, creator ) {
 			if ( Transaction.prototype[ name ] ) {
 				/**

+ 4 - 0
packages/ckeditor5-engine/src/document/transaction.js

@@ -5,6 +5,10 @@
 
 'use strict';
 
+// All deltas need to be loaded so they can register themselves as transaction methods.
+//
+// To solve circular dependencies (deltas need to require transaction class), transaction class body is moved
+// to document/delta/transaction-base.
 CKEDITOR.define( [
 	'document/delta/transaction-base',
 	'document/delta/insertdelta',