Browse Source

Docs: API docs corrections. [skip ci]

Anna Tomanek 8 years ago
parent
commit
cd713d040c

+ 5 - 5
packages/ckeditor5-ui/src/componentfactory.js

@@ -14,9 +14,9 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  *
  * It allows functions producing specific UI components to be registered under their unique names
  * in the factory. A registered component can be then instantiated by providing its name.
- * Note that names are case-insensitive.
+ * Note that names are case insensitive.
  *
- *		// Editor provides localization tools for the factory.
+ *		// The editor provides localization tools for the factory.
  *		const factory = new ComponentFactory( editor );
  *
  *		factory.add( 'foo', locale => new FooView( locale ) );
@@ -25,7 +25,7 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  *		// An instance of FooView.
  *		const fooInstance = factory.create( 'foo' );
  *
- *		// Names are case-insensitive os this is also allowed:
+ *		// Names are case insensitive so this is also allowed:
  *		const barInstance = factory.create( 'Bar' );
  *
  * The {@link module:core/editor/editor~Editor#locale editor locale} is passed to the factory
@@ -40,7 +40,7 @@ export default class ComponentFactory {
 	 */
 	constructor( editor ) {
 		/**
-		 * The editor instance the factory belongs to.
+		 * The editor instance that the factory belongs to.
 		 *
 		 * @readonly
 		 * @member {module:core/editor/editor~Editor}
@@ -130,7 +130,7 @@ export default class ComponentFactory {
 }
 
 //
-// Ensures that component name used as key in internal map is in lower case.
+// Ensures that the component name used as the key in the internal map is in lower case.
 //
 // @private
 // @param {String} name

+ 13 - 13
packages/ckeditor5-ui/src/focuscycler.js

@@ -10,8 +10,8 @@
 import global from '@ckeditor/ckeditor5-utils/src/dom/global';
 
 /**
- * An utility class that helps cycling over focusable {@link module:ui/view~View views} in a
- * {@link module:ui/viewcollection~ViewCollection} when the focus is tracked by
+ * A utility class that helps cycling over focusable {@link module:ui/view~View views} in a
+ * {@link module:ui/viewcollection~ViewCollection} when the focus is tracked by the
  * {@link module:utils/focustracker~FocusTracker} instance. It helps implementing keyboard
  * navigation in HTML forms, toolbars, lists and the like.
  *
@@ -31,10 +31,10 @@ import global from '@ckeditor/ckeditor5-utils/src/dom/global';
  *
  *		const cycler = new FocusCycler( { focusables, focusTracker } );
  *
- *		// Will focus the first forusable view in #focusables.
+ *		// Will focus the first focusable view in #focusables.
  *		cycler.focusFirst();
  *
- *		// Will log next focusable item in #focusables.
+ *		// Will log the next focusable item in #focusables.
  *		console.log( cycler.next );
  *
  * Alternatively, it can work side by side with the {@link module:utils/keystrokehandler~KeystrokeHandler}:
@@ -47,7 +47,7 @@ import global from '@ckeditor/ckeditor5-utils/src/dom/global';
  *		const cycler = new FocusCycler( {
  *			focusables, focusTracker, keystrokeHandler,
  *			actions: {
- *				// When arrowup of arrowleft is detected by the #keystrokeHandler
+ *				// When arrowup of arrowleft is detected by the #keystrokeHandler,
  *				// focusPrevious() will be called on the cycler.
  *				focusPrevious: [ 'arrowup', 'arrowleft' ],
  *			}
@@ -67,14 +67,14 @@ export default class FocusCycler {
 		Object.assign( this, options );
 
 		/**
-		 * A {@link module:ui/view~View view} collection the cycler operates on.
+		 * A {@link module:ui/view~View view} collection that the cycler operates on.
 		 *
 		 * @readonly
 		 * @member {module:utils/collection~Collection} #focusables
 		 */
 
 		/**
-		 * A focus tracker instance that cycler uses to determine the current focus
+		 * A focus tracker instance that the cycler uses to determine the current focus
 		 * state in {@link #focusables}.
 		 *
 		 * @readonly
@@ -93,7 +93,7 @@ export default class FocusCycler {
 		 * Actions that the cycler can take when a keystroke is pressed. Requires
 		 * `options.keystrokeHandler` to be passed and working. When an action is
 		 * performed, `preventDefault` and `stopPropagation` will be called on the event
-		 * the keystroke fired in DOM.
+		 * the keystroke fired in the DOM.
 		 *
 		 *		actions: {
 		 *			// Will call #focusPrevious() when arrowleft or arrowup is pressed.
@@ -171,7 +171,7 @@ export default class FocusCycler {
 
 	/**
 	 * An index of the view in the {@link #focusables} which is focused according
-	 * to {@link #focusTracker}. `null` when there is no such view.
+	 * to {@link #focusTracker}. Returns `null` when there is no such view.
 	 *
 	 * @readonly
 	 * @member {Number|null} #current
@@ -226,7 +226,7 @@ export default class FocusCycler {
 	}
 
 	/**
-	 * Focuses the given view, if exists.
+	 * Focuses the given view if it exists.
 	 *
 	 * @protected
 	 * @param {module:ui/view~View} view
@@ -238,11 +238,11 @@ export default class FocusCycler {
 	}
 
 	/**
-	 * Returns the next/previous focusable view in {@link #focusables} with respect
+	 * Returns the next or previous focusable view in {@link #focusables} with respect
 	 * to {@link #current}.
 	 *
 	 * @protected
-	 * @param {Number} step Either `1` for checking forward of {@link #current} or
+	 * @param {Number} step Either `1` for checking forward from {@link #current} or
 	 * `-1` for checking backwards.
 	 * @returns {module:ui/view~View|null}
 	 */
@@ -280,7 +280,7 @@ export default class FocusCycler {
 	}
 }
 
-// Checks whether an view is focusable.
+// Checks whether a view is focusable.
 //
 // @private
 // @param {module:ui/view~View} view A view to be checked.

+ 52 - 52
packages/ckeditor5-ui/src/template.js

@@ -50,7 +50,7 @@ const xhtmlNs = 'http://www.w3.org/1999/xhtml';
  *
  *		<p class="foo" style="background-color: yellow;">A paragraph.</p>
  *
- * Additionally, the `observable` will always fire `clicked` upon clicking `<p>` in DOM.
+ * Additionally, the `observable` will always fire `clicked` upon clicking `<p>` in the DOM.
  *
  * See {@link module:ui/template~TemplateDefinition} to know more about templates and complex
  * template definitions.
@@ -84,14 +84,14 @@ export default class Template {
 		 */
 
 		/**
-		 * Text of the template. It also indicates that the template renders to a DOM text node.
+		 * The text of the template. It also indicates that the template renders to a DOM text node.
 		 *
 		 * @member {Array.<String|module:ui/template~TemplateValueSchema>} #text
 		 */
 
 		/**
-		 * Attributes of the template, e.g. `{ id: [ 'ck-id' ] }`, corresponding with
-		 * attributes of an HTML element.
+		 * The attributes of the template, e.g. `{ id: [ 'ck-id' ] }`, corresponding with
+		 * the attributes of an HTML element.
 		 *
 		 * **Note**: This property only makes sense when {@link #tag} is defined.
 		 *
@@ -99,8 +99,8 @@ export default class Template {
 		 */
 
 		/**
-		 * Children of the template. They can be either:
-		 * * an independent instances of {@link ~Template} (sub–templates),
+		 * The children of the template. They can be either:
+		 * * independent instances of {@link ~Template} (sub–templates),
 		 * * native DOM Nodes.
 		 *
 		 * **Note**: This property only makes sense when {@link #tag} is defined.
@@ -109,13 +109,13 @@ export default class Template {
 		 */
 
 		/**
-		 * DOM event listeners of the template.
+		 * The DOM event listeners of the template.
 		 *
 		 * @member {Object} #eventListeners
 		 */
 
 		/**
-		 * Data used by the {@link #revert} method to restore a node to its original state.
+		 * The data used by the {@link #revert} method to restore a node to its original state.
 		 *
 		 * See: {@link #apply}.
 		 *
@@ -155,7 +155,7 @@ export default class Template {
 	 * **Note:** Existing `class` and `style` attributes are extended when a template
 	 * is applied to an HTML element, while other attributes and `textContent` are overridden.
 	 *
-	 * **Note:** The process of applying a template can be easily reverted using
+	 * **Note:** The process of applying a template can be easily reverted using the
 	 * {@link module:ui/template~Template#revert} method.
 	 *
 	 *		const element = document.createElement( 'div' );
@@ -195,17 +195,17 @@ export default class Template {
 	/**
 	 * Reverts a template {@link module:ui/template~Template#apply applied} to a DOM node.
 	 *
-	 * @param {Node} node Root node for the template to revert. In most of the cases, it is the
+	 * @param {Node} node The root node for the template to revert. In most of the cases, it is the
 	 * same node used by {@link module:ui/template~Template#apply}.
 	 */
 	revert( node ) {
 		if ( !this._revertData ) {
 			/**
-			 * Attempting reverting a template which has not been applied yet.
+			 * Attempting to revert a template which has not been applied yet.
 			 *
 			 * @error ui-template-revert-not-applied
 			 */
-			throw new CKEditorError( 'ui-template-revert-not-applied: Attempting reverting a template which has not been applied yet.' );
+			throw new CKEditorError( 'ui-template-revert-not-applied: Attempting to revert a template which has not been applied yet.' );
 		}
 
 		this._revertTemplateFromNode( node, this._revertData );
@@ -268,7 +268,7 @@ export default class Template {
 	 *
 	 *		new Template( {
 	 *			attrs: {
-	 *				// Binds element's "class" attribute to observable#classAttribute.
+	 *				// Binds the element "class" attribute to observable#classAttribute.
 	 *				class: bind.to( 'classAttribute' )
 	 *			}
 	 *		} ).render();
@@ -400,13 +400,13 @@ export default class Template {
 
 		if ( isInvalid ) {
 			/**
-			 * Node definition cannot have "tag" and "text" properties at the same time.
-			 * Node definition must have either "tag" or "text" when rendering new Node.
+			 * Node definition cannot have the "tag" and "text" properties at the same time.
+			 * Node definition must have either "tag" or "text" when rendering a new Node.
 			 *
 			 * @error ui-template-wrong-syntax
 			 */
 			throw new CKEditorError(
-				'ui-template-wrong-syntax: Node definition must have either "tag" or "text" when rendering new Node.'
+				'ui-template-wrong-syntax: Node definition must have either "tag" or "text" when rendering a new Node.'
 			);
 		}
 
@@ -484,7 +484,7 @@ export default class Template {
 	}
 
 	/**
-	 * Renders an HTML element attributes out of {@link module:ui/template~Template#attributes}.
+	 * Renders HTML element attributes out of {@link module:ui/template~Template#attributes}.
 	 *
 	 * @protected
 	 * @param {module:ui/template~RenderData} data Rendering data.
@@ -618,7 +618,7 @@ export default class Template {
 	 * Renders the `style` attribute of an HTML element based on
 	 * {@link module:ui/template~Template#attributes}.
 	 *
-	 * Style attribute is an {Object} with static values:
+	 * A style attribute is an {Object} with static values:
 	 *
 	 *		attributes: {
 	 *			style: {
@@ -634,7 +634,7 @@ export default class Template {
 	 *			}
 	 *		}
 	 *
-	 * Note: `style` attribute is rendered without setting the namespace. It does not seem to be
+	 * Note: The `style` attribute is rendered without setting the namespace. It does not seem to be
 	 * needed.
 	 *
 	 * @private
@@ -757,13 +757,13 @@ export default class Template {
 	 * For a given {@link module:ui/template~TemplateValueSchema} containing {@link module:ui/template~TemplateBinding}
 	 * activates the binding and sets its initial value.
 	 *
-	 * Note: {@link module:ui/template~TemplateValueSchema} can be for an HTML element attributes or
+	 * Note: {@link module:ui/template~TemplateValueSchema} can be for HTML element attributes or
 	 * text node `textContent`.
 	 *
 	 * @protected
 	 * @param {Object} options Binding options.
 	 * @param {module:ui/template~TemplateValueSchema} options.schema
-	 * @param {Function} options.updater A function which updates DOM (like attribute or text).
+	 * @param {Function} options.updater A function which updates the DOM (like attribute or text).
 	 * @param {module:ui/template~RenderData} options.data Rendering data.
 	 */
 	_bindToObservable( { schema, updater, data } ) {
@@ -789,7 +789,7 @@ export default class Template {
 
 	/**
 	 * Reverts {@link module:ui/template~RenderData#revertData template data} from a node to
-	 * return it to the the original state.
+	 * return it to the original state.
 	 *
 	 * @protected
 	 * @param {HTMLElement|Text} node A node to be reverted.
@@ -839,7 +839,7 @@ export default class Template {
 mix( Template, EmitterMixin );
 
 /**
- * Describes a binding created by {@link module:ui/template~Template.bind} interface.
+ * Describes a binding created by the {@link module:ui/template~Template.bind} interface.
  *
  * @protected
  */
@@ -855,7 +855,7 @@ export class TemplateBinding {
 		/**
 		 * An observable instance of the binding. It either:
 		 *
-		 * * provides the attribute with the value
+		 * * provides the attribute with the value,
 		 * * or passes the event when a corresponding DOM event is fired.
 		 *
 		 * @member {module:utils/observablemixin~ObservableMixin} module:ui/template~TemplateBinding#observable
@@ -903,8 +903,8 @@ export class TemplateBinding {
 	 * {@link module:ui/template~TemplateBinding#observable}, then updates the DOM with the aggregated
 	 * value of {@link module:ui/template~TemplateValueSchema}.
 	 *
-	 * @param {module:ui/template~TemplateValueSchema} schema A full schema to generate an attribute or text in DOM.
-	 * @param {Function} updater A DOM updater function used to update native DOM attribute or text.
+	 * @param {module:ui/template~TemplateValueSchema} schema A full schema to generate an attribute or text in the DOM.
+	 * @param {Function} updater A DOM updater function used to update the native DOM attribute or text.
 	 * @param {module:ui/template~RenderData} data Rendering data.
 	 * @returns {Function} A function to sever the listener binding.
 	 */
@@ -935,8 +935,8 @@ export class TemplateToBinding extends TemplateBinding {
 	 * Activates the listener for the native DOM event, which when fired, is propagated by
 	 * the {@link module:ui/template~TemplateBinding#emitter}.
 	 *
-	 * @param {String} domEvtName A name of the native DOM event.
-	 * @param {String} domSelector A selector in DOM to filter delegated events.
+	 * @param {String} domEvtName The name of the native DOM event.
+	 * @param {String} domSelector The selector in the DOM to filter delegated events.
 	 * @param {module:ui/template~RenderData} data Rendering data.
 	 * @returns {Function} A function to sever the listener binding.
 	 */
@@ -961,7 +961,7 @@ export class TemplateToBinding extends TemplateBinding {
 }
 
 /**
- * Describes a binding to {@link module:utils/observablemixin~ObservableMixin} created by {@link module:ui/template~BindChain#if}
+ * Describes a binding to {@link module:utils/observablemixin~ObservableMixin} created by the {@link module:ui/template~BindChain#if}
  * method.
  *
  * @protected
@@ -977,7 +977,7 @@ export class TemplateIfBinding extends TemplateBinding {
 	}
 
 	/**
-	 * The value of the DOM attribute/text to be set if the {@link module:ui/template~TemplateBinding#attribute} in
+	 * The value of the DOM attribute or text to be set if the {@link module:ui/template~TemplateBinding#attribute} in
 	 * {@link module:ui/template~TemplateBinding#observable} is `true`.
 	 *
 	 * @member {String} [module:ui/template~TemplateIfBinding#valueIfTrue]
@@ -1015,7 +1015,7 @@ function hasTemplateBinding( schema ) {
 }
 
 // Assembles the value using {@link module:ui/template~TemplateValueSchema} and stores it in a form of
-// an Array. Each entry of an Array corresponds to one of {@link module:ui/template~TemplateValueSchema}
+// an Array. Each entry of the Array corresponds to one of {@link module:ui/template~TemplateValueSchema}
 // items.
 //
 // @param {module:ui/template~TemplateValueSchema} schema
@@ -1033,11 +1033,11 @@ function getValueSchemaValue( schema, node ) {
 	} );
 }
 
-// A function executed each time bound Observable attribute changes, which updates DOM with a value
+// A function executed each time the bound Observable attribute changes, which updates the DOM with a value
 // constructed from {@link module:ui/template~TemplateValueSchema}.
 //
 // @param {module:ui/template~TemplateValueSchema} schema
-// @param {Function} updater A function which updates DOM (like attribute or text).
+// @param {Function} updater A function which updates the DOM (like attribute or text).
 // @param {Node} node DOM Node updated when {@link module:utils/observablemixin~ObservableMixin} changes.
 function syncValueSchemaValue( schema, updater, { node } ) {
 	let value = getValueSchemaValue( schema, node );
@@ -1525,19 +1525,19 @@ function shouldExtend( attrName ) {
  * @typedef module:ui/template~TemplateDefinition
  * @type Object
  *
- * @property {String} tag See template {@link module:ui/template~Template#tag} property.
+ * @property {String} tag See the template {@link module:ui/template~Template#tag} property.
  *
  * @property {Array.<module:ui/template~TemplateDefinition>} [children]
- * See template {@link module:ui/template~Template#children} property.
+ * See the template {@link module:ui/template~Template#children} property.
  *
  * @property {Object.<String, module:ui/template~TemplateValueSchema>} [attributes]
- * See template {@link module:ui/template~Template#attributes} property.
+ * See the template {@link module:ui/template~Template#attributes} property.
  *
  * @property {String|module:ui/template~TemplateValueSchema|Array.<String|module:ui/template~TemplateValueSchema>} [text]
- * See template {@link module:ui/template~Template#text} property.
+ * See the template {@link module:ui/template~Template#text} property.
  *
  * @property {Object.<String, module:ui/template~TemplateListenerSchema>} [on]
- * See template {@link module:ui/template~Template#eventListeners} property.
+ * See the template {@link module:ui/template~Template#eventListeners} property.
  */
 
 /**
@@ -1593,7 +1593,7 @@ function shouldExtend( attrName ) {
  *			}
  *		} );
  *
- * Text nodes can also be have complex values:
+ * Text nodes can also have complex values:
  *
  *		const bind = Template.bind( observable, emitter );
  *
@@ -1622,7 +1622,7 @@ function shouldExtend( attrName ) {
  *
  * Also see:
  * * {@link module:ui/template~TemplateDefinition} to learn more about template definitions,
- * * {@link module:ui/template~BindChain#to `to()`} method, to learn more about bindings.
+ * * {@link module:ui/template~BindChain#to `to()`} method to learn more about bindings.
  *
  * Check out different ways of attaching event listeners below:
  *
@@ -1632,7 +1632,7 @@ function shouldExtend( attrName ) {
  *		new Template( {
  *			tag: 'p',
  *			on: {
- *				// An object schema. The observable will fire 'clicked' event upon DOM 'click'.
+ *				// An object schema. The observable will fire the "clicked" event upon DOM "click".
  *				click: bind.to( 'clicked' )
  *
  *				// An object schema. It will work for "click" event on "a.foo" children only.
@@ -1660,7 +1660,7 @@ function shouldExtend( attrName ) {
 
 /**
  * The return value of {@link ~Template.bind `Template.bind()`}. It provides `to()` and `if()`
- * methods to create {@link module:utils/observablemixin~Observable observable} attribute and event bindings.
+ * methods to create the {@link module:utils/observablemixin~Observable observable} attribute and event bindings.
  *
  * @interface module:ui/template~BindChain
  */
@@ -1668,11 +1668,11 @@ function shouldExtend( attrName ) {
 /**
  * Binds an {@link module:utils/observablemixin~Observable observable} to either:
  *
- * * an HTML element attribute or a text node `textContent` so remains in sync with the observable
+ * * an HTML element attribute or a text node `textContent`, so it remains in sync with the observable
  * attribute as it changes,
  * * or an HTML element DOM event, so the DOM events are propagated through an observable.
  *
- * Some common usecases of `to()` bindings are presented below:
+ * Some common use cases of `to()` bindings are presented below:
  *
  *		const bind = Template.bind( observable, emitter );
  *
@@ -1690,10 +1690,10 @@ function shouldExtend( attrName ) {
  *			],
  *			on: {
  *				click: [
- *					// an observable will fire "clicked" upon "click" in DOM.
+ *					// An observable will fire "clicked" upon "click" in the DOM.
  *					bind.to( 'clicked' ),
  *
- *					// A custom callback will be executed upon "click" in DOM.
+ *					// A custom callback will be executed upon "click" in the DOM.
  *					bind.to( () => {
  *						...
  *					} )
@@ -1707,15 +1707,15 @@ function shouldExtend( attrName ) {
  * @method #to
  * @param {String|Function} eventNameOrFunctionOrAttribute An attribute name of
  * {@link module:utils/observablemixin~Observable} or a DOM event name or an event callback.
- * @param {Function} [callback] Allows processing of the value. Accepts `Node` and `value` as arguments.
+ * @param {Function} [callback] Allows for processing of the value. Accepts `Node` and `value` as arguments.
  * @return {module:ui/template~TemplateBinding}
  */
 
 /**
  * Binds an {@link module:utils/observablemixin~Observable observable} to an HTML element attribute or a text
- * node `textContent` so remains in sync with the observable attribute as it changes.
+ * node `textContent` so it remains in sync with the observable attribute as it changes.
  *
- * Unlike {@link module:ui/template~BindChain#to}, it controls the presence of the attribute/`textContent`
+ * Unlike {@link module:ui/template~BindChain#to}, it controls the presence of the attribute or `textContent`
  * depending on the "falseness" of an {@link module:utils/observablemixin~Observable} attribute.
  *
  *		const bind = Template.bind( observable, emitter );
@@ -1740,9 +1740,9 @@ function shouldExtend( attrName ) {
  *
  * @method #if
  * @param {String} attribute An attribute name of {@link module:utils/observablemixin~Observable} used in the binding.
- * @param {String} [valueIfTrue] Value set when {@link module:utils/observablemixin~Observable} attribute is not
+ * @param {String} [valueIfTrue] Value set when the {@link module:utils/observablemixin~Observable} attribute is not
  * undefined/null/false/'' (empty string).
- * @param {Function} [callback] Allows processing of the value. Accepts `Node` and `value` as arguments.
+ * @param {Function} [callback] Allows for processing of the value. Accepts `Node` and `value` as arguments.
  * @return {module:ui/template~TemplateBinding}
  */
 
@@ -1756,7 +1756,7 @@ function shouldExtend( attrName ) {
 /**
  * Tells {@link module:ui/template~Template#_renderNode} to render
  * children into `DocumentFragment` first and then append the fragment
- * to the parent element. It's a speed optimization.
+ * to the parent element. It is a speed optimization.
  *
  * @member {Boolean} #intoFragment
  */