@ckeditor/ckeditor5-ui 36.0.1 → 37.0.0-alpha.0

package/src/template.js

@@ -18,105 +18,57 @@ const xhtmlNs = 'http://www.w3.org/1999/xhtml';
  *
  * A simple template can look like this:
  *
- *		const bind = Template.bind( observable, emitter );
+ * ```ts
+ * const bind = Template.bind( observable, emitter );
  *
- *		new Template( {
- *			tag: 'p',
- *			attributes: {
- *				class: 'foo',
- *				style: {
- *					backgroundColor: 'yellow'
- *				}
- *			},
- *			on: {
- *				click: bind.to( 'clicked' )
- *			},
- *			children: [
- *				'A paragraph.'
- *			]
- *		} ).render();
+ * new Template( {
+ * 	tag: 'p',
+ * 	attributes: {
+ * 		class: 'foo',
+ * 		style: {
+ * 			backgroundColor: 'yellow'
+ * 		}
+ * 	},
+ * 	on: {
+ * 		click: bind.to( 'clicked' )
+ * 	},
+ * 	children: [
+ * 		'A paragraph.'
+ * 	]
+ * } ).render();
+ * ```
  *
  * and it will render the following HTML element:
  *
- *		<p class="foo" style="background-color: yellow;">A paragraph.</p>
+ * ```html
+ * <p class="foo" style="background-color: yellow;">A paragraph.</p>
+ * ```
  *
  * 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.
