Browse Source

Docs: Updated docs for the document. Added operation.delta property description.

Piotr Jasiun 10 years ago
parent
commit
298b25836e

+ 18 - 3
packages/ckeditor5-utils/src/document/document.js

@@ -16,13 +16,21 @@ CKEDITOR.define( [
 	const graveyardSymbol = Symbol( 'graveyard' );
 
 	/**
-	 * Document model.
+	 * Document tree model describes all editable data in the editor. In may contains multiple {@link #roots root elements},
+	 * for example if the editor have multiple editable areas, each area will be represented by the separate root.
+	 *
+	 * All changes in the document are done by {@link document.operation.Operation operations}. To create operations in
+	 * the simple way use use the {@link document.Transaction transaction} API, for example:
+	 *
+	 *	  document.makeTransaction().insert( position, nodes ).split( otherPosition );
+	 *
+	 * @see #makeTransaction
 	 *
 	 * @class document.Document
 	 */
 	class Document {
 		/**
-		 * Creates an empty document instance.
+		 * Creates an empty document instance with no {@link #roots}.
 		 *
 		 * @constructor
 		 */
@@ -50,7 +58,9 @@ CKEDITOR.define( [
 		}
 
 		/**
-		 * This is the only entry point for all document changes.
+		 * This is the entry point for all document changes. All changes on the document are done using
+		 * {@link document.operation.Operation operations}. To create operations in the simple way use the
+		 * {@link document.Transaction} API available via {@link #makeTransaction} method.
 		 *
 		 * @param {document.operation.Operation} operation Operation to be applied.
 		 */
@@ -133,6 +143,11 @@ CKEDITOR.define( [
 			return this.getRoot( graveyardSymbol );
 		}
 
+		/**
+		 * Creates a {@link document.Transaction} instance which allows to change the document.
+		 *
+		 * @returns {document.Transaction} Transaction instance.
+		 */
 		makeTransaction() {
 			return new Tranaction( this );
 		}

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

@@ -30,6 +30,14 @@ CKEDITOR.define( [], () => {
 			 */
 			this.baseVersion = baseVersion;
 
+			/**
+			 * {@link Document.Delta Delta} which the operation is a part of. This property is set by the
+			 * {@link Document.Delta delta} when the operations is added to it by the
+			 * {@link Document.Delta#addOperation} method.
+			 *
+			 * @property {Document.Delta} delta
+			 */
+
 			/**
 			 * Executes the operation - modifications described by the operation attributes
 			 * will be applied to the tree model.