Browse Source

Moar API docs corrections.

Piotrek Koszuliński 9 năm trước cách đây
mục cha
commit
38e35ae992

+ 33 - 28
packages/ckeditor5-engine/src/treeview/domconverter.js

@@ -42,6 +42,17 @@ export default class DomConverter {
 		// Yes, PJ. It is.
 		//
 		// You guys so smart.
+		//
+		// I've been here. Seen stuff. Afraid of code now.
+
+		/**
+		 * Block {@link engine.treeView.filler filler} creator, which is used to create all block fillers during the
+		 * view to DOM conversion and to recognize block fillers during the DOM to view conversion.
+		 *
+		 * @readonly
+		 * @member {Function} engine.treeView.DomConverter#blockFiller
+		 */
+		this.blockFiller = options.blockFiller || BR_FILLER;
 
 		/**
 		 * DOM to View mapping.
@@ -58,14 +69,6 @@ export default class DomConverter {
 		 * @member {WeakMap} engine.treeView.DomConverter#_viewToDomMapping
 		 */
 		this._viewToDomMapping = new WeakMap();
-
-		/**
-		 * Block {@link engine.treeView.filler filler} creator, which is used to create all block fillers during the
-		 * view to DOM conversion and to recognize block fillers during the DOM to view conversion.
-		 *
-		 * @member {Function} engine.treeView.DomConverter#blockFiller
-		 */
-		this.blockFiller = options.blockFiller || BR_FILLER;
 	}
 
 	/**
@@ -215,7 +218,8 @@ export default class DomConverter {
 			}
 
 			return { parent: domParent, offset: offset };
-		} // instanceof HTMLElement
+		}
+		// viewParent instance of ViewElement.
 		else {
 			let domParent, domBefore, domAfter;
 
@@ -243,7 +247,7 @@ export default class DomConverter {
 	/**
 	 * Converts DOM to view. For all text nodes, not bound elements and document fragments new items will
 	 * be created. For bound elements and document fragments function will return corresponding items. For
-	 * {@link engine.treeView.filler fillers} null will be returned.
+	 * {@link engine.treeView.filler fillers} `null` will be returned.
 	 *
 	 * @param {Node|DocumentFragment} domNode DOM node or document fragment to transform.
 	 * @param {Object} [options] Conversion options.
@@ -305,7 +309,7 @@ export default class DomConverter {
 
 	/**
 	 * Converts children of the DOM element to view nodes using {@link engine.treeView.DomConverter#domToView} method.
-	 * Additionally this method omit block {@link engine.treeView.filler filler}, if it exists in the DOM parent.
+	 * Additionally this method omits block {@link engine.treeView.filler filler}, if it exists in the DOM parent.
 	 *
 	 * @param {HTMLElement} domElement Parent DOM element.
 	 * @param {Object} options See {@link engine.treeView.DomConverter#domToView} options parameter.
@@ -324,7 +328,7 @@ export default class DomConverter {
 
 	/**
 	 * Converts DOM selection to view {@link engine.treeView.Selection}.
-	 * Ranges which can not be converted will be omitted.
+	 * Ranges which cannot be converted will be omitted.
 	 *
 	 * @param {Selection} domSelection DOM selection.
 	 * @returns {engine.treeView.Selection} View selection.
@@ -346,7 +350,7 @@ export default class DomConverter {
 
 	/**
 	 * Converts DOM Range to view {@link engine.treeView.range}.
-	 * If the start or end position can not be converted null is returned.
+	 * If the start or end position can not be converted `null` is returned.
 	 *
 	 * @param {Range} domRange DOM range.
 	 * @returns {engine.treeView.Range|null} View range.
@@ -368,7 +372,7 @@ export default class DomConverter {
 	 * If the position is inside a {@link engine.treeView.filler filler} which has no corresponding view node,
 	 * position of the filler will be converted and returned.
 	 *
-	 * If structures are too different and it is not possible to find corresponding position then null will be returned.
+	 * If structures are too different and it is not possible to find corresponding position then `null` will be returned.
 	 *
 	 * @param {Node} domParent DOM position parent.
 	 * @param {Number} domOffset DOM position offset.
@@ -397,7 +401,8 @@ export default class DomConverter {
 			}
 
 			return new ViewPosition( viewParent, offset );
-		} // domParent instanceof HTMLElement
+		}
+		// domParent instanceof HTMLElement.
 		else {
 			if ( domOffset === 0 ) {
 				const viewParent = this.getCorrespondingView( domParent );
@@ -424,7 +429,7 @@ export default class DomConverter {
 	 * nodes and {@link engine.treeView.DomConverter#getCorrespondingViewDocumentFragment getCorrespondingViewDocumentFragment}
 	 * for document fragments.
 	 *
-	 * Note that for the block or inline {@link engine.treeView.filler filler} this method returns null.
+	 * Note that for the block or inline {@link engine.treeView.filler filler} this method returns `null`.
 	 *
 	 * @param {Node|DocumentFragment} domNode DOM node or document fragment.
 	 * @returns {engine.treeView.Node|engine.treeView.DocumentFragment|null} Corresponding view item.
@@ -443,10 +448,10 @@ export default class DomConverter {
 
 	/**
 	 * Gets corresponding view element. Returns element if an view element was
-	 * {@link engine.treeView.DomConverter#bindElements bound} to the given DOM element or null otherwise.
+	 * {@link engine.treeView.DomConverter#bindElements bound} to the given DOM element or `null` otherwise.
 	 *
 	 * @param {HTMLElement} domElement DOM element.
-	 * @returns {engine.treeView.Element|null} Corresponding element or null if no element was bound.
+	 * @returns {engine.treeView.Element|null} Corresponding element or `null` if no element was bound.
 	 */
 	getCorrespondingViewElement( domElement ) {
 		return this._domToViewMapping.get( domElement );
@@ -454,10 +459,10 @@ export default class DomConverter {
 
 	/**
 	 * Gets corresponding view document fragment. Returns document fragment if an view element was
-	 * {@link engine.treeView.DomConverter#bindDocumentFragments bound} to the given DOM fragment or null otherwise.
+	 * {@link engine.treeView.DomConverter#bindDocumentFragments bound} to the given DOM fragment or `null` otherwise.
 	 *
 	 * @param {DocumentFragment} domFragment DOM element.
-	 * @returns {engine.treeView.DocumentFragment|null} Corresponding document fragment or null if none element was bound.
+	 * @returns {engine.treeView.DocumentFragment|null} Corresponding document fragment or `null` if none element was bound.
 	 */
 	getCorrespondingViewDocumentFragment( domFragment ) {
 		return this._domToViewMapping.get( domFragment );
@@ -475,10 +480,10 @@ export default class DomConverter {
 	 *
 	 * Otherwise `null` is returned.
 	 *
-	 * Note that for the block or inline {@link engine.treeView.filler filler} this method returns null.
+	 * Note that for the block or inline {@link engine.treeView.filler filler} this method returns `null`.
 	 *
 	 * @param {Text} domText DOM text node.
-	 * @returns {engine.treeView.Text|null} Corresponding view text node or null, if it was not possible to find a
+	 * @returns {engine.treeView.Text|null} Corresponding view text node or `null`, if it was not possible to find a
 	 * corresponding node.
 	 */
 	getCorrespondingViewText( domText ) {
@@ -549,10 +554,10 @@ export default class DomConverter {
 
 	/**
 	 * Gets corresponding DOM element. Returns element if an DOM element was
-	 * {@link engine.treeView.DomConverter#bindElements bound} to the given view element or null otherwise.
+	 * {@link engine.treeView.DomConverter#bindElements bound} to the given view element or `null` otherwise.
 	 *
 	 * @param {engine.treeView.Element} viewElement View element.
-	 * @returns {HTMLElement|null} Corresponding element or null if none element was bound.
+	 * @returns {HTMLElement|null} Corresponding element or `null` if none element was bound.
 	 */
 	getCorrespondingDomElement( viewElement ) {
 		return this._viewToDomMapping.get( viewElement );
@@ -560,10 +565,10 @@ export default class DomConverter {
 
 	/**
 	 * Gets corresponding DOM document fragment. Returns document fragment if an DOM element was
-	 * {@link engine.treeView.DomConverter#bindDocumentFragments bound} to the given view document fragment or null otherwise.
+	 * {@link engine.treeView.DomConverter#bindDocumentFragments bound} to the given view document fragment or `null` otherwise.
 	 *
 	 * @param {engine.treeView.DocumentFragment} viewDocumentFragment View document fragment.
-	 * @returns {DocumentFragment|null} Corresponding document fragment or null if no fragment was bound.
+	 * @returns {DocumentFragment|null} Corresponding document fragment or `null` if no fragment was bound.
 	 */
 	getCorrespondingDomDocumentFragment( viewDocumentFragment ) {
 		return this._viewToDomMapping.get( viewDocumentFragment );
@@ -579,10 +584,10 @@ export default class DomConverter {
 	 * If this is a first child in the parent and the parent is a {@link engine.treeView.DomConverter#bindElements bound}
 	 * element, it is used to find the corresponding text node.
 	 *
-	 * Otherwise null is returned.
+	 * Otherwise `null` is returned.
 	 *
 	 * @param {engine.treeView.Text} viewText View text node.
-	 * @returns {Text|null} Corresponding DOM text node or null, if it was not possible to find a corresponding node.
+	 * @returns {Text|null} Corresponding DOM text node or `null`, if it was not possible to find a corresponding node.
 	 */
 	getCorrespondingDomText( viewText ) {
 		const previousSibling = viewText.getPreviousSibling();

+ 28 - 26
packages/ckeditor5-engine/src/treeview/renderer.js

@@ -16,16 +16,17 @@ import remove from '../../utils/dom/remove.js';
 import CKEditorError from '../../utils/ckeditorerror.js';
 
 /**
- * Renderer updates DOM tree and selection, to make it a reflection of the view tree and selection.
+ * Renderer updates DOM structure and selection, to make them a reflection of the view structure and selection.
  *
- * Changed nodes need to be {@link engine.treeView.Renderer#markToSync marked} to be rendered.
- * Then, on {@link engine.treeView.Renderer#render render}, renderer ensure they need to be refreshed and creates DOM
- * nodes from view nodes, {@link engine.treeView.DomConverter#bindElements bind} them and insert into DOM tree.
+ * View nodes which may need to be rendered needs to be {@link engine.treeView.Renderer#markToSync marked}.
+ * Then, on {@link engine.treeView.Renderer#render render}, renderer compares the view nodes with the DOM nodes
+ * in order to check which ones really need to be refreshed. Finally, it creates DOM nodes from these view nodes,
+ * {@link engine.treeView.DomConverter#bindElements binds} them and inserts into the DOM tree.
  *
- * Every time {@link engine.treeView.Renderer#render render} is called, Renderer additionally check if
- * {@link engine.treeView.Renderer#selection selection} needs update and update it if so.
+ * Every time {@link engine.treeView.Renderer#render render} is called, renderer additionally checks if
+ * {@link engine.treeView.Renderer#selection selection} needs update and updates it if so.
  *
- * Renderer use {@link engine.treeView.DomConverter} to transform and bind nodes.
+ * Renderer uses {@link engine.treeView.DomConverter} to transform and bind nodes.
  *
  * @memberOf engine.treeView
  */
@@ -70,7 +71,7 @@ export default class Renderer {
 		this.markedTexts = new Set();
 
 		/**
-		 * View selection. Renderer updates DOM Selection to make it match this.
+		 * View selection. Renderer updates DOM Selection to make it match this one.
 		 *
 		 * @readonly
 		 * @member {engine.treeView.Selection} engine.treeView.Renderer#selection
@@ -89,8 +90,8 @@ export default class Renderer {
 		/**
 		 * Last DOM selection object.
 		 *
-		 * Because renderer handle multiple roots, and because these roots might be in different documents (in case of
-		 * using iframes) renderer need to keep last DOM selection object to remove ranges from it before new selection
+		 * Because renderer handles multiple roots, and because these roots might be in different documents (in case of
+		 * using `iframes`) renderer needs to keep last DOM selection object to remove ranges from it before new selection
 		 * is rendered.
 		 *
 		 * @private
@@ -140,25 +141,26 @@ export default class Renderer {
 
 	/**
 	 * Render method checks {@link engine.treeView.Renderer#markedAttributes},
-	 * {@link engine.treeView.Renderer#markedChildren} and {@link engine.treeView.Renderer#markedTexts} and updated all
-	 * nodes which needs to be updated. Then it clear all three sets. Every time render is called additionally selection
-	 * is compared and updated if needed.
+	 * {@link engine.treeView.Renderer#markedChildren} and {@link engine.treeView.Renderer#markedTexts} and updats all
+	 * nodes which need to be updated. Then it clears all three sets. Also, every time render is called it compares and
+	 * if needed updates the selection.
 	 *
-	 * Renderer try not to break IME and x-index of the selection, so it do as little as it is needed to update DOM.
+	 * Renderer tries not to break text composition (e.g. IME) and x-index of the selection,
+	 * so it does as little as it is needed to update the DOM.
 	 *
-	 * For attributes it adds new attributes to DOM elements, update attributes with different values and remove
-	 * attributes which does not exists in the view element.
+	 * For attributes it adds new attributes to DOM elements, updates values and removes
+	 * attributes which do not exist in the view element.
 	 *
-	 * For text nodes it update the text string if it is different. Note that if parent element is marked as an element
+	 * For text nodes it updates the text string if it is different. Note that if parent element is marked as an element
 	 * which changed child list, text node update will not be done, because it may not be possible do find a
 	 * {@link engine.treeView.DomConverter#getCorrespondingDomText corresponding DOM text}. The change will be handled
 	 * in the parent element.
 	 *
-	 * For nodes, which changed child list, it calculates a {@link diff} and add or removed nodes which changed.
+	 * For elements, which child lists have changed, it calculates a {@link diff} and adds or removs children which have changed.
 	 *
-	 * Rendering also handle {@link engine.treeView.filler fillers}. Especially it check if the inline filler is needed
-	 * at selection position and add or remove it. To prevent breaking IME inline filler will not be removed as long
-	 * selection is in the text node which needed it at first.
+	 * Rendering also handles {@link engine.treeView.filler fillers}. Especially, it checks if the inline filler is needed
+	 * at 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.
 	 */
 	render() {
 		if ( !this._isInlineFillerAtSelection() ) {
@@ -194,7 +196,7 @@ export default class Renderer {
 	}
 
 	/**
-	 * Returns true if the inline filler and selection are in the same place.
+	 * Returns `true` if the inline filler and selection are in the same place.
 	 * If it is true it means filler had been added for a reason and selection does not
 	 * left text node, user can be in the middle of the composition so it should not be touched.
 	 *
@@ -292,7 +294,7 @@ export default class Renderer {
 	}
 
 	/**
-	 * Checks if text needs updated and possibly updates it.
+	 * Checks if text needs to be updated and possibly updates it.
 	 *
 	 * @private
 	 * @param {engine.treeView.Text} viewText View text to update.
@@ -315,7 +317,7 @@ export default class Renderer {
 	}
 
 	/**
-	 * Checks if attributes list needs updated and possibly updates it.
+	 * Checks if attributes list needs to be updated and possibly updates it.
 	 *
 	 * @private
 	 * @param {engine.treeView.Element} viewElement View element to update.
@@ -339,7 +341,7 @@ export default class Renderer {
 	}
 
 	/**
-	 * Checks if elements child list needs updated and possibly updates it.
+	 * Checks if elements child list needs to be updated and possibly updates it.
 	 *
 	 * @private
 	 * @param {engine.treeView.Element} viewElement View element to update.
@@ -400,7 +402,7 @@ export default class Renderer {
 	}
 
 	/**
-	 * Checks if selection needs updated and possibly updates it.
+	 * Checks if selection needs to be updated and possibly updates it.
 	 *
 	 * @private
 	 */