8
0
Просмотр исходного кода

Even moar API docs corrections.

Piotrek Koszuliński 9 лет назад
Родитель
Сommit
87cb32f8de

+ 12 - 10
packages/ckeditor5-engine/src/treeview/observer/selectionobserver.js

@@ -9,13 +9,13 @@ import Observer from './observer.js';
 import MutationObserver from './mutationobserver.js';
 
 /**
- * Selection observer class observes selection changes in the document. If selection change on the document this
- * observer checks if there are any mutations and if DOM selection is different then the
+ * Selection observer class observes selection changes in the document. If selection changes on the document this
+ * observer checks if there are any mutations and if DOM selection is different than the
  * {@link engine.treeView.TreeView#selection view selection}. Selection observer fires
  * {@link engine.treeView.TreeView#selectionchange} event only if selection change was the only change in the document
- * and DOM selection is different then view selection.
+ * and DOM selection is different then the view selection.
  *
- * @see  engine.treeView.MutationObserver
+ * @see engine.treeView.MutationObserver
  * @memberOf engine.treeView.observer
  * @extends engine.treeView.observer.Observer
  */
@@ -25,9 +25,10 @@ export default class SelectionObserver extends Observer {
 
 		/**
 		 * Instance of the mutation observer. Selection observer calls
-		 * {@link engine.treeView.observer.MutationObserver#flush} to ensure mutations will be handled before the
-		 * {@link engine.treeView.TreeView#selectionchange} event.
+		 * {@link engine.treeView.observer.MutationObserver#flush} to ensure that the mutations will be handled before the
+		 * {@link engine.treeView.TreeView#selectionchange} event is fired.
 		 *
+		 * @readonly
 		 * @member {engine.treeView.observer.MutationObserver} engine.treeView.observer.SelectionObserver#mutationObserver
 		 */
 		this.mutationObserver = treeView.getObserver( MutationObserver );
@@ -51,6 +52,7 @@ export default class SelectionObserver extends Observer {
 		/**
 		 * Reference to the {@link engine.treeView.TreeView#domConverter}.
 		 *
+		 * @readonly
 		 * @member {engine.treeView.DomConverter} engine.treeView.observer.SelectionObserver#domConverter
 		 */
 		this.domConverter = treeView.domConverter;
@@ -96,8 +98,8 @@ export default class SelectionObserver extends Observer {
 		// Ensure the mutation event will be before selection event on all browsers.
 		this.mutationObserver.flush();
 
-		// If there were mutations then the view will be re-rendered by the mutations observer and selection
-		// will be updated, so selection will be equal and event will not be fires, as expected.
+		// If there were mutations then the view will be re-rendered by the mutation observer and selection
+		// will be updated, so selections will equal and event will not be fired, as expected.
 		const domSelection = domDocument.defaultView.getSelection();
 		const newViewSelection = this.domConverter.domSelectionToView( domSelection );
 
@@ -117,8 +119,8 @@ export default class SelectionObserver extends Observer {
 }
 
 /**
- * Fired when selection changes. This event is fired only when the selection change is the only change in the
- * document, and old selection is different then new selection.
+ * Fired when selection has changed. This event is fired only when the selection change was the only change that happened
+ * in the document, and old selection is different then the new selection.
  *
  * @event engine.treeView.TreeView#selection
  * @param {Object} data

+ 6 - 6
packages/ckeditor5-engine/src/treeview/position.js

@@ -187,15 +187,15 @@ export default class Position {
 	}
 
 	/**
-	 * Creates a new position after given node.
+	 * Creates a new position after the given node.
 	 *
-	 * @param {engine.treeView.Node} node Node the position should be directly after.
+	 * @param {engine.treeView.Node} node Node after which the position should be located.
 	 * @returns {engine.treeView.Position}
 	 */
 	static createAfter( node ) {
 		if ( !node.parent ) {
 			/**
-			 * You can not make position after root.
+			 * You can not make a position after a root.
 			 *
 			 * @error position-after-root
 			 * @param {engine.treeView.Node} root
@@ -209,13 +209,13 @@ export default class Position {
 	/**
 	 * Creates a new position before the given node.
 	 *
-	 * @param {engine.treeView.node} node Node the position should be directly before.
+	 * @param {engine.treeView.node} node Node before which the position should be located.
 	 * @returns {engine.treeView.Position}
 	 */
 	static createBefore( node ) {
 		if ( !node.parent ) {
 			/**
-			 * You can not make position before root.
+			 * You cannot make a position before a root.
 			 *
 			 * @error position-before-root
 			 * @param {engine.treeView.Node} root
@@ -227,7 +227,7 @@ export default class Position {
 	}
 
 	/**
-	 * Creates and returns a new instance of Position, which is equal to passed position.
+	 * Creates and returns a new instance of `Position`, which is equal to the passed position.
 	 *
 	 * @param {engine.treeView.Position} position Position to be cloned.
 	 * @returns {engine.treeView.Position}

+ 2 - 2
packages/ckeditor5-engine/src/treeview/selection.js

@@ -207,7 +207,7 @@ export default class Selection {
 	}
 
 	/**
-	 * Two selections equals if they have the same ranges and directions.
+	 * Two selections equal if they have the same ranges and directions.
 	 *
 	 * @param {engine.treeView.Selection} otherSelection Selection to compare with.
 	 * @returns {Boolean} True if selections equal.
@@ -263,7 +263,7 @@ export default class Selection {
 	}
 
 	/**
-	 * Set this selection ranges and direction to the ranges and direction of other selection
+	 * Set this selection's ranges and direction to the ranges and direction of the given selection.
 	 *
 	 * @param {engine.treeView.Selection} otherSelection Other selection.
 	 */

+ 3 - 4
packages/ckeditor5-engine/src/treeview/treeview.js

@@ -82,10 +82,10 @@ export default class TreeView {
 		this.renderer = new Renderer( this.domConverter, this.selection );
 
 		/**
-		 * Set of registered {@link engine.treeView.Observer observers}.
+		 * Map of registered {@link engine.treeView.Observer observers}.
 		 *
 		 * @private
-		 * @member {Set.<engine.treeView.Observer>} engine.treeView.TreeView_#observers
+		 * @member {Map.<Function, engine.treeView.Observer>} engine.treeView.TreeView_#observers
 		 */
 		this._observers = new Map();
 
@@ -105,7 +105,6 @@ export default class TreeView {
 	 *
 	 * @param {Function} Observer The constructor of an observer to add.
 	 * Should create an instance inheriting from {@link engine.treeView.observer.Observer}.
-	 *
 	 * @returns {engine.treeView.observer.Observer} Added observer instance.
 	 */
 	addObserver( Observer ) {
@@ -127,7 +126,7 @@ export default class TreeView {
 	}
 
 	/**
-	 * Get observer of given type or undefined if such observer have not been added.
+	 * Returns observer of the given type or `undefined` if such observer has not been added yet.
 	 *
 	 * @param {Function} Observer The constructor of an observer to get.
 	 * @returns {engine.treeView.observer.Observer|undefined} Observer instance or undefined.