Procházet zdrojové kódy

Doc fixes in Document, changed methods order in Document.

Szymon Cofalik před 10 roky
rodič
revize
e1ea3c1682
1 změnil soubory, kde provedl 69 přidání a 68 odebrání
  1. 69 68
      packages/ckeditor5-engine/src/treemodel/document.js

+ 69 - 68
packages/ckeditor5-engine/src/treemodel/document.js

@@ -60,88 +60,96 @@ CKEDITOR.define( [
 			 * Array of pending changes. See: {@link #enqueueChanges}.
 			 *
 			 * @private
-			 * @type {Array.<Function>}
+			 * @property {Array.<Function>}
 			 */
 			this._pendingChanges = [];
 		}
 
 		/**
-		 * Creates a new top-level root.
+		 * Graveyard tree root. Document always have a graveyard root, which stores removed nodes.
 		 *
-		 * @param {String|Symbol} name Unique root name.
-		 * @returns {treeModel.RootElement} Created root.
+		 * @readonly
+		 * @property {treeModel.RootElement} graveyard
 		 */
-		createRoot( name ) {
-			if ( this.roots.has( name ) ) {
+		get graveyard() {
+			return this.getRoot( graveyardSymbol );
+		}
+
+		/**
+		 * This is the entry point for all document changes. All changes on the document are done using
+		 * {@link treeModel.operation.Operation operations}. To create operations in the simple way use the
+		 * {@link treeModel.Batch} API available via {@link #batch} method.
+		 *
+		 * This method calls {@link #change} event.
+		 *
+		 * @param {treeModel.operation.Operation} operation Operation to be applied.
+		 */
+		applyOperation( operation ) {
+			if ( operation.baseVersion !== this.version ) {
 				/**
-				 * Root with specified name already exists.
+				 * Only operations with matching versions can be applied.
 				 *
-				 * @error document-createRoot-name-exists
-				 * @param {treeModel.Document} doc
-				 * @param {String} name
+				 * @error document-applyOperation-wrong-version
+				 * @param {treeModel.operation.Operation} operation
 				 */
 				throw new CKEditorError(
-					'document-createRoot-name-exists: Root with specified name already exists.',
-					{ name: name }
-				);
+					'document-applyOperation-wrong-version: Only operations with matching versions can be applied.',
+					{ operation: operation } );
 			}
 
-			const root = new RootElement( this );
-			this.roots.set( name, root );
+			let changes = operation._execute();
 
-			return root;
+			this.version++;
+
+			const batch = operation.delta && operation.delta.batch;
+			this.fire( 'change', operation.type, changes, batch );
 		}
 
 		/**
-		 * Returns top-level root by it's name.
+		 * Creates a {@link treeModel.Batch} instance which allows to change the document.
 		 *
-		 * @param {String|Symbol} name Name of the root to get.
-		 * @returns {treeModel.RootElement} Root registered under given name.
+		 * @returns {treeModel.Batch} Batch instance.
 		 */
-		getRoot( name ) {
-			if ( !this.roots.has( name ) ) {
+		batch() {
+			return new Batch( this );
+		}
+
+		/**
+		 * Creates a new top-level root.
+		 *
+		 * @param {String|Symbol} name Unique root name.
+		 * @returns {treeModel.RootElement} Created root.
+		 */
+		createRoot( name ) {
+			if ( this.roots.has( name ) ) {
 				/**
-				 * Root with specified name does not exist.
+				 * Root with specified name already exists.
 				 *
-				 * @error document-createRoot-root-not-exist
+				 * @error document-createRoot-name-exists
+				 * @param {treeModel.Document} doc
 				 * @param {String} name
 				 */
 				throw new CKEditorError(
-					'document-createRoot-root-not-exist: Root with specified name does not exist.',
+					'document-createRoot-name-exists: Root with specified name already exists.',
 					{ name: name }
 				);
 			}
 
-			return this.roots.get( name );
-		}
-
-		/**
-		 * Graveyard tree root. Document always have a graveyard root, which stores removed nodes.
-		 *
-		 * @readonly
-		 * @property {treeModel.RootElement} graveyard
-		 */
-		get graveyard() {
-			return this.getRoot( graveyardSymbol );
-		}
+			const root = new RootElement( this );
+			this.roots.set( name, root );
 
-		/**
-		 * Creates a {@link treeModel.Batch} instance which allows to change the document.
-		 *
-		 * @returns {treeModel.Batch} Batch instance.
-		 */
-		batch() {
-			return new Batch( this );
+			return root;
 		}
 
 		/**
-		 * Enqueue document changes. All document changes should be done in the enqueued callback. If no other plugin is changing document
-		 * this callback will ba called immediately. Otherwise it will be called after all enqueued changes, so it will not interrupt other
-		 * plugins.
+		 * Enqueue a callback with document changes. Any changes to be done on document (mostly using {@link #batch} should
+		 * be placed in the queued callback. If no other plugin is changing document at the moment, the callback will be
+		 * called immediately. Otherwise it will wait for all previously queued changes to finish happening. This way
+		 * queued callback will not interrupt other callbacks.
 		 *
-		 * When all enqueued changes are done {@link #changesDone} event is fired.
+		 * When all queued changes are done {@link #changesDone} event is fired.
 		 *
-		 * @param callback
+		 * @param {Function} callback Callback to enqueue.
 		 */
 		enqueueChanges( callback ) {
 			let pendingChanges = this._pendingChanges;
@@ -159,33 +167,26 @@ CKEDITOR.define( [
 		}
 
 		/**
-		 * This is the entry point for all document changes. All changes on the document are done using
-		 * {@link treeModel.operation.Operation operations}. To create operations in the simple way use the
-		 * {@link treeModel.Batch} API available via {@link #batch} method.
-		 *
-		 * This method calls {@link #change} event.
+		 * Returns top-level root by it's name.
 		 *
-		 * @param {treeModel.operation.Operation} operation Operation to be applied.
+		 * @param {String|Symbol} name Name of the root to get.
+		 * @returns {treeModel.RootElement} Root registered under given name.
 		 */
-		applyOperation( operation ) {
-			if ( operation.baseVersion !== this.version ) {
+		getRoot( name ) {
+			if ( !this.roots.has( name ) ) {
 				/**
-				 * Only operations with matching versions can be applied.
+				 * Root with specified name does not exist.
 				 *
-				 * @error document-applyOperation-wrong-version
-				 * @param {treeModel.operation.Operation} operation
+				 * @error document-createRoot-root-not-exist
+				 * @param {String} name
 				 */
 				throw new CKEditorError(
-					'document-applyOperation-wrong-version: Only operations with matching versions can be applied.',
-					{ operation: operation } );
+					'document-createRoot-root-not-exist: Root with specified name does not exist.',
+					{ name: name }
+				);
 			}
 
-			let changes = operation._execute();
-
-			this.version++;
-
-			const batch = operation.delta && operation.delta.batch;
-			this.fire( 'change', operation.type, changes, batch );
+			return this.roots.get( name );
 		}
 
 		/**
@@ -217,7 +218,7 @@ CKEDITOR.define( [
 		 */
 
 		/**
-		 * Fired when all document changes are done. See {@link #enqueueChanges}.
+		 * Fired when all queued document changes are done. See {@link #enqueueChanges}.
 		 *
 		 * @event changesDone
 		 */