Browse Source

Docs: Engine view renderer API docs corrected. [skip ci]

Anna Tomanek 7 years ago
parent
commit
592431c68e
1 changed files with 49 additions and 49 deletions
  1. 49 49
      packages/ckeditor5-engine/src/view/renderer.js

+ 49 - 49
packages/ckeditor5-engine/src/view/renderer.js

@@ -118,7 +118,7 @@ export default class Renderer {
 	/**
 	 * Marks a view node to be updated in the DOM by {@link #render `render()`}.
 	 *
-	 * Note that only view nodes which parents have corresponding DOM elements need to be marked to be synchronized.
+	 * Note that only view nodes whose parents have corresponding DOM elements need to be marked to be synchronized.
 	 *
 	 * @see #markedAttributes
 	 * @see #markedChildren
@@ -163,7 +163,7 @@ export default class Renderer {
 	 *
 	 * Renderer also handles {@link module:engine/view/filler fillers}. Especially, it checks if the inline filler is needed
 	 * at the selection position and adds or removes it. To prevent breaking text composition inline filler will not be
-	 * removed as long selection is in the text node which needed it at first.
+	 * removed as long as the selection is in the text node which needed it at first.
 	 */
 	render() {
 		let inlineFillerPosition;
@@ -237,14 +237,14 @@ export default class Renderer {
 	}
 
 	/**
-	 * Updates mappings of `viewElement`'s children.
+	 * Updates mappings of view element's children.
 	 *
-	 * Children which were replaced in the view structure by similar elements (same tag name) are treated as 'replaced'.
-	 * This means that we can update their mappings so the new view elements are mapped to the existing DOM elements.
-	 * Thanks to that we won't need to re-render these elements completely.
+	 * Children that were replaced in the view structure by similar elements (same tag name) are treated as 'replaced'.
+	 * This means that their mappings can be updated so the new view elements are mapped to the existing DOM elements.
+	 * Thanks to that these elements do not need to be re-rendered completely.
 	 *
 	 * @private
-	 * @param {module:engine/view/node~Node} viewElement The view element which children mappings will be updated.
+	 * @param {module:engine/view/node~Node} viewElement The view element whose children mappings will be updated.
 	 */
 	_updateChildrenMappings( viewElement ) {
 		const domElement = this.domConverter.mapViewToDom( viewElement );
@@ -283,11 +283,11 @@ export default class Renderer {
 	}
 
 	/**
-	 * Updates mappings of a given `viewElement`.
+	 * Updates mappings of a given view element.
 	 *
 	 * @private
-	 * @param {module:engine/view/node~Node} viewElement The view element which mappings will be updated.
-	 * @param {Node} domElement The DOM element representing given view element.
+	 * @param {module:engine/view/node~Node} viewElement The view element whose mappings will be updated.
+	 * @param {Node} domElement The DOM element representing the given view element.
 	 */
 	_updateElementMappings( viewElement, domElement ) {
 		// Because we replace new view element mapping with the existing one, the corresponding DOM element
@@ -315,16 +315,16 @@ export default class Renderer {
 	}
 
 	/**
-	 * Adds inline filler at given position.
+	 * Adds inline filler at a given position.
 	 *
 	 * The position can be given as an array of DOM nodes and an offset in that array,
-	 * or a DOM parent element and offset in that element.
+	 * or a DOM parent element and an offset in that element.
 	 *
 	 * @private
 	 * @param {Document} domDocument
 	 * @param {Element|Array.<Node>} domParentOrArray
 	 * @param {Number} offset
-	 * @returns {Text} The DOM text node that contains inline filler.
+	 * @returns {Text} The DOM text node that contains an inline filler.
 	 */
 	_addInlineFiller( domDocument, domParentOrArray, offset ) {
 		const childNodes = domParentOrArray instanceof Array ? domParentOrArray : domParentOrArray.childNodes;
@@ -350,11 +350,11 @@ export default class Renderer {
 	/**
 	 * Gets the position of the inline filler based on the current selection.
 	 * Here, we assume that we know that the filler is needed and
-	 * {@link #_isSelectionInInlineFiller is at the selection position}, and, since it's needed,
-	 * it's somewhere at the selection postion.
+	 * {@link #_isSelectionInInlineFiller is at the selection position}, and, since it is needed,
+	 * it is somewhere at the selection position.
 	 *
-	 * Note: we cannot restore the filler position based on the filler's DOM text node, because
-	 * when this method is called (before rendering) the bindings will often be broken. View to DOM
+	 * Note: The filler position cannot be restored based on the filler's DOM text node, because
+	 * when this method is called (before rendering), the bindings will often be broken. View-to-DOM
 	 * bindings are only dependable after rendering.
 	 *
 	 * @private
@@ -371,12 +371,12 @@ export default class Renderer {
 	}
 
 	/**
-	 * Returns `true` if the selection hasn't left the inline filler's text node.
-	 * If it is `true` it means that the filler had been added for a reason and the selection does not
-	 * left the filler's text node. E.g. the user can be in the middle of a composition so it should not be touched.
+	 * Returns `true` if the selection has not left the inline filler's text node.
+	 * If it is `true`, it means that the filler had been added for a reason and the selection did not
+	 * leave the filler's text node. For example, the user can be in the middle of a composition so it should not be touched.
 	 *
 	 * @private
-	 * @returns {Boolean} True if the inline filler and selection are in the same place.
+	 * @returns {Boolean} `true` if the inline filler and selection are in the same place.
 	 */
 	_isSelectionInInlineFiller() {
 		if ( this.selection.rangeCount != 1 || !this.selection.isCollapsed ) {
@@ -434,7 +434,7 @@ export default class Renderer {
 	 * Checks if the inline {@link module:engine/view/filler filler} should be added.
 	 *
 	 * @private
-	 * @returns {Boolean} True if the inline fillers should be added.
+	 * @returns {Boolean} `true` if the inline filler should be added.
 	 */
 	_needsInlineFillerAtSelection() {
 		if ( this.selection.rangeCount != 1 || !this.selection.isCollapsed ) {
@@ -481,7 +481,7 @@ export default class Renderer {
 	 * @private
 	 * @param {module:engine/view/text~Text} viewText View text to update.
 	 * @param {Object} options
-	 * @param {module:engine/view/position~Position} options.inlineFillerPosition The position on which the inline
+	 * @param {module:engine/view/position~Position} options.inlineFillerPosition The position where the inline
 	 * filler should be rendered.
 	 */
 	_updateText( viewText, options ) {
@@ -511,7 +511,7 @@ export default class Renderer {
 	}
 
 	/**
-	 * Checks if attributes list needs to be updated and possibly updates it.
+	 * Checks if attribute list needs to be updated and possibly updates it.
 	 *
 	 * @private
 	 * @param {module:engine/view/element~Element} viewElement The view element to update.
@@ -549,7 +549,7 @@ export default class Renderer {
 	 * @private
 	 * @param {module:engine/view/element~Element} viewElement View element to update.
 	 * @param {Object} options
-	 * @param {module:engine/view/position~Position} options.inlineFillerPosition The position on which the inline
+	 * @param {module:engine/view/position~Position} options.inlineFillerPosition The position where the inline
 	 * filler should be rendered.
 	 */
 	_updateChildren( viewElement, options ) {
@@ -595,17 +595,17 @@ export default class Renderer {
 	}
 
 	/**
-	 * Compares `viewElement`'s actual and expected children and returns actions sequence which can be used to transform
+	 * Compares view element's actual and expected children and returns an action sequence which can be used to transform
 	 * actual children into expected ones.
 	 *
 	 * @private
-	 * @param {module:engine/view/node~Node} viewElement The view element which children will be compared.
-	 * @param {module:engine/view/position~Position} [inlineFillerPosition=null] The position on which the inline
+	 * @param {module:engine/view/node~Node} viewElement The view element whose children will be compared.
+	 * @param {module:engine/view/position~Position} [inlineFillerPosition=null] The position where the inline
 	 * filler should be rendered.
 	 * @returns {Object|null} result
 	 * @returns {Array.<String>} result.actions List of actions based on {@link module:utils/diff~diff} function.
-	 * @returns {Array.<Node>} result.actualDomChildren Current `viewElement`'s DOM children.
-	 * @returns {Array.<Node>} result.expectedDomChildren Expected `viewElement`'s DOM children.
+	 * @returns {Array.<Node>} result.actualDomChildren Current view element's DOM children.
+	 * @returns {Array.<Node>} result.expectedDomChildren Expected view element's DOM children.
 	 */
 	_diffChildren( viewElement, inlineFillerPosition = null ) {
 		const domElement = this.domConverter.mapViewToDom( viewElement );
@@ -621,15 +621,15 @@ export default class Renderer {
 	}
 
 	/**
-	 * Returns expected DOM children for a given `viewElement`.
+	 * Returns expected DOM children for a given view element.
 	 *
 	 * @private
-	 * @param {module:engine/view/node~Node} viewElement View element which children will be returned.
-	 * @param {Node} domElement DOM representation of a given view element.
-	 * @param {Object} options See {@link module:engine/view/domconverter~DomConverter#viewToDom} options parameter.
-	 * @param {module:engine/view/position~Position} [options.inlineFillerPosition=null] The position on which
+	 * @param {module:engine/view/node~Node} viewElement View element whose children will be returned.
+	 * @param {Node} domElement The DOM representation of a given view element.
+	 * @param {Object} options See the {@link module:engine/view/domconverter~DomConverter#viewToDom} options parameter.
+	 * @param {module:engine/view/position~Position} [options.inlineFillerPosition=null] The position where
 	 * the inline filler should be rendered.
-	 * @returns {Array.<Node>} The `viewElement`'s expected children.
+	 * @returns {Array.<Node>} The view element's expected children.
 	 */
 	_getElementExpectedChildren( viewElement, domElement, options ) {
 		const expectedDomChildren = Array.from( this.domConverter.viewChildrenToDom( viewElement, domElement.ownerDocument, options ) );
@@ -646,7 +646,7 @@ export default class Renderer {
 	}
 
 	/**
-	 * Finds DOM nodes which were replaced with the similar nodes (same tag name) in the view. All nodes are compared
+	 * Finds DOM nodes that were replaced with the similar nodes (same tag name) in the view. All nodes are compared
 	 * within one `insert`/`delete` action group, for example:
 	 *
 	 * 		Actual DOM:		<p><b>Foo</b>Bar<i>Baz</i><b>Bax</b></p>
@@ -655,10 +655,10 @@ export default class Renderer {
 	 * 		Output actions:	[ insert, replace, delete, equal, replace ]
 	 *
 	 * @private
-	 * @param {Array.<String>} actions Actions array which is result of {@link module:utils/diff~diff} function.
+	 * @param {Array.<String>} actions Actions array which is a result of the {@link module:utils/diff~diff} function.
 	 * @param {Array.<Node>} actualDom Actual DOM children
 	 * @param {Array.<Node>} expectedDom Expected DOM children.
-	 * @returns {Array.<String>} Actions array modified with `replace` actions.
+	 * @returns {Array.<String>} Actions array modified with the `replace` actions.
 	 */
 	_findReplaceActions( actions, actualDom, expectedDom ) {
 		// If there is no both 'insert' and 'delete' actions, no need to check for replaced elements.
@@ -691,7 +691,7 @@ export default class Renderer {
 	}
 
 	/**
-	 * Marks text nodes to be synced.
+	 * Marks text nodes to be synchronized.
 	 *
 	 * If a text node is passed, it will be marked. If an element is passed, all descendant text nodes inside it will be marked.
 	 *
@@ -713,7 +713,7 @@ export default class Renderer {
 	}
 
 	/**
-	 * Checks if selection needs to be updated and possibly updates it.
+	 * Checks if the selection needs to be updated and possibly updates it.
 	 *
 	 * @private
 	 */
@@ -743,10 +743,10 @@ export default class Renderer {
 	}
 
 	/**
-	 * Updates fake selection.
+	 * Updates the fake selection.
 	 *
 	 * @private
-	 * @param {HTMLElement} domRoot Valid DOM root where fake selection container should be added.
+	 * @param {HTMLElement} domRoot A valid DOM root where the fake selection container should be added.
 	 */
 	_updateFakeSelection( domRoot ) {
 		const domDocument = domRoot.ownerDocument;
@@ -789,10 +789,10 @@ export default class Renderer {
 	}
 
 	/**
-	 * Updates DOM selection.
+	 * Updates the DOM selection.
 	 *
 	 * @private
-	 * @param {HTMLElement} domRoot Valid DOM root where DOM selection should be rendered.
+	 * @param {HTMLElement} domRoot A valid DOM root where the DOM selection should be rendered.
 	 */
 	_updateDomSelection( domRoot ) {
 		const domSelection = domRoot.ownerDocument.defaultView.getSelection();
@@ -819,10 +819,10 @@ export default class Renderer {
 	}
 
 	/**
-	 * Checks whether given DOM selection needs to be updated.
+	 * Checks whether a given DOM selection needs to be updated.
 	 *
 	 * @private
-	 * @param {Selection} domSelection DOM selection to check.
+	 * @param {Selection} domSelection The DOM selection to check.
 	 * @returns {Boolean}
 	 */
 	_domSelectionNeedsUpdate( domSelection ) {
@@ -848,7 +848,7 @@ export default class Renderer {
 	}
 
 	/**
-	 * Removes DOM selection.
+	 * Removes the DOM selection.
 	 *
 	 * @private
 	 */
@@ -868,7 +868,7 @@ export default class Renderer {
 	}
 
 	/**
-	 * Removes fake selection.
+	 * Removes the fake selection.
 	 *
 	 * @private
 	 */