Browse Source

Docs: Document API docs revised. [skip ci]

Anna Tomanek 7 years ago
parent
commit
223a6dcea8
1 changed files with 48 additions and 48 deletions
  1. 48 48
      packages/ckeditor5-engine/src/model/document.js

+ 48 - 48
packages/ckeditor5-engine/src/model/document.js

@@ -24,8 +24,8 @@ const graveyardName = '$graveyard';
 
 /**
  * Document tree model describes all editable data in the editor. It may contain multiple
- * {@link module:engine/model/document~Document#roots root elements}, for example if the editor have multiple editable areas,
- * each area will be represented by the separate root.
+ * {@link module:engine/model/document~Document#roots root elements}. For example, if the editor has multiple editable areas,
+ * each area will be represented by a separate root.
  *
  * @mixes module:utils/emittermixin~EmitterMixin
  */
@@ -36,7 +36,7 @@ export default class Document {
 	 */
 	constructor( model ) {
 		/**
-		 * {@link module:engine/model/model~Model} the document is part of.
+		 * The {@link module:engine/model/model~Model model} that the document is a part of.
 		 *
 		 * @readonly
 		 * @member {module:engine/model/model~Model}
@@ -44,10 +44,10 @@ export default class Document {
 		this.model = model;
 
 		/**
-		 * Document version. It starts from `0` and every operation increases the version number. It is used to ensure that
-		 * operations are applied on the proper document version.
-		 * If the {@link module:engine/model/operation/operation~Operation#baseVersion} will not match document version the
-		 * {@link module:utils/ckeditorerror~CKEditorError model-document-applyOperation-wrong-version} error is thrown.
+		 * The document version. It starts from `0` and every operation increases the version number. It is used to ensure that
+		 * operations are applied on a proper document version.
+		 * If the {@link module:engine/model/operation/operation~Operation#baseVersion base version} does not match the document version,
+		 * a {@link module:utils/ckeditorerror~CKEditorError model-document-applyOperation-wrong-version} error is thrown.
 		 *
 		 * @readonly
 		 * @member {Number}
@@ -55,7 +55,7 @@ export default class Document {
 		this.version = 0;
 
 		/**
-		 * Document's history.
+		 * The document's history.
 		 *
 		 * **Note:** Be aware that deltas applied to the document might get removed or changed.
 		 *
@@ -65,7 +65,7 @@ export default class Document {
 		this.history = new History( this );
 
 		/**
-		 * Selection done on this document.
+		 * The selection done on this document.
 		 *
 		 * @readonly
 		 * @member {module:engine/model/documentselection~DocumentSelection}
@@ -73,7 +73,7 @@ export default class Document {
 		this.selection = new DocumentSelection( this );
 
 		/**
-		 * List of roots that are owned and managed by this document. Use {@link #createRoot} and
+		 * A list of roots that are owned and managed by this document. Use {@link #createRoot} and
 		 * {@link #getRoot} to manipulate it.
 		 *
 		 * @readonly
@@ -82,7 +82,7 @@ export default class Document {
 		this.roots = new Collection( { idProperty: 'rootName' } );
 
 		/**
-		 * Model differ object. Its role is to buffer changes done on model document and then calculate a diff of those changes.
+		 * The model differ object. Its role is to buffer changes done on the model document and then calculate a diff of those changes.
 		 *
 		 * @readonly
 		 * @member {module:engine/model/differ~Differ}
@@ -180,7 +180,7 @@ export default class Document {
 	}
 
 	/**
-	 * Graveyard tree root. Document always have a graveyard root, which stores removed nodes.
+	 * The graveyard tree root. A document always has a graveyard root that stores removed nodes.
 	 *
 	 * @readonly
 	 * @member {module:engine/model/rootelement~RootElement}
@@ -192,16 +192,15 @@ export default class Document {
 	/**
 	 * Creates a new top-level root.
 	 *
-	 * @param {String} [elementName='$root'] Element name. Defaults to `'$root'` which also have
-	 * some basic schema defined (`$block`s are allowed inside the `$root`). Make sure to define a proper
-	 * schema if you use a different name.
-	 * @param {String} [rootName='main'] Unique root name.
-	 * @returns {module:engine/model/rootelement~RootElement} Created root.
+	 * @param {String} [elementName='$root'] The element name. Defaults to `'$root'` which also has some basic schema defined
+	 * (`$block`s are allowed inside the `$root`). Make sure to define a proper schema if you use a different name.
+	 * @param {String} [rootName='main'] A unique root name.
+	 * @returns {module:engine/model/rootelement~RootElement} The created root.
 	 */
 	createRoot( elementName = '$root', rootName = 'main' ) {
 		if ( this.roots.get( rootName ) ) {
 			/**
-			 * Root with specified name already exists.
+			 * A root with the specified name already exists.
 			 *
 			 * @error model-document-createRoot-name-exists
 			 * @param {module:engine/model/document~Document} doc
@@ -220,7 +219,7 @@ export default class Document {
 	}
 
 	/**
-	 * Removes all events listeners set by document instance.
+	 * Removes all event listeners set by the document instance.
 	 */
 	destroy() {
 		this.selection.destroy();
@@ -228,18 +227,18 @@ export default class Document {
 	}
 
 	/**
-	 * Returns top-level root by its name.
+	 * Returns the top-level root by its name.
 	 *
-	 * @param {String} [name='main'] Unique root name.
-	 * @returns {module:engine/model/rootelement~RootElement|null} Root registered under given name or null when
-	 * there is no root of given name.
+	 * @param {String} [name='main'] A unique root name.
+	 * @returns {module:engine/model/rootelement~RootElement|null} The root registered under a given name or null when
+	 * there is no root with the given name.
 	 */
 	getRoot( name = 'main' ) {
 		return this.roots.get( name );
 	}
 
 	/**
-	 * Returns array with names of all roots (without the {@link #graveyard}) added to the document.
+	 * Returns an array with names of all roots (without the {@link #graveyard}) added to the document.
 	 *
 	 * @returns {Array.<String>} Roots names.
 	 */
@@ -248,32 +247,33 @@ export default class Document {
 	}
 
 	/**
-	 * Used to register a post-fixer callback. Post-fixers mechanism guarantees that the features that listen to
-	 * {@link module:engine/model/model~Model#event:_change model's change event} will operate on a correct model state.
+	 * Used to register a post-fixer callback. A post-fixer mechanism guarantees that the features that listen to
+	 * the {@link module:engine/model/model~Model#event:_change model's change event} will operate on a correct model state.
 	 *
-	 * Execution of a feature may lead to an incorrect document tree state. The callbacks are used to fix document tree after
+	 * An execution of a feature may lead to an incorrect document tree state. The callbacks are used to fix the document tree after
 	 * it has changed. Post-fixers are fired just after all changes from the outermost change block were applied but
-	 * before {@link module:engine/model/document~Document#event:change} is fired. If a post-fixer callback made a change,
-	 * it should return `true`. When this happens, all post-fixers are fired again to check if something else should
+	 * before the {@link module:engine/model/document~Document#event:change change event} is fired. If a post-fixer callback made
+	 * a change, it should return `true`. When this happens, all post-fixers are fired again to check if something else should
 	 * not be fixed in the new document tree state.
 	 *
-	 * As a parameter, a post-fixer callback receives {@link module:engine/model/writer~Writer} instance connected with the executed
-	 * changes block. Thanks to that, all changes done by the callback will be added to the same {@link module:engine/model/batch~Batch}
-	 * (and undo step) as the original changes. This makes post-fixer changes transparent for the user.
+	 * As a parameter, a post-fixer callback receives a {@link module:engine/model/writer~Writer writer} instance connected with the
+	 * executed changes block. Thanks to that, all changes done by the callback will be added to the same
+	 * {@link module:engine/model/batch~Batch batch} (and undo step) as the original changes. This makes post-fixer changes transparent
+	 * for the user.
 	 *
-	 * An example of a post-fixer is a callback that checks if all the data was removed from the editor. If so, the
-	 * callback should add an empty paragraph, so that the editor is never empty:
+	 * An example of a post-fixer is a callback that checks if all the data were removed from the editor. If so, the
+	 * callback should add an empty paragraph so that the editor is never empty:
 	 *
 	 *		document.registerPostFixer( writer => {
 	 *			const changes = document.differ.getChanges();
 	 *
-	 *			// Check if the changes lead to an empty root in an editor.
+	 *			// Check if the changes lead to an empty root in the editor.
 	 *			for ( const entry of changes ) {
 	 *				if ( entry.type == 'remove' && entry.position.root.isEmpty ) {
 	 *					writer.insertElement( 'paragraph', entry.position.root, 0 );
 	 *
 	 *					// It is fine to return early, even if multiple roots would need to be fixed.
-	 *					// All post-fixers will be fired again, so if there more empty roots, those will be fixed too.
+	 *					// All post-fixers will be fired again, so if there are more empty roots, those will be fixed, too.
 	 *					return true;
 	 *				}
 	 *			}
@@ -286,9 +286,9 @@ export default class Document {
 	}
 
 	/**
-	 * Custom toJSON method to solve child-parent circular dependencies.
+	 * A custom `toJSON()` method to solve child-parent circular dependencies.
 	 *
-	 * @returns {Object} Clone of this object with the document property changed to string.
+	 * @returns {Object} A clone of this object with the document property changed to a string.
 	 */
 	toJSON() {
 		const json = clone( this );
@@ -301,7 +301,7 @@ export default class Document {
 	}
 
 	/**
-	 * Returns default root for this document which is either the first root that was added to the the document using
+	 * Returns the default root for this document which is either the first root that was added to the document using
 	 * {@link #createRoot} or the {@link #graveyard graveyard root} if no other roots were created.
 	 *
 	 * @protected
@@ -318,8 +318,8 @@ export default class Document {
 	}
 
 	/**
-	 * Returns a default range for this selection. The default range is a collapsed range that starts and ends
-	 * at the beginning of this selection's document's {@link #_getDefaultRoot default root}.
+	 * Returns the default range for this selection. The default range is a collapsed range that starts and ends
+	 * at the beginning of this selection's document {@link #_getDefaultRoot default root}.
 	 *
 	 * @protected
 	 * @returns {module:engine/model/range~Range}
@@ -337,11 +337,11 @@ export default class Document {
 	}
 
 	/**
-	 * Checks whether given {@link module:engine/model/range~Range range} is a valid range for
-	 * {@link #selection document's selection}.
+	 * Checks whether a given {@link module:engine/model/range~Range range} is a valid range for
+	 * the {@link #selection document's selection}.
 	 *
 	 * @private
-	 * @param {module:engine/model/range~Range} range Range to check.
+	 * @param {module:engine/model/range~Range} range A range to check.
 	 * @returns {Boolean} `true` if `range` is valid, `false` otherwise.
 	 */
 	_validateSelectionRange( range ) {
@@ -349,7 +349,7 @@ export default class Document {
 	}
 
 	/**
-	 * Performs post-fixer loops. Executes post-fixer callbacks as long as neither of them has done any changes to model.
+	 * Performs post-fixer loops. Executes post-fixer callbacks as long as none of them has done any changes to the model.
 	 *
 	 * @private
 	 */
@@ -368,12 +368,12 @@ export default class Document {
 	}
 
 	/**
-	 * Fired after an {@link module:engine/model/model~Model#enqueueChange enqueueChange block} or the outermost
-	 * {@link module:engine/model/model~Model#change change block} has been executed and the document model tree was changed
+	 * Fired after an {@link module:engine/model/model~Model#enqueueChange enqueue change block} or the outermost
+	 * {@link module:engine/model/model~Model#change change block} was executed and the document model tree was changed
 	 * during that block execution.
 	 *
 	 * @event change
-	 * @param {@link module:engine/model/batch~Batch} batch Batch which was used in the executed changes block.
+	 * @param {@link module:engine/model/batch~Batch} batch The batch that was used in the executed changes block.
 	 */
 }