- *
-* @mixes module:utils/emittermixin~EmitterMixin
  */
 export default class Template extends EmitterMixin() {
     /**
      * Creates an instance of the {@link ~Template} class.
      *
-     * @param {module:ui/template~TemplateDefinition} def The definition of the template.
+     * @param def The definition of the template.
      */
     constructor(def) {
         super();
         Object.assign(this, normalize(clone(def)));
-        /**
-         * Indicates whether this particular Template instance has been
-         * {@link #render rendered}.
-         *
-         * @readonly
-         * @protected
-         * @member {Boolean}
-         */
         this._isRendered = false;
-        /**
-         * The tag (`tagName`) of this template, e.g. `div`. It also indicates that the template
-         * renders to an HTML element.
-         *
-         * @member {String} #tag
-         */
-        /**
-         * 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
-         */
-        /**
-         * 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.
-         *
-         * @member {Object} #attributes
-         */
-        /**
-         * 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.
-         *
-         * @member {Array.<module:ui/template~Template|Node>} #children
-         */
-        /**
-         * The DOM event listeners of the template.
-         *
-         * @member {Object} #eventListeners
-         */
-        /**
-         * The data used by the {@link #revert} method to restore a node to its original state.
-         *
-         * See: {@link #apply}.
-         *
-         * @readonly
-         * @protected
-         * @member {module:ui/template~RenderData}
-         */
         this._revertData = null;
     }
     /**
      * Renders a DOM Node (an HTML element or text) out of the template.
      *
-     *		const domNode = new Template( { ... } ).render();
+     * ```ts
+     * const domNode = new Template( { ... } ).render();
+     * ```
      *
      * See: {@link #apply}.
-     *
-     * @returns {HTMLElement|Text}
      */
     render() {
         const node = this._renderNode({
@@ -140,29 +92,31 @@ export default class Template extends EmitterMixin() {
      * **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' );
-     *		const observable = new Model( { divClass: 'my-div' } );
-     *		const emitter = Object.create( EmitterMixin );
-     *		const bind = Template.bind( observable, emitter );
+     * ```ts
+     * const element = document.createElement( 'div' );
+     * const observable = new Model( { divClass: 'my-div' } );
+     * const emitter = Object.create( EmitterMixin );
+     * const bind = Template.bind( observable, emitter );
      *
-     *		new Template( {
-     *			attributes: {
-     *				id: 'first-div',
-     *				class: bind.to( 'divClass' )
-     *			},
-     *			on: {
-     *				click: bind( 'elementClicked' ) // Will be fired by the observable.
-     *			},
-     *			children: [
-     *				'Div text.'
-     *			]
-     *		} ).apply( element );
+     * new Template( {
+     * 	attributes: {
+     * 		id: 'first-div',
+     * 		class: bind.to( 'divClass' )
+     * 	},
+     * 	on: {
+     * 		click: bind( 'elementClicked' ) // Will be fired by the observable.
+     * 	},
+     * 	children: [
+     * 		'Div text.'
+     * 	]
+     * } ).apply( element );
      *
-     *		console.log( element.outerHTML ); // -> '<div id="first-div" class="my-div"></div>'
+     * console.log( element.outerHTML ); // -> '<div id="first-div" class="my-div"></div>'
+     * ```
      *
      * @see module:ui/template~Template#render
      * @see module:ui/template~Template#revert
-     * @param {Node} node Root node for the template to apply.
+     * @param node Root node for the template to apply.
      */
     apply(node) {
         this._revertData = getEmptyRevertData();
@@ -177,7 +131,7 @@ export default class Template extends EmitterMixin() {
     /**
      * Reverts a template {@link module:ui/template~Template#apply applied} to a DOM node.
      *
-     * @param {Node} node The root node for the template to revert. In most of the cases, it is the
+     * @param 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) {
@@ -195,29 +149,29 @@ export default class Template extends EmitterMixin() {
      * Returns an iterator which traverses the template in search of {@link module:ui/view~View}
      * instances and returns them one by one.
      *
-     *		const viewFoo = new View();
-     *		const viewBar = new View();
-     *		const viewBaz = new View();
-     *		const template = new Template( {
-     *			tag: 'div',
-     *			children: [
-     *				viewFoo,
-     *				{
-     *					tag: 'div',
-     *					children: [
-     *						viewBar
-     *					]
-     *				},
-     *				viewBaz
-     *			]
-     *		} );
-     *
-     *		// Logs: viewFoo, viewBar, viewBaz
-     *		for ( const view of template.getViews() ) {
-     *			console.log( view );
-     *		}
+     * ```ts
+     * const viewFoo = new View();
+     * const viewBar = new View();
+     * const viewBaz = new View();
+     * const template = new Template( {
+     * 	tag: 'div',
+     * 	children: [
+     * 		viewFoo,
+     * 		{
+     * 			tag: 'div',
+     * 			children: [
+     * 				viewBar
+     * 			]
+     * 		},
+     * 		viewBaz
+     * 	]
+     * } );
      *
-     * @returns {Iterable.<module:ui/view~View>}
+     * // Logs: viewFoo, viewBar, viewBaz
+     * for ( const view of template.getViews() ) {
+     * 	console.log( view );
+     * }
+     * ```
      */
     *getViews() {
         function* search(def) {
@@ -243,33 +197,36 @@ export default class Template extends EmitterMixin() {
      * {@link module:utils/observablemixin~Observable}. Learn more about {@link module:ui/template~BindChain#to}
      * and {@link module:ui/template~BindChain#if}.
      *
-     *		const bind = Template.bind( observable, emitter );
+     * ```ts
+     * const bind = Template.bind( observable, emitter );
      *
-     *		new Template( {
-     *			attributes: {
-     *				// Binds the element "class" attribute to observable#classAttribute.
-     *				class: bind.to( 'classAttribute' )
-     *			}
-     *		} ).render();
+     * new Template( {
+     * 	attributes: {
+     * 		// Binds the element "class" attribute to observable#classAttribute.
+     * 		class: bind.to( 'classAttribute' )
+     * 	}
+     * } ).render();
+     * ```
      *
      * * DOM events fired on HTML element propagated through
      * {@link module:utils/observablemixin~Observable}. Learn more about {@link module:ui/template~BindChain#to}.
      *
-     *		const bind = Template.bind( observable, emitter );
+     * ```ts
+     * const bind = Template.bind( observable, emitter );
      *
-     *		new Template( {
-     *			on: {
-     *				// Will be fired by the observable.
-     *				click: bind( 'elementClicked' )
-     *			}
-     *		} ).render();
+     * new Template( {
+     * 	on: {
+     * 		// Will be fired by the observable.
+     * 		click: bind( 'elementClicked' )
+     * 	}
+     * } ).render();
+     * ```
      *
      * Also see {@link module:ui/view~View#bindTemplate}.
      *
-     * @param {module:utils/observablemixin~Observable} observable An observable which provides boundable attributes.
-     * @param {module:utils/emittermixin~Emitter} emitter An emitter that listens to observable attribute
+     * @param observable An observable which provides boundable attributes.
+     * @param emitter An emitter that listens to observable attribute
      * changes or DOM Events (depending on the kind of the binding). Usually, a {@link module:ui/view~View} instance.
-     * @returns {module:ui/template~BindChain}
      */
     static bind(observable, emitter) {
         return {
@@ -291,57 +248,61 @@ export default class Template extends EmitterMixin() {
      * Extends an existing {@link module:ui/template~Template} instance with some additional content
      * from another {@link module:ui/template~TemplateDefinition}.
      *
-     *		const bind = Template.bind( observable, emitter );
+     * ```ts
+     * const bind = Template.bind( observable, emitter );
      *
-     *		const template = new Template( {
-     *			tag: 'p',
-     *			attributes: {
-     *				class: 'a',
-     *				data-x: bind.to( 'foo' )
-     *			},
-     *			children: [
-     *				{
-     *					tag: 'span',
-     *					attributes: {
-     *						class: 'b'
-     *					},
-     *					children: [
-     *						'Span'
-     *					]
-     *				}
-     *			]
-     *		 } );
+     * const template = new Template( {
+     * 	tag: 'p',
+     * 	attributes: {
+     * 		class: 'a',
+     * 		data-x: bind.to( 'foo' )
+     * 	},
+     * 	children: [
+     * 		{
+     * 			tag: 'span',
+     * 			attributes: {
+     * 				class: 'b'
+     * 			},
+     * 			children: [
+     * 				'Span'
+     * 			]
+     * 		}
+     * 	]
+     *  } );
      *
-     *		// Instance-level extension.
-     *		Template.extend( template, {
-     *			attributes: {
-     *				class: 'b',
-     *				data-x: bind.to( 'bar' )
-     *			},
-     *			children: [
-     *				{
-     *					attributes: {
-     *						class: 'c'
-     *					}
-     *				}
-     *			]
-     *		} );
+     * // Instance-level extension.
+     * Template.extend( template, {
+     * 	attributes: {
+     * 		class: 'b',
+     * 		data-x: bind.to( 'bar' )
+     * 	},
+     * 	children: [
+     * 		{
+     * 			attributes: {
+     * 				class: 'c'
+     * 			}
+     * 		}
+     * 	]
+     * } );
      *
-     *		// Child extension.
-     *		Template.extend( template.children[ 0 ], {
-     *			attributes: {
-     *				class: 'd'
-     *			}
-     *		} );
+     * // Child extension.
+     * Template.extend( template.children[ 0 ], {
+     * 	attributes: {
+     * 		class: 'd'
+     * 	}
+     * } );
+     * ```
      *
      * the `outerHTML` of `template.render()` is:
      *
-     *		<p class="a b" data-x="{ observable.foo } { observable.bar }">
-     *			<span class="b c d">Span</span>
-     *		</p>
+     * ```html
+     * <p class="a b" data-x="{ observable.foo } { observable.bar }">
+     * 	<span class="b c d">Span</span>
+     * </p>
+     * ```
      *
-     * @param {module:ui/template~Template} template An existing template instance to be extended.
-     * @param {module:ui/template~TemplateDefinition} def Additional definition to be applied to a template.
+     * @param template An existing template instance to be extended.
+     * @param def Additional definition to be applied to a template.
      */
     static extend(template, def) {
         if (template._isRendered) {
@@ -359,8 +320,7 @@ export default class Template extends EmitterMixin() {
     /**
      * Renders a DOM Node (either an HTML element or text) out of the template.
      *
-     * @protected
-     * @param {module:ui/template~RenderData} data Rendering data.
+     * @param data Rendering data.
      */
     _renderNode(data) {
         let isInvalid;
@@ -391,8 +351,7 @@ export default class Template extends EmitterMixin() {
     /**
      * Renders an HTML element out of the template.
      *
-     * @protected
-     * @param {module:ui/template~RenderData} data Rendering data.
+     * @param data Rendering data.
      */
     _renderElement(data) {
         let node = data.node;
@@ -407,8 +366,7 @@ export default class Template extends EmitterMixin() {
     /**
      * Renders a text node out of {@link module:ui/template~Template#text}.
      *
-     * @protected
-     * @param {module:ui/template~RenderData} data Rendering data.
+     * @param data Rendering data.
      */
     _renderText(data) {
         let node = data.node;
@@ -450,8 +408,7 @@ export default class Template extends EmitterMixin() {
     /**
      * Renders HTML element attributes out of {@link module:ui/template~Template#attributes}.
      *
-     * @protected
-     * @param {module:ui/template~RenderData} data Rendering data.
+     * @param data Rendering data.
      */
     _renderAttributes(data) {
         if (!this.attributes) {
@@ -567,28 +524,31 @@ export default class Template extends EmitterMixin() {
      * Renders the `style` attribute of an HTML element based on
      * {@link module:ui/template~Template#attributes}.
      *
-     * A style attribute is an {Object} with static values:
+     * A style attribute is an object with static values:
      *
-     *		attributes: {
-     *			style: {
-     *				color: 'red'
-     *			}
-     *		}
+     * ```ts
+     * attributes: {
+     * 	style: {
+     * 		color: 'red'
+     * 	}
+     * }
+     * ```
      *
      * or values bound to {@link module:ui/model~Model} properties:
      *
-     *		attributes: {
-     *			style: {
-     *				color: bind.to( ... )
-     *			}
-     *		}
+     * ```ts
+     * attributes: {
+     * 	style: {
+     * 		color: bind.to( ... )
+     * 	}
+     * }
+     * ```
      *
      * Note: The `style` attribute is rendered without setting the namespace. It does not seem to be
      * needed.
      *
-     * @private
-     * @param {Object} styles Styles located in `attributes.style` of {@link module:ui/template~TemplateDefinition}.
-     * @param {module:ui/template~RenderData} data Rendering data.
+     * @param styles Styles located in `attributes.style` of {@link module:ui/template~TemplateDefinition}.
+     * @param data Rendering data.
      */
     _renderStyleAttribute(styles, data) {
         const node = data.node;
@@ -621,8 +581,7 @@ export default class Template extends EmitterMixin() {
     /**
      * Recursively renders HTML element's children from {@link module:ui/template~Template#children}.
      *
-     * @protected
-     * @param {module:ui/template~RenderData} data Rendering data.
+     * @param data Rendering data.
      */
     _renderElementChildren(data) {
         const node = data.node;
@@ -675,8 +634,7 @@ export default class Template extends EmitterMixin() {
      * Activates `on` event listeners from the {@link module:ui/template~TemplateDefinition}
      * on an HTML element.
      *
-     * @protected
-     * @param {module:ui/template~RenderData} data Rendering data.
+     * @param data Rendering data.
      */
     _setUpListeners(data) {
         if (!this.eventListeners) {
@@ -699,11 +657,9 @@ export default class Template extends EmitterMixin() {
      * 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 the DOM (like attribute or text).
-     * @param {module:ui/template~RenderData} options.data Rendering data.
+     * @param options Binding options.
+     * @param options.updater A function which updates the DOM (like attribute or text).
+     * @param options.data Rendering data.
      */
     _bindToObservable({ schema, updater, data }) {
         const revertData = data.revertData;
@@ -726,9 +682,8 @@ export default class Template extends EmitterMixin() {
      * Reverts {@link module:ui/template~RenderData#revertData template data} from a node to
      * return it to the original state.
      *
-     * @protected
-     * @param {HTMLElement|Text} node A node to be reverted.
-     * @param {Object} revertData An object that stores information about what changes have been made by
+     * @param node A node to be reverted.
+     * @param revertData An object that stores information about what changes have been made by
      * {@link #apply} to the node. See {@link module:ui/template~RenderData#revertData} for more information.
      */
     _revertTemplateFromNode(node, revertData) {
@@ -770,54 +725,27 @@ export default class Template extends EmitterMixin() {
 /**
  * Describes a binding created by the {@link module:ui/template~Template.bind} interface.
  *
- * @protected
  * @internal
  */
 export class TemplateBinding {
     /**
      * Creates an instance of the {@link module:ui/template~TemplateBinding} class.
      *
-     * @param {module:ui/template~TemplateDefinition} def The definition of the binding.
+     * @param def The definition of the binding.
      */
     constructor(def) {
         this.attribute = def.attribute;
         this.observable = def.observable;
         this.emitter = def.emitter;
         this.callback = def.callback;
-        /**
-         * An observable instance of the binding. It either:
-         *
-         * * 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
-         */
-        /**
-         * An {@link module:utils/emittermixin~Emitter} used by the binding to:
-         *
-         * * listen to the attribute change in the {@link module:ui/template~TemplateBinding#observable},
-         * * or listen to the event in the DOM.
-         *
-         * @member {module:utils/emittermixin~EmitterMixin} module:ui/template~TemplateBinding#emitter
-         */
-        /**
-         * The name of the {@link module:ui/template~TemplateBinding#observable observed attribute}.
-         *
-         * @member {String} module:ui/template~TemplateBinding#attribute
-         */
-        /**
-         * A custom function to process the value of the {@link module:ui/template~TemplateBinding#attribute}.
-         *
-         * @member {Function} [module:ui/template~TemplateBinding#callback]
-         */
     }
     /**
      * Returns the value of the binding. It is the value of the {@link module:ui/template~TemplateBinding#attribute} in
      * {@link module:ui/template~TemplateBinding#observable}. The value may be processed by the
      * {@link module:ui/template~TemplateBinding#callback}, if such has been passed to the binding.
      *
-     * @param {Node} [node] A native DOM node, passed to the custom {@link module:ui/template~TemplateBinding#callback}.
-     * @returns {*} The value of {@link module:ui/template~TemplateBinding#attribute} in
+     * @param node A native DOM node, passed to the custom {@link module:ui/template~TemplateBinding#callback}.
+     * @returns The value of {@link module:ui/template~TemplateBinding#attribute} in
      * {@link module:ui/template~TemplateBinding#observable}.
      */
     getValue(node) {
@@ -829,10 +757,10 @@ 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 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.
+     * @param schema A full schema to generate an attribute or text in the DOM.
+     * @param updater A DOM updater function used to update the native DOM attribute or text.
+     * @param data Rendering data.
+     * @returns A function to sever the listener binding.
      */
     activateAttributeListener(schema, updater, data) {
         const callback = () => syncValueSchemaValue(schema, updater, data);
@@ -851,7 +779,6 @@ export class TemplateBinding {
  *
  * It is created by the {@link module:ui/template~BindChain#to} method.
  *
- * @protected
  * @internal
  */
 export class TemplateToBinding extends TemplateBinding {
@@ -863,10 +790,10 @@ 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 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.
+     * @param domEvtName The name of the native DOM event.
+     * @param domSelector The selector in the DOM to filter delegated events.
+     * @param data Rendering data.
+     * @returns A function to sever the listener binding.
      */
     activateDomEventListener(domEvtName, domSelector, data) {
         const callback = (evt, domEvt) => {
@@ -890,7 +817,6 @@ export class TemplateToBinding extends TemplateBinding {
  * Describes a binding to {@link module:utils/observablemixin~ObservableMixin} created by the {@link module:ui/template~BindChain#if}
  * method.
  *
- * @protected
  * @internal
  */
 export class TemplateIfBinding extends TemplateBinding {
@@ -906,11 +832,10 @@ export class TemplateIfBinding extends TemplateBinding {
         return isFalsy(value) ? false : (this.valueIfTrue || true);
     }
 }
-// Checks whether given {@link module:ui/template~TemplateValueSchema} contains a
-// {@link module:ui/template~TemplateBinding}.
-//
-// @param {module:ui/template~TemplateValueSchema} schema
-// @returns {Boolean}
+/**
+ * Checks whether given {@link module:ui/template~TemplateValueSchema} contains a
+ * {@link module:ui/template~TemplateBinding}.
+ */
 function hasTemplateBinding(schema) {
     if (!schema) {
         return false;
@@ -933,13 +858,13 @@ function hasTemplateBinding(schema) {
     }
     return false;
 }
-// Assembles the value using {@link module:ui/template~TemplateValueSchema} and stores it in a form of
-// an Array. Each entry of the Array corresponds to one of {@link module:ui/template~TemplateValueSchema}
-// items.
-//
-// @param {module:ui/template~TemplateValueSchema} schema
-// @param {Node} node DOM Node updated when {@link module:utils/observablemixin~ObservableMixin} changes.
-// @returns {Array}
+/**
+ * Assembles the value using {@link module:ui/template~TemplateValueSchema} and stores it in a form of
+ * an Array. Each entry of the Array corresponds to one of {@link module:ui/template~TemplateValueSchema}
+ * items.
+ *
+ * @param node DOM Node updated when {@link module:utils/observablemixin~ObservableMixin} changes.
+ */
 function getValueSchemaValue(schema, node) {
     return schema.map(schemaItem => {
         // Process {@link module:ui/template~TemplateBinding} bindings.
@@ -950,12 +875,13 @@ function getValueSchemaValue(schema, node) {
         return schemaItem;
     });
 }
-// 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 the DOM (like attribute or text).
-// @param {Node} node DOM Node updated when {@link module:utils/observablemixin~ObservableMixin} changes.
+/**
+ * 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 updater A function which updates the DOM (like attribute or text).
+ * @param node DOM Node updated when {@link module:utils/observablemixin~ObservableMixin} changes.
+ */
 function syncValueSchemaValue(schema, updater, { node }) {
     const values = getValueSchemaValue(schema, node);
     let value;
@@ -976,12 +902,13 @@ function syncValueSchemaValue(schema, updater, { node }) {
         updater.set(value);
     }
 }
-// Returns an object consisting of `set` and `remove` functions, which
-// can be used in the context of DOM Node to set or reset `textContent`.
-// @see module:ui/view~View#_bindToObservable
-//
-// @param {Node} node DOM Node to be modified.
-// @returns {Object}
+/**
+ * Returns an object consisting of `set` and `remove` functions, which
+ * can be used in the context of DOM Node to set or reset `textContent`.
+ * @see module:ui/view~View#_bindToObservable
+ *
+ * @param node DOM Node to be modified.
+ */
 function getTextUpdater(node) {
     return {
         set(value) {
@@ -992,14 +919,15 @@ function getTextUpdater(node) {
         }
     };
 }
-// Returns an object consisting of `set` and `remove` functions, which
-// can be used in the context of DOM Node to set or reset an attribute.
-// @see module:ui/view~View#_bindToObservable
-//
-// @param {Node} node DOM Node to be modified.
-// @param {String} attrName Name of the attribute to be modified.
-// @param {String} [ns=null] Namespace to use.
-// @returns {Object}
+/**
+ * Returns an object consisting of `set` and `remove` functions, which
+ * can be used in the context of DOM Node to set or reset an attribute.
+ * @see module:ui/view~View#_bindToObservable
+ *
+ * @param el DOM Node to be modified.
+ * @param attrName Name of the attribute to be modified.
+ * @param ns Namespace to use.
+ */
 function getAttributeUpdater(el, attrName, ns) {
     return {
         set(value) {
@@ -1010,13 +938,14 @@ function getAttributeUpdater(el, attrName, ns) {
         }
     };
 }
-// Returns an object consisting of `set` and `remove` functions, which
-// can be used in the context of CSSStyleDeclaration to set or remove a style.
-// @see module:ui/view~View#_bindToObservable
-//
-// @param {Node} node DOM Node to be modified.
-// @param {String} styleName Name of the style to be modified.
-// @returns {Object}
+/**
+ * Returns an object consisting of `set` and `remove` functions, which
+ * can be used in the context of CSSStyleDeclaration to set or remove a style.
+ * @see module:ui/view~View#_bindToObservable
+ *
+ * @param el DOM Node to be modified.
+ * @param styleName Name of the style to be modified.
+ */
 function getStyleUpdater(el, styleName) {
     return {
         set(value) {
@@ -1027,10 +956,9 @@ function getStyleUpdater(el, styleName) {
         }
     };
 }
-// Clones definition of the template.
-//
-// @param {module:ui/template~TemplateDefinition} def
-// @returns {module:ui/template~TemplateDefinition}
+/**
+ * Clones definition of the template.
+ */
 function clone(def) {
     const clone = cloneDeepWith(def, value => {
         // Don't clone the `Template.bind`* bindings because of the references to Observable
@@ -1050,16 +978,18 @@ function clone(def) {
     });
     return clone;
 }
-// Normalizes given {@link module:ui/template~TemplateDefinition}.
-//
-// See:
-//  * {@link normalizeAttributes}
-//  * {@link normalizeListeners}
-//  * {@link normalizePlainTextDefinition}
-//  * {@link normalizeTextDefinition}
-//
-// @param {module:ui/template~TemplateDefinition} def
-// @returns {module:ui/template~TemplateDefinition} Normalized definition.
+/**
+ * Normalizes given {@link module:ui/template~TemplateDefinition}.
+ *
+ * See:
+ *  * {@link normalizeAttributes}
+ *  * {@link normalizeListeners}
+ *  * {@link normalizePlainTextDefinition}
+ *  * {@link normalizeTextDefinition}
+ *
+ * @param def A template definition.
+ * @returns Normalized definition.
+ */
 function normalize(def) {
     if (typeof def == 'string') {
         def = normalizePlainTextDefinition(def);
@@ -1096,27 +1026,31 @@ function normalize(def) {
     }
     return def;
 }
-// Normalizes "attributes" section of {@link module:ui/template~TemplateDefinition}.
-//
-//		attributes: {
-//			a: 'bar',
-//			b: {@link module:ui/template~TemplateBinding},
-//			c: {
-//				value: 'bar'
-//			}
-//		}
-//
-// becomes
-//
-//		attributes: {
-//			a: [ 'bar' ],
-//			b: [ {@link module:ui/template~TemplateBinding} ],
-//			c: {
-//				value: [ 'bar' ]
-//			}
-//		}
-//
-// @param {Object} attributes
+/**
+ * Normalizes "attributes" section of {@link module:ui/template~TemplateDefinition}.
+ *
+ * ```
+ * attributes: {
+ * 	a: 'bar',
+ * 	b: {@link module:ui/template~TemplateBinding},
+ * 	c: {
+ * 		value: 'bar'
+ * 	}
+ * }
+ * ```
+ *
+ * becomes
+ *
+ * ```
+ * attributes: {
+ * 	a: [ 'bar' ],
+ * 	b: [ {@link module:ui/template~TemplateBinding} ],
+ * 	c: {
+ * 		value: [ 'bar' ]
+ * 	}
+ * }
+ * ```
+ */
 function normalizeAttributes(attributes) {
     for (const a in attributes) {
         if (attributes[a].value) {
@@ -1125,88 +1059,103 @@ function normalizeAttributes(attributes) {
         arrayify(attributes, a);
     }
 }
-// Normalizes "on" section of {@link module:ui/template~TemplateDefinition}.
-//
-//		on: {
-//			a: 'bar',
-//			b: {@link module:ui/template~TemplateBinding},
-//			c: [ {@link module:ui/template~TemplateBinding}, () => { ... } ]
-//		}
-//
-// becomes
-//
-//		on: {
-//			a: [ 'bar' ],
-//			b: [ {@link module:ui/template~TemplateBinding} ],
-//			c: [ {@link module:ui/template~TemplateBinding}, () => { ... } ]
-//		}
-//
-// @param {Object} listeners
-// @returns {Object} Object containing normalized listeners.
+/**
+ * Normalizes "on" section of {@link module:ui/template~TemplateDefinition}.
+ *
+ * ```
+ * on: {
+ * 	a: 'bar',
+ * 	b: {@link module:ui/template~TemplateBinding},
+ * 	c: [ {@link module:ui/template~TemplateBinding}, () => { ... } ]
+ * }
+ * ```
+ *
+ * becomes
+ *
+ * ```
+ * on: {
+ * 	a: [ 'bar' ],
+ * 	b: [ {@link module:ui/template~TemplateBinding} ],
+ * 	c: [ {@link module:ui/template~TemplateBinding}, () => { ... } ]
+ * }
+ * ```
+ *
+ * @returns Object containing normalized listeners.
+ */
 function normalizeListeners(listeners) {
     for (const l in listeners) {
         arrayify(listeners, l);
     }
     return listeners;
 }
-// Normalizes "string" {@link module:ui/template~TemplateDefinition}.
-//
-//		"foo"
-//
-// becomes
-//
-//		{ text: [ 'foo' ] },
-//
-// @param {String} def
-// @returns {module:ui/template~TemplateDefinition} Normalized template definition.
+/**
+ * Normalizes "string" {@link module:ui/template~TemplateDefinition}.
+ *
+ * ```
+ * "foo"
+ * ```
+ *
+ * becomes
+ *
+ * ```
+ * { text: [ 'foo' ] },
+ * ```
+ *
+ * @returns Normalized template definition.
+ */
 function normalizePlainTextDefinition(def) {
     return {
         text: [def]
     };
 }
-// Normalizes text {@link module:ui/template~TemplateDefinition}.
-//
-//		children: [
-//			{ text: 'def' },
-//			{ text: {@link module:ui/template~TemplateBinding} }
-//		]
-//
-// becomes
-//
-//		children: [
-//			{ text: [ 'def' ] },
-//			{ text: [ {@link module:ui/template~TemplateBinding} ] }
-//		]
-//
-// @param {module:ui/template~TemplateDefinition} def
+/**
+ * Normalizes text {@link module:ui/template~TemplateDefinition}.
+ *
+ * ```
+ * children: [
+ * 	{ text: 'def' },
+ * 	{ text: {@link module:ui/template~TemplateBinding} }
+ * ]
+ * ```
+ *
+ * becomes
+ *
+ * ```
+ * children: [
+ * 	{ text: [ 'def' ] },
+ * 	{ text: [ {@link module:ui/template~TemplateBinding} ] }
+ * ]
+ * ```
+ */
 function normalizeTextDefinition(def) {
     def.text = toArray(def.text);
 }
-// Wraps an entry in Object in an Array, if not already one.
-//
-//		{
-//			x: 'y',
-//			a: [ 'b' ]
-//		}
-//
-// becomes
-//
-//		{
-//			x: [ 'y' ],
-//			a: [ 'b' ]
-//		}
-//
-// @param {Object} obj
-// @param {String} key
+/**
+ * Wraps an entry in Object in an Array, if not already one.
+ *
+ * ```
+ * {
+ * 	x: 'y',
+ * 	a: [ 'b' ]
+ * }
+ * ```
+ *
+ * becomes
+ *
+ * ```
+ * {
+ * 	x: [ 'y' ],
+ * 	a: [ 'b' ]
+ * }
+ * ```
+ */
 function arrayify(obj, key) {
     obj[key] = toArray(obj[key]);
 }
-// A helper which concatenates the value avoiding unwanted
-// leading white spaces.
-//
-// @param {String} prev
-// @param {String} cur
-// @returns {String}
+/**
+ * A helper which concatenates the value avoiding unwanted
+ * leading white spaces.
+ */
 function arrayValueReducer(prev, cur) {
     if (isFalsy(cur)) {
         return prev;
@@ -1218,20 +1167,23 @@ function arrayValueReducer(prev, cur) {
         return `${prev} ${cur}`;
     }
 }
-// Extends one object defined in the following format:
-//
-//		{
-//			key1: [Array1],
-//			key2: [Array2],
-//			...
-//			keyN: [ArrayN]
-//		}
-//
-// with another object of the same data format.
-//
-// @param {Object} obj Base object.
-// @param {Object} ext Object extending base.
-// @returns {String}
+/**
+ * Extends one object defined in the following format:
+ *
+ * ```
+ * {
+ * 	key1: [Array1],
+ * 	key2: [Array2],
+ * 	...
+ * 	keyN: [ArrayN]
+ * }
+ * ```
+ *
+ * with another object of the same data format.
+ *
+ * @param obj Base object.
+ * @param ext Object extending base.
+ */
 function extendObjectValueArray(obj, ext) {
     for (const a in ext) {
         if (obj[a]) {
@@ -1242,12 +1194,14 @@ function extendObjectValueArray(obj, ext) {
         }
     }
 }
-// A helper for {@link module:ui/template~Template#extend}. Recursively extends {@link module:ui/template~Template} instance
-// with content from {@link module:ui/template~TemplateDefinition}. See {@link module:ui/template~Template#extend} to learn more.
-//
-// @param {module:ui/template~Template} def A template instance to be extended.
-// @param {module:ui/template~TemplateDefinition} def A definition which is to extend the template instance.
-// @param {Object} Error context.
+/**
+ * A helper for {@link module:ui/template~Template#extend}. Recursively extends {@link module:ui/template~Template} instance
+ * with content from {@link module:ui/template~TemplateDefinition}. See {@link module:ui/template~Template#extend} to learn more.
+ *
+ * @param def A template instance to be extended.
+ * @param def A definition which is to extend the template instance.
+ * @param Error context.
+ */
 function extendTemplate(template, def) {
     if (def.attributes) {
         if (!template.attributes) {
@@ -1279,43 +1233,49 @@ function extendTemplate(template, def) {
         }
     }
 }
-// Checks if value is "falsy".
-// Note: 0 (Number) is not "falsy" in this context.
-//
-// @private
-// @param {*} value Value to be checked.
+/**
+ * Checks if value is "falsy".
+ * Note: 0 (Number) is not "falsy" in this context.
+ *
+ * @param value Value to be checked.
+ */
 function isFalsy(value) {
     return !value && value !== 0;
 }
-// Checks if the item is an instance of {@link module:ui/view~View}
-//
-// @private
-// @param {*} value Value to be checked.
+/**
+ * Checks if the item is an instance of {@link module:ui/view~View}
+ *
+ * @param value Value to be checked.
+ */
 function isView(item) {
     return item instanceof View;
 }
-// Checks if the item is an instance of {@link module:ui/template~Template}
-//
-// @private
-// @param {*} value Value to be checked.
+/**
+ * Checks if the item is an instance of {@link module:ui/template~Template}
+ *
+ * @param value Value to be checked.
+ */
 function isTemplate(item) {
     return item instanceof Template;
 }
-// Checks if the item is an instance of {@link module:ui/viewcollection~ViewCollection}
-//
-// @private
-// @param {*} value Value to be checked.
+/**
+ * Checks if the item is an instance of {@link module:ui/viewcollection~ViewCollection}
+ *
+ * @param value Value to be checked.
+ */
 function isViewCollection(item) {
     return item instanceof ViewCollection;
 }
-// Checks if value array contains the one with namespace.
+/**
+ * Checks if value array contains the one with namespace.
+ */
 function isNamespaced(attrValue) {
     return isObject(attrValue[0]) && attrValue[0].ns;
 }
-// Creates an empty skeleton for {@link module:ui/template~Template#revert}
-// data.
-//
-// @private
+/**
+ * Creates an empty skeleton for {@link module:ui/template~Template#revert}
+ * data.
+ */
 function getEmptyRevertData() {
     return {
         children: [],
@@ -1323,36 +1283,12 @@ function getEmptyRevertData() {
         attributes: {}
     };
 }
-// Checks whether an attribute should be extended when
-// {@link module:ui/template~Template#apply} is called.
-//
-// @private
-// @param {String} attrName Attribute name to check.
-function shouldExtend(attrName) {
-    return attrName == 'class' || attrName == 'style';
-}
 /**
- * Tells {@link module:ui/template~Template#_renderNode} to render
- * children into `DocumentFragment` first and then append the fragment
- * to the parent element. It is a speed optimization.
+ * Checks whether an attribute should be extended when
+ * {@link module:ui/template~Template#apply} is called.
  *
- * @member {Boolean} #intoFragment
- */
-/**
- * A node which is being rendered.
- *
- * @member {HTMLElement|Text} #node
- */
-/**
- * Indicates whether the {@module:ui/template~RenderNodeOptions#node} has
- * been provided by {@module:ui/template~Template#apply}.
- *
- * @member {Boolean} #isApplying
- */
-/**
- * An object storing the data that helps {@module:ui/template~Template#revert}
- * bringing back an element to its initial state, i.e. before
- * {@module:ui/template~Template#apply} was called.
- *
- * @member {Object} #revertData
+ * @param attrName Attribute name to check.
  */
+function shouldExtend(attrName) {
+    return attrName == 'class' || attrName == 'style';
+}