From: Jo-Philipp Wich <jo@mein.io>
Date: Tue, 7 Apr 2020 14:33:09 +0000 (+0200)
Subject: luci-base: form.js: add documentation
X-Git-Url: http://git.lede-project.org./?a=commitdiff_plain;h=cd6428955460090ca7ee371a17254f92133c444e;p=project%2Fluci.git

luci-base: form.js: add documentation

Signed-off-by: Jo-Philipp Wich <jo@mein.io>
(cherry picked from commit 698c8ff843253c9785bec9dfdff3774db0eae661)
---

diff --git a/modules/luci-base/htdocs/luci-static/resources/form.js b/modules/luci-base/htdocs/luci-static/resources/form.js
index 69793ee554..2b02066a40 100644
--- a/modules/luci-base/htdocs/luci-static/resources/form.js
+++ b/modules/luci-base/htdocs/luci-static/resources/form.js
@@ -173,17 +173,50 @@ var CBIJSONConfig = baseclass.extend({
 	}
 });
 
-var CBINode = baseclass.extend({
+/**
+ * @class AbstractElement
+ * @memberof LuCI.form
+ * @hideconstructor
+ * @classdesc
+ *
+ * The `AbstractElement` class serves as abstract base for the different form
+ * elements implemented by `LuCI.form`. It provides the common logic for
+ * loading and rendering values, for nesting elements and for defining common
+ * properties.
+ *
+ * This class is private and not directly accessible by user code.
+ */
+var CBIAbstractElement = baseclass.extend(/** @lends LuCI.form.AbstractElement.prototype */ {
 	__init__: function(title, description) {
 		this.title = title || '';
 		this.description = description || '';
 		this.children = [];
 	},
 
+	/**
+	 * Add another form element as children to this element.
+	 *
+	 * @param {AbstractElement} element
+	 * The form element to add.
+	 */
 	append: function(obj) {
 		this.children.push(obj);
 	},
 
+	/**
+	 * Parse this elements form input.
+	 *
+	 * The `parse()` function recursively walks the form element tree and
+	 * triggers input value reading and validation for each encountered element.
+	 *
+	 * Elements which are hidden due to unsatisified dependencies are skipped.
+	 *
+	 * @returns {Promise<void>}
+	 * Returns a promise resolving once this element's value and the values of
+	 * all child elements have been parsed. The returned promise is rejected
+	 * if any parsed values are not meeting the validation constraints of their
+	 * respective elements.
+	 */
 	parse: function() {
 		var args = arguments;
 		this.children.forEach(function(child) {
@@ -191,10 +224,22 @@ var CBINode = baseclass.extend({
 		});
 	},
 
+	/**
+	 * Render the form element.
+	 *
+	 * The `render()` function recursively walks the form element tree and
+	 * renders the markup for each element, returning the assembled DOM tree.
+	 *
+	 * @abstract
+	 * @returns {Node|Promise<Node>}
+	 * May return a DOM Node or a promise resolving to a DOM node containing
+	 * the form element's markup, including the markup of any child elements.
+	 */
 	render: function() {
 		L.error('InternalError', 'Not implemented');
 	},
 
+	/** @private */
 	loadChildren: function(/* ... */) {
 		var tasks = [];
 
@@ -206,6 +251,7 @@ var CBINode = baseclass.extend({
 		return Promise.all(tasks);
 	},
 
+	/** @private */
 	renderChildren: function(tab_name /*, ... */) {
 		var tasks = [],
 		    index = 0;
@@ -220,6 +266,15 @@ var CBINode = baseclass.extend({
 		return Promise.all(tasks);
 	},
 
+	/**
+	 * Strip any HTML tags from the given input string.
+	 *
+	 * @param {string} input
+	 * The input string to clean.
+	 *
+	 * @returns {string}
+	 * The cleaned input string with HTML removes removed.
+	 */
 	stripTags: function(s) {
 		if (typeof(s) == 'string' && !s.match(/[<>]/))
 			return s;
@@ -228,6 +283,32 @@ var CBINode = baseclass.extend({
 		return x.textContent || x.innerText || '';
 	},
 
+	/**
+	 * Format the given named property as title string.
+	 *
+	 * This function looks up the given named property and formats its value
+	 * suitable for use as element caption or description string. It also
+	 * strips any HTML tags from the result.
+	 *
+	 * If the property value is a string, it is passed to `String.format()`
+	 * along with any additional parameters passed to `titleFn()`.
+	 *
+	 * If the property value is a function, it is invoked with any additional
+	 * `titleFn()` parameters as arguments and the obtained return value is
+	 * converted to a string.
+	 *
+	 * In all other cases, `null` is returned.
+	 *
+	 * @param {string} property
+	 * The name of the element property to use.
+	 *
+	 * @param {...*} fmt_args
+	 * Extra values to format the title string with.
+	 *
+	 * @returns {string|null}
+	 * The formatted title string or `null` if the property did not exist or
+	 * was neither a string nor a function.
+	 */
 	titleFn: function(attr /*, ... */) {
 		var s = null;
 
@@ -246,7 +327,34 @@ var CBINode = baseclass.extend({
 	}
 });
 
-var CBIMap = CBINode.extend({
+/**
+ * @constructor Map
+ * @memberof LuCI.form
+ * @augments LuCI.form.AbstractElement
+ *
+ * @classdesc
+ *
+ * The `Map` class represents one complete form. A form usually maps one UCI
+ * configuraton file and is divided into multiple sections containing multiple
+ * fields each.
+ *
+ * It serves as main entry point into the `LuCI.form` for typical view code.
+ *
+ * @param {string} config
+ * The UCI configuration to map. It is automatically loaded along when the
+ * resulting map instance.
+ *
+ * @param {string} [title]
+ * The title caption of the form. A form title is usually rendered as separate
+ * headline element before the actual form contents. If omitted, the
+ * corresponding headline element will not be rendered.
+ *
+ * @param {string} [description]
+ * The description text of the form which is usually rendered as text
+ * paragraph below the form title and before the actual form conents.
+ * If omitted, the corresponding paragraph element will not be rendered.
+ */
+var CBIMap = CBIAbstractElement.extend(/** @lends LuCI.form.Map.prototype */ {
 	__init__: function(config /*, ... */) {
 		this.super('__init__', this.varargs(arguments, 1));
 
@@ -255,6 +363,36 @@ var CBIMap = CBINode.extend({
 		this.data = uci;
 	},
 
+	/**
+	 * Find all DOM nodes within this Map which match the given search
+	 * parameters. This function is essentially a convenience wrapper around
+	 * `querySelectorAll()`.
+	 *
+	 * This function is sensitive to the amount of arguments passed to it;
+	 * if only one argument is specified, it is used as selector-expression
+	 * as-is. When two arguments are passed, the first argument is treated
+	 * as attribute name, the second one as attribute value to match.
+	 *
+	 * As an example, `map.findElements('input')` would find all `<input>`
+	 * nodes while `map.findElements('type', 'text')` would find any DOM node
+	 * with a `type="text"` attribute.
+	 *
+	 * @param {string} selector_or_attrname
+	 * If invoked with only one parameter, this argument is a
+	 * `querySelectorAll()` compatible selector expression. If invoked with
+	 * two parameters, this argument is the attribute name to filter for.
+	 *
+	 * @param {string} [attrvalue]
+	 * In case the function is invoked with two parameters, this argument
+	 * specifies the attribute value to match.
+	 *
+	 * @throws {InternalError}
+	 * Throws an `InternalError` if more than two function parameters are
+	 * passed.
+	 *
+	 * @returns {NodeList}
+	 * Returns a (possibly empty) DOM `NodeList` containing the found DOM nodes.
+	 */
 	findElements: function(/* ... */) {
 		var q = null;
 
@@ -268,16 +406,86 @@ var CBIMap = CBINode.extend({
 		return this.root.querySelectorAll(q);
 	},
 
+	/**
+	 * Find the first DOM node within this Map which matches the given search
+	 * parameters. This function is essentially a convenience wrapper around
+	 * `findElements()` which only returns the first found node.
+	 *
+	 * This function is sensitive to the amount of arguments passed to it;
+	 * if only one argument is specified, it is used as selector-expression
+	 * as-is. When two arguments are passed, the first argument is treated
+	 * as attribute name, the second one as attribute value to match.
+	 *
+	 * As an example, `map.findElement('input')` would find the first `<input>`
+	 * node while `map.findElement('type', 'text')` would find the first DOM
+	 * node with a `type="text"` attribute.
+	 *
+	 * @param {string} selector_or_attrname
+	 * If invoked with only one parameter, this argument is a `querySelector()`
+	 * compatible selector expression. If invoked with two parameters, this
+	 * argument is the attribute name to filter for.
+	 *
+	 * @param {string} [attrvalue]
+	 * In case the function is invoked with two parameters, this argument
+	 * specifies the attribute value to match.
+	 *
+	 * @throws {InternalError}
+	 * Throws an `InternalError` if more than two function parameters are
+	 * passed.
+	 *
+	 * @returns {Node|null}
+	 * Returns the first found DOM node or `null` if no element matched.
+	 */
 	findElement: function(/* ... */) {
 		var res = this.findElements.apply(this, arguments);
 		return res.length ? res[0] : null;
 	},
 
+	/**
+	 * Tie another UCI configuration to the map.
+	 *
+	 * By default, a map instance will only load the UCI configuration file
+	 * specified in the constructor but sometimes access to values from
+	 * further configuration files is required. This function allows for such
+	 * use cases by registering further UCI configuration files which are
+	 * needed by the map.
+	 *
+	 * @param {string} config
+	 * The additional UCI configuration file to tie to the map. If the given
+	 * config already is in the list of required files, it will be ignored.
+	 */
 	chain: function(config) {
 		if (this.parsechain.indexOf(config) == -1)
 			this.parsechain.push(config);
 	},
 
+	/**
+	 * Add a configuration section to the map.
+	 *
+	 * LuCI forms follow the structure of the underlying UCI configurations,
+	 * means that a map, which represents a single UCI configuration, is
+	 * divided into multiple sections which in turn contain an arbitrary
+	 * number of options.
+	 *
+	 * While UCI itself only knows two kinds of sections - named and anonymous
+	 * ones - the form class offers various flavors of form section elements
+	 * to present configuration sections in different ways. Refer to the
+	 * documentation of the different section classes for details.
+	 *
+	 * @param {LuCI.form.AbstractSection} sectionclass
+	 * The section class to use for rendering the configuration section.
+	 * Note that this value must be the class itself, not a class instance
+	 * obtained from calling `new`. It must also be a class dervied from
+	 * `LuCI.form.AbstractSection`.
+	 *
+	 * @param {...string} classargs
+	 * Additional arguments which are passed as-is to the contructor of the
+	 * given section class. Refer to the class specific constructor
+	 * documentation for details.
+	 *
+	 * @returns {LuCI.form.AbstractSection}
+	 * Returns the instantiated section class instance.
+	 */
 	section: function(cbiClass /*, ... */) {
 		if (!CBIAbstractSection.isSubclass(cbiClass))
 			L.error('TypeError', 'Class must be a descendent of CBIAbstractSection');
@@ -287,11 +495,37 @@ var CBIMap = CBINode.extend({
 		return obj;
 	},
 
+	/**
+	 * Load the configuration covered by this map.
+	 *
+	 * The `load()` function first loads all referenced UCI configurations,
+	 * then it recursively walks the form element tree and invokes the
+	 * load function of each child element.
+	 *
+	 * @returns {Promise<void>}
+	 * Returns a promise resolving once the entire form completed loading all
+	 * data. The promise may reject with an error if any configuration failed
+	 * to load or if any of the child elements load functions rejected with
+	 * an error.
+	 */
 	load: function() {
 		return this.data.load(this.parsechain || [ this.config ])
 			.then(this.loadChildren.bind(this));
 	},
 
+	/**
+	 * Parse the form input values.
+	 *
+	 * The `parse()` function recursively walks the form element tree and
+	 * triggers input value reading and validation for each child element.
+	 *
+	 * Elements which are hidden due to unsatisified dependencies are skipped.
+	 *
+	 * @returns {Promise<void>}
+	 * Returns a promise resolving once the entire form completed parsing all
+	 * input values. The returned promise is rejected if any parsed values are
+	 * not meeting the validation constraints of their respective elements.
+	 */
 	parse: function() {
 		var tasks = [];
 
@@ -302,6 +536,26 @@ var CBIMap = CBINode.extend({
 		return Promise.all(tasks);
 	},
 
+	/**
+	 * Save the form input values.
+	 *
+	 * This function parses the current form, saves the resulting UCI changes,
+	 * reloads the UCI configuration data and redraws the form elements.
+	 *
+	 * @param {function} [cb]
+	 * An optional callback function that is invoked after the form is parsed
+	 * but before the changed UCI data is saved. This is useful to perform
+	 * additional data manipulation steps before saving the changes.
+	 *
+	 * @param {boolean} [silent=false]
+	 * If set to `true`, trigger an alert message to the user in case saving
+	 * the form data failes. Otherwise fail silently.
+	 *
+	 * @returns {Promise<void>}
+	 * Returns a promise resolving once the entire save operation is complete.
+	 * The returned promise is rejected if any step of the save operation
+	 * failed.
+	 */
 	save: function(cb, silent) {
 		this.checkDepends();
 
@@ -317,14 +571,30 @@ var CBIMap = CBINode.extend({
 			}).finally(this.renderContents.bind(this));
 	},
 
+	/**
+	 * Reset the form by re-rendering its contents. This will revert all
+	 * unsaved user inputs to their initial form state.
+	 *
+	 * @returns {Promise<Node>}
+	 * Returns a promise resolving to the toplevel form DOM node once the
+	 * re-rendering is complete.
+	 */
 	reset: function() {
 		return this.renderContents();
 	},
 
+	/**
+	 * Render the form markup.
+	 *
+	 * @returns {Promise<Node>}
+	 * Returns a promise resolving to the toplevel form DOM node once the
+	 * rendering is complete.
+	 */
 	render: function() {
 		return this.load().then(this.renderContents.bind(this));
 	},
 
+	/** @private */
 	renderContents: function() {
 		var mapEl = this.root || (this.root = E('div', {
 			'id': 'cbi-%s'.format(this.config),
@@ -369,6 +639,25 @@ var CBIMap = CBINode.extend({
 		}, this));
 	},
 
+	/**
+	 * Find a form option element instance.
+	 *
+	 * @param {string} name_or_id
+	 * The name or the full ID of the option element to look up.
+	 *
+	 * @param {string} [section_id]
+	 * The ID of the UCI section containing the option to look up. May be
+	 * omitted if a full ID is passed as first argument.
+	 *
+	 * @param {string} [config]
+	 * The name of the UCI configuration the option instance is belonging to.
+	 * Defaults to the main UCI configuration of the map if omitted.
+	 *
+	 * @returns {Array<LuCI.form.AbstractValue,string>|null}
+	 * Returns a two-element array containing the form option instance as
+	 * first item and the corresponding UCI section ID as second item.
+	 * Returns `null` if the option could not be found.
+	 */
 	lookupOption: function(name, section_id, config_name) {
 		var id, elem, sid, inst;
 
@@ -384,6 +673,7 @@ var CBIMap = CBINode.extend({
 		return (inst instanceof CBIAbstractValue) ? [ inst, sid ] : null;
 	},
 
+	/** @private */
 	checkDepends: function(ev, n) {
 		var changed = false;
 
@@ -397,6 +687,7 @@ var CBIMap = CBINode.extend({
 		ui.tabs.updateTabs(ev, this.root);
 	},
 
+	/** @private */
 	isDependencySatisfied: function(depends, config_name, section_id) {
 		var def = false;
 
@@ -436,7 +727,34 @@ var CBIMap = CBINode.extend({
 	}
 });
 
-var CBIJSONMap = CBIMap.extend({
+/**
+ * @constructor JSONMap
+ * @memberof LuCI.form
+ * @augments LuCI.form.Map
+ *
+ * @classdesc
+ *
+ * A `JSONMap` class functions similar to [LuCI.form.Map]{@link LuCI.form.Map}
+ * but uses a multidimensional JavaScript object instead of UCI configuration
+ * as data source.
+ *
+ * @param {Object<string, Object<string, *>|Array<Object<string, *>>>} data
+ * The JavaScript object to use as data source. Internally, the object is
+ * converted into an UCI-like format. Its toplevel keys are treated like UCI
+ * section types while the object or array-of-object values are treated as
+ * section contents.
+ *
+ * @param {string} [title]
+ * The title caption of the form. A form title is usually rendered as separate
+ * headline element before the actual form contents. If omitted, the
+ * corresponding headline element will not be rendered.
+ *
+ * @param {string} [description]
+ * The description text of the form which is usually rendered as text
+ * paragraph below the form title and before the actual form conents.
+ * If omitted, the corresponding paragraph element will not be rendered.
+ */
+var CBIJSONMap = CBIMap.extend(/** @lends LuCI.form.JSONMap.prototype */ {
 	__init__: function(data /*, ... */) {
 		this.super('__init__', this.varargs(arguments, 1, 'json'));
 
@@ -446,7 +764,21 @@ var CBIJSONMap = CBIMap.extend({
 	}
 });
 
-var CBIAbstractSection = CBINode.extend({
+/**
+ * @class AbstractSection
+ * @memberof LuCI.form
+ * @augments LuCI.form.AbstractElement
+ * @hideconstructor
+ * @classdesc
+ *
+ * The `AbstractSection` class serves as abstract base for the different form
+ * section styles implemented by `LuCI.form`. It provides the common logic for
+ * enumerating underlying configuration section instances, for registering
+ * form options and for handling tabs to segment child options.
+ *
+ * This class is private and not directly accessible by user code.
+ */
+var CBIAbstractSection = CBIAbstractElement.extend(/** @lends LuCI.form.AbstractSection.prototype */ {
 	__init__: function(map, sectionType /*, ... */) {
 		this.super('__init__', this.varargs(arguments, 2));
 
@@ -459,14 +791,68 @@ var CBIAbstractSection = CBINode.extend({
 		this.dynamic = false;
 	},
 
+	/**
+	 * Access the parent option container instance.
+	 *
+	 * In case this section is nested within an option element container,
+	 * this property will hold a reference to the parent option instance.
+	 *
+	 * If this section is not nested, the property is `null`.
+	 *
+	 * @name LuCI.form.AbstractSection.prototype#parentoption
+	 * @type LuCI.form.AbstractValue
+	 * @readonly
+	 */
+
+	/**
+	 * Enumerate the UCI section IDs covered by this form section element.
+	 *
+	 * @abstract
+	 * @throws {InternalError}
+	 * Throws an `InternalError` exception if the function is not implemented.
+	 *
+	 * @returns {string[]}
+	 * Returns an array of UCI section IDs covered by this form element.
+	 * The sections will be rendered in the same order as the returned array.
+	 */
 	cfgsections: function() {
 		L.error('InternalError', 'Not implemented');
 	},
 
+	/**
+	 * Filter UCI section IDs to render.
+	 *
+	 * The filter function is invoked for each UCI section ID of a given type
+	 * and controls whether the given UCI section is rendered or ignored by
+	 * the form section element.
+	 *
+	 * The default implementation always returns `true`. User code or
+	 * classes extending `AbstractSection` may overwrite this function with
+	 * custom implementations.
+	 *
+	 * @abstract
+	 * @param {string} section_id
+	 * The UCI section ID to test.
+	 *
+	 * @returns {boolean}
+	 * Returns `true` when the given UCI section ID should be handled and
+	 * `false` when it should be ignored.
+	 */
 	filter: function(section_id) {
 		return true;
 	},
 
+	/**
+	 * Load the configuration covered by this section.
+	 *
+	 * The `load()` function recursively walks the section element tree and
+	 * invokes the load function of each child option element.
+	 *
+	 * @returns {Promise<void>}
+	 * Returns a promise resolving once the values of all child elements have
+	 * been loaded. The promise may reject with an error if any of the child
+	 * elements load functions rejected with an error.
+	 */
 	load: function() {
 		var section_ids = this.cfgsections(),
 		    tasks = [];
@@ -482,6 +868,20 @@ var CBIAbstractSection = CBINode.extend({
 		return Promise.all(tasks);
 	},
 
+	/**
+	 * Parse this sections form input.
+	 *
+	 * The `parse()` function recursively walks the section element tree and
+	 * triggers input value reading and validation for each encountered child
+	 * option element.
+	 *
+	 * Options which are hidden due to unsatisified dependencies are skipped.
+	 *
+	 * @returns {Promise<void>}
+	 * Returns a promise resolving once the values of all child elements have
+	 * been parsed. The returned promise is rejected if any parsed values are
+	 * not meeting the validation constraints of their respective elements.
+	 */
 	parse: function() {
 		var section_ids = this.cfgsections(),
 		    tasks = [];
@@ -494,6 +894,35 @@ var CBIAbstractSection = CBINode.extend({
 		return Promise.all(tasks);
 	},
 
+	/**
+	 * Add an option tab to the section.
+	 *
+	 * The child option elements of a section may be divided into multiple
+	 * tabs to provide a better overview to the user.
+	 *
+	 * Before options can be moved into a tab pane, the corresponding tab
+	 * has to be defined first, which is done by calling this function.
+	 *
+	 * Note that once tabs are defined, user code must use the `taboption()`
+	 * method to add options to specific tabs. Option elements added by
+	 * `option()` will not be assigned to any tab and not be rendered in this
+	 * case.
+	 *
+	 * @param {string} name
+	 * The name of the tab to register. It may be freely chosen and just serves
+	 * as an identifier to differentiate tabs.
+	 *
+	 * @param {string} title
+	 * The human readable caption of the tab.
+	 *
+	 * @param {string} [description]
+	 * An additional description text for the corresponding tab pane. It is
+	 * displayed as text paragraph below the tab but before the tab pane
+	 * contents. If omitted, no description will be rendered.
+	 *
+	 * @throws {Error}
+	 * Throws an exeption if a tab with the same `name` already exists.
+	 */
 	tab: function(name, title, description) {
 		if (this.tabs && this.tabs[name])
 			throw 'Tab already declared';
@@ -513,6 +942,30 @@ var CBIAbstractSection = CBINode.extend({
 		this.tab_names.push(name);
 	},
 
+	/**
+	 * Add a configuration option widget to the section.
+	 *
+	 * Note that [taboption()]{@link LuCI.form.AbstractSection#taboption}
+	 * should be used instead if this form section element uses tabs.
+	 *
+	 * @param {LuCI.form.AbstractValue} optionclass
+	 * The option class to use for rendering the configuration option. Note
+	 * that this value must be the class itself, not a class instance obtained
+	 * from calling `new`. It must also be a class dervied from
+	 * [LuCI.form.AbstractSection]{@link LuCI.form.AbstractSection}.
+	 *
+	 * @param {...*} classargs
+	 * Additional arguments which are passed as-is to the contructor of the
+	 * given option class. Refer to the class specific constructor
+	 * documentation for details.
+	 *
+	 * @throws {TypeError}
+	 * Throws a `TypeError` exception in case the passed class value is not a
+	 * descendent of `AbstractValue`.
+	 *
+	 * @returns {LuCI.form.AbstractValue}
+	 * Returns the instantiated option class instance.
+	 */
 	option: function(cbiClass /*, ... */) {
 		if (!CBIAbstractValue.isSubclass(cbiClass))
 			throw L.error('TypeError', 'Class must be a descendent of CBIAbstractValue');
@@ -522,6 +975,34 @@ var CBIAbstractSection = CBINode.extend({
 		return obj;
 	},
 
+	/**
+	 * Add a configuration option widget to a tab of the section.
+	 *
+	 * @param {string} tabname
+	 * The name of the section tab to add the option element to.
+	 *
+	 * @param {LuCI.form.AbstractValue} optionclass
+	 * The option class to use for rendering the configuration option. Note
+	 * that this value must be the class itself, not a class instance obtained
+	 * from calling `new`. It must also be a class dervied from
+	 * [LuCI.form.AbstractSection]{@link LuCI.form.AbstractSection}.
+	 *
+	 * @param {...*} classargs
+	 * Additional arguments which are passed as-is to the contructor of the
+	 * given option class. Refer to the class specific constructor
+	 * documentation for details.
+	 *
+	 * @throws {ReferenceError}
+	 * Throws a `ReferenceError` exception when the given tab name does not
+	 * exist.
+	 *
+	 * @throws {TypeError}
+	 * Throws a `TypeError` exception in case the passed class value is not a
+	 * descendent of `AbstractValue`.
+	 *
+	 * @returns {LuCI.form.AbstractValue}
+	 * Returns the instantiated option class instance.
+	 */
 	taboption: function(tabName /*, ... */) {
 		if (!this.tabs || !this.tabs[tabName])
 			throw L.error('ReferenceError', 'Associated tab not declared');
@@ -532,6 +1013,7 @@ var CBIAbstractSection = CBINode.extend({
 		return obj;
 	},
 
+	/** @private */
 	renderUCISection: function(section_id) {
 		var renderTasks = [];
 
@@ -545,6 +1027,7 @@ var CBIAbstractSection = CBINode.extend({
 			.then(this.renderTabContainers.bind(this, section_id));
 	},
 
+	/** @private */
 	renderTabContainers: function(section_id, nodes) {
 		var config_name = this.uciconfig || this.map.config,
 		    containerEls = E([]);
@@ -570,6 +1053,7 @@ var CBIAbstractSection = CBINode.extend({
 		return containerEls;
 	},
 
+	/** @private */
 	renderOptions: function(tab_name, section_id) {
 		var in_table = (this instanceof CBITableSection);
 		return this.renderChildren(tab_name, section_id, in_table).then(function(nodes) {
@@ -580,6 +1064,7 @@ var CBIAbstractSection = CBINode.extend({
 		});
 	},
 
+	/** @private */
 	checkDepends: function(ev, n) {
 		var changed = false,
 		    sids = this.cfgsections();
@@ -657,7 +1142,21 @@ var isContained = function(x, y) {
 	return false;
 };
 
-var CBIAbstractValue = CBINode.extend({
+/**
+ * @class AbstractValue
+ * @memberof LuCI.form
+ * @augments LuCI.form.AbstractElement
+ * @hideconstructor
+ * @classdesc
+ *
+ * The `AbstractValue` class serves as abstract base for the different form
+ * option styles implemented by `LuCI.form`. It provides the common logic for
+ * handling option input values, for dependencies among options and for
+ * validation constraints that should be applied to entered values.
+ *
+ * This class is private and not directly accessible by user code.
+ */
+var CBIAbstractValue = CBIAbstractElement.extend(/** @lends LuCI.form.AbstractValue.prototype */ {
 	__init__: function(map, section, option /*, ... */) {
 		this.super('__init__', this.varargs(arguments, 3));
 
@@ -674,6 +1173,237 @@ var CBIAbstractValue = CBINode.extend({
 		this.optional = false;
 	},
 
+	/**
+	 * If set to `false`, the underlying option value is retained upon saving
+	 * the form when the option element is disabled due to unsatisfied
+	 * dependency constraints.
+	 *
+	 * @name LuCI.form.AbstractValue.prototype#rmempty
+	 * @type boolean
+	 * @default true
+	 */
+
+	/**
+	 * If set to `true`, the underlying ui input widget is allowed to be empty,
+	 * otherwise the option element is marked invalid when no value is entered
+	 * or selected by the user.
+	 *
+	 * @name LuCI.form.AbstractValue.prototype#optional
+	 * @type boolean
+	 * @default false
+	 */
+
+	/**
+	 * Sets a default value to use when the underlying UCI option is not set.
+	 *
+	 * @name LuCI.form.AbstractValue.prototype#default
+	 * @type *
+	 * @default null
+	 */
+
+	/**
+	 * Specifies a datatype constraint expression to validate input values
+	 * against. Refer to {@link LuCI.validation} for details on the format.
+	 *
+	 * If the user entered input does not match the datatype validation, the
+	 * option element is marked as invalid.
+	 *
+	 * @name LuCI.form.AbstractValue.prototype#datatype
+	 * @type string
+	 * @default null
+	 */
+
+	/**
+	 * Specifies a custom validation function to test the user input for
+	 * validity. The validation function must return `true` to accept the
+	 * value. Any other return value type is converted to a string and
+	 * displayed to the user as validation error message.
+	 *
+	 * If the user entered input does not pass the validation function, the
+	 * option element is marked as invalid.
+	 *
+	 * @name LuCI.form.AbstractValue.prototype#validate
+	 * @type function
+	 * @default null
+	 */
+
+	/**
+	 * Override the UCI configuration name to read the option value from.
+	 *
+	 * By default, the configuration name is inherited from the parent Map.
+	 * By setting this property, a deviating configuration may be specified.
+	 *
+	 * The default is null, means inheriting from the parent form.
+	 *
+	 * @name LuCI.form.AbstractValue.prototype#uciconfig
+	 * @type string
+	 * @default null
+	 */
+
+	/**
+	 * Override the UCI section name to read the option value from.
+	 *
+	 * By default, the section ID is inherited from the parent section element.
+	 * By setting this property, a deviating section may be specified.
+	 *
+	 * The default is null, means inheriting from the parent section.
+	 *
+	 * @name LuCI.form.AbstractValue.prototype#ucisection
+	 * @type string
+	 * @default null
+	 */
+
+	/**
+	 * Override the UCI option name to read the value from.
+	 *
+	 * By default, the elements name, which is passed as third argument to
+	 * the constructor, is used as UCI option name. By setting this property,
+	 * a deviating UCI option may be specified.
+	 *
+	 * The default is null, means using the option element name.
+	 *
+	 * @name LuCI.form.AbstractValue.prototype#ucioption
+	 * @type string
+	 * @default null
+	 */
+
+	/**
+	 * Mark grid section option element as editable.
+	 *
+	 * Options which are displayed in the table portion of a `GridSection`
+	 * instance are rendered as readonly text by default. By setting the
+	 * `editable` property of a child option element to `true`, that element
+	 * is rendered as full input widget within its cell instead of a text only
+	 * preview.
+	 *
+	 * This property has no effect on options that are not children of grid
+	 * section elements.
+	 *
+	 * @name LuCI.form.AbstractValue.prototype#editable
+	 * @type boolean
+	 * @default false
+	 */
+
+	/**
+	 * Move grid section option element into the table, the modal popup or both.
+	 *
+	 * If this property is `null` (the default), the option element is
+	 * displayed in both the table preview area and the per-section instance
+	 * modal popup of a grid section. When it is set to `false` the option
+	 * is only shown in the table but not the modal popup. When set to `true`,
+	 * the option is only visible in the modal popup but not the table.
+	 *
+	 * This property has no effect on options that are not children of grid
+	 * section elements.
+	 *
+	 * @name LuCI.form.AbstractValue.prototype#modalonly
+	 * @type boolean
+	 * @default null
+	 */
+
+	/**
+	 * Override the cell width of a table or grid section child option.
+	 *
+	 * If the property is set to a numeric value, it is treated as pixel width
+	 * which is set on the containing cell element of the option, essentially
+	 * forcing a certain column width. When the property is set to a string
+	 * value, it is applied as-is to the CSS `width` property.
+	 *
+	 * This property has no effect on options that are not children of grid or
+	 * table section elements.
+	 *
+	 * @name LuCI.form.AbstractValue.prototype#width
+	 * @type number|string
+	 * @default null
+	 */
+
+	/**
+	 * Add a dependency contraint to the option.
+	 *
+	 * Dependency constraints allow making the presence of option elements
+	 * dependant on the current values of certain other options within the
+	 * same form. An option element with unsatisfied dependencies will be
+	 * hidden from the view and its current value is omitted when saving.
+	 *
+	 * Multiple constraints (that is, multiple calls to `depends()`) are
+	 * treated as alternatives, forming a logical "or" expression.
+	 *
+	 * By passing an object of name => value pairs as first argument, it is
+	 * possible to depend on multiple options simultaneously, allowing to form
+	 * a logical "and" expression.
+	 *
+	 * Option names may be given in "dot notation" which allows to reference
+	 * option elements outside of the current form section. If a name without
+	 * dot is specified, it refers to an option within the same configuration
+	 * section. If specified as <code>configname.sectionid.optionname</code>,
+	 * options anywhere within the same form may be specified.
+	 *
+	 * The object notation also allows for a number of special keys which are
+	 * not treated as option names but as modifiers to influence the dependency
+	 * constraint evaluation. The associated value of these special "tag" keys
+	 * is ignored. The recognized tags are:
+	 *
+	 * <ul>
+	 *   <li>
+	 *    <code>!reverse</code><br>
+	 *    Invert the dependency, instead of requiring another option to be
+	 *    equal to the dependency value, that option should <em>not</em> be
+	 *    equal.
+	 *   </li>
+	 *   <li>
+	 *    <code>!contains</code><br>
+	 *    Instead of requiring an exact match, the dependency is considered
+	 *    satisfied when the dependency value is contained within the option
+	 *    value.
+	 *   </li>
+	 *   <li>
+	 *    <code>!default</code><br>
+	 *    The dependency is always satisfied
+	 *   </li>
+	 * </ul>
+	 *
+	 * Examples:
+	 *
+	 * <ul>
+	 *  <li>
+	 *   <code>opt.depends("foo", "test")</code><br>
+	 *   Require the value of `foo` to be `test`.
+	 *  </li>
+	 *  <li>
+	 *   <code>opt.depends({ foo: "test" })</code><br>
+	 *   Equivalent to the previous example.
+	 *  </li>
+	 *  <li>
+	 *   <code>opt.depends({ foo: "test", bar: "qrx" })</code><br>
+	 *   Require the value of `foo` to be `test` and the value of `bar` to be
+	 *   `qrx`.
+	 *  </li>
+	 *  <li>
+	 *   <code>opt.depends({ foo: "test" })<br>
+	 *         opt.depends({ bar: "qrx" })</code><br>
+	 *   Require either <code>foo</code> to be set to <code>test</code>,
+	 *   <em>or</em> the <code>bar</code> option to be <code>qrx</code>.
+	 *  </li>
+	 *  <li>
+	 *   <code>opt.depends("test.section1.foo", "bar")</code><br>
+	 *   Require the "foo" form option within the "section1" section to be
+	 *   set to "bar".
+	 *  </li>
+	 *  <li>
+	 *   <code>opt.depends({ foo: "test", "!contains": true })</code><br>
+	 *   Require the "foo" option value to contain the substring "test".
+	 *  </li>
+	 * </ul>
+	 *
+	 * @param {string|Object<string, string|boolean>} optionname_or_depends
+	 * The name of the option to depend on or an object describing multiple
+	 * dependencies which must be satified (a logical "and" expression).
+	 *
+	 * @param {string} optionvalue
+	 * When invoked with a plain option name as first argument, this parameter
+	 * specifies the expected value. In case an object is passed as first
+	 * argument, this parameter is ignored.
+	 */
 	depends: function(field, value) {
 		var deps;
 
@@ -685,6 +1415,7 @@ var CBIAbstractValue = CBINode.extend({
 		this.deps.push(deps);
 	},
 
+	/** @private */
 	transformDepList: function(section_id, deplist) {
 		var list = deplist || this.deps,
 		    deps = [];
@@ -720,6 +1451,7 @@ var CBIAbstractValue = CBINode.extend({
 		return deps;
 	},
 
+	/** @private */
 	transformChoices: function() {
 		if (!Array.isArray(this.keylist) || this.keylist.length == 0)
 			return null;
@@ -732,6 +1464,7 @@ var CBIAbstractValue = CBINode.extend({
 		return choices;
 	},
 
+	/** @private */
 	checkDepends: function(section_id) {
 		var config_name = this.uciconfig || this.section.uciconfig || this.map.config,
 		    active = this.map.isDependencySatisfied(this.deps, config_name, section_id);
@@ -742,6 +1475,7 @@ var CBIAbstractValue = CBINode.extend({
 		return active;
 	},
 
+	/** @private */
 	updateDefaultValue: function(section_id) {
 		if (!L.isObject(this.defaults))
 			return;
@@ -771,6 +1505,23 @@ var CBIAbstractValue = CBINode.extend({
 		this.default = satisified_defval;
 	},
 
+	/**
+	 * Obtain the internal ID ("cbid") of the element instance.
+	 *
+	 * Since each form section element may map multiple underlying
+	 * configuration sections, the configuration section ID is required to
+	 * form a fully qualified ID pointing to the specific element instance
+	 * within the given specific section.
+	 *
+	 * @param {string} section_id
+	 * The configuration section ID
+	 *
+	 * @throws {TypeError}
+	 * Throws a `TypeError` exception when no `section_id` was specified.
+	 *
+	 * @returns {string}
+	 * Returns the element ID.
+	 */
 	cbid: function(section_id) {
 		if (section_id == null)
 			L.error('TypeError', 'Section ID required');
@@ -780,6 +1531,25 @@ var CBIAbstractValue = CBINode.extend({
 			section_id, this.option);
 	},
 
+	/**
+	 * Load the underlying configuration value.
+	 *
+	 * The default implementation of this method reads and returns the
+	 * underlying UCI option value (or the related JavaScript property for
+	 * `JSONMap` instances). It may be overwritten by user code to load data
+	 * from nonstandard sources.
+	 *
+	 * @param {string} section_id
+	 * The configuration section ID
+	 *
+	 * @throws {TypeError}
+	 * Throws a `TypeError` exception when no `section_id` was specified.
+	 *
+	 * @returns {*|Promise<*>}
+	 * Returns the configuration value to initialize the option element with.
+	 * The return value of this function is filtered through `Promise.resolve()`
+	 * so it may return promises if overridden by user code.
+	 */
 	load: function(section_id) {
 		if (section_id == null)
 			L.error('TypeError', 'Section ID required');
@@ -790,12 +1560,42 @@ var CBIAbstractValue = CBINode.extend({
 			this.ucioption || this.option);
 	},
 
+	/**
+	 * Obtain the underlying `LuCI.ui` element instance.
+	 *
+	 * @param {string} section_id
+	 * The configuration section ID
+	 *
+	 * @throws {TypeError}
+	 * Throws a `TypeError` exception when no `section_id` was specified.
+	 *
+	 * @return {LuCI.ui.AbstractElement|null}
+	 * Returns the `LuCI.ui` element instance or `null` in case the form
+	 * option implementation does not use `LuCI.ui` widgets.
+	 */
 	getUIElement: function(section_id) {
 		var node = this.map.findElement('id', this.cbid(section_id)),
 		    inst = node ? dom.findClassInstance(node) : null;
 		return (inst instanceof ui.AbstractElement) ? inst : null;
 	},
 
+	/**
+	 * Query the underlying configuration value.
+	 *
+	 * The default implementation of this method returns the cached return
+	 * value of [load()]{@link LuCI.form.AbstractValue#load}. It may be
+	 * overwritten by user code to obtain the configuration value in a
+	 * different way.
+	 *
+	 * @param {string} section_id
+	 * The configuration section ID
+	 *
+	 * @throws {TypeError}
+	 * Throws a `TypeError` exception when no `section_id` was specified.
+	 *
+	 * @returns {*}
+	 * Returns the configuration value.
+	 */
 	cfgvalue: function(section_id, set_value) {
 		if (section_id == null)
 			L.error('TypeError', 'Section ID required');
@@ -808,11 +1608,46 @@ var CBIAbstractValue = CBINode.extend({
 		return this.data ? this.data[section_id] : null;
 	},
 
+	/**
+	 * Query the current form input value.
+	 *
+	 * The default implementation of this method returns the current input
+	 * value of the underlying [LuCI.ui]{@link LuCI.ui.AbstractElement} widget.
+	 * It may be overwritten by user code to handle input values differently.
+	 *
+	 * @param {string} section_id
+	 * The configuration section ID
+	 *
+	 * @throws {TypeError}
+	 * Throws a `TypeError` exception when no `section_id` was specified.
+	 *
+	 * @returns {*}
+	 * Returns the current input value.
+	 */
 	formvalue: function(section_id) {
 		var elem = this.getUIElement(section_id);
 		return elem ? elem.getValue() : null;
 	},
 
+	/**
+	 * Obtain a textual input representation.
+	 *
+	 * The default implementation of this method returns the HTML escaped
+	 * current input value of the underlying
+	 * [LuCI.ui]{@link LuCI.ui.AbstractElement} widget. User code or specific
+	 * option element implementations may overwrite this function to apply a
+	 * different logic, e.g. to return `Yes` or `No` depending on the checked
+	 * state of checkbox elements.
+	 *
+	 * @param {string} section_id
+	 * The configuration section ID
+	 *
+	 * @throws {TypeError}
+	 * Throws a `TypeError` exception when no `section_id` was specified.
+	 *
+	 * @returns {string}
+	 * Returns the text representation of the current input value.
+	 */
 	textvalue: function(section_id) {
 		var cval = this.cfgvalue(section_id);
 
@@ -822,20 +1657,67 @@ var CBIAbstractValue = CBINode.extend({
 		return (cval != null) ? '%h'.format(cval) : null;
 	},
 
+	/**
+	 * Apply custom validation logic.
+	 *
+	 * This method is invoked whenever incremental validation is performed on
+	 * the user input, e.g. on keyup or blur events.
+	 *
+	 * The default implementation of this method does nothing and always
+	 * returns `true`. User code may overwrite this method to provide
+	 * additional validation logic which is not covered by data type
+	 * constraints.
+	 *
+	 * @abstract
+	 * @param {string} section_id
+	 * The configuration section ID
+	 *
+	 * @param {*} value
+	 * The value to validate
+	 *
+	 * @returns {*}
+	 * The method shall return `true` to accept the given value. Any other
+	 * return value is treated as failure, converted to a string and displayed
+	 * as error message to the user.
+	 */
 	validate: function(section_id, value) {
 		return true;
 	},
 
+	/**
+	 * Test whether the input value is currently valid.
+	 *
+	 * @param {string} section_id
+	 * The configuration section ID
+	 *
+	 * @returns {boolean}
+	 * Returns `true` if the input value currently is valid, otherwise it
+	 * returns `false`.
+	 */
 	isValid: function(section_id) {
 		var elem = this.getUIElement(section_id);
 		return elem ? elem.isValid() : true;
 	},
 
+	/**
+	 * Test whether the option element is currently active.
+	 *
+	 * An element is active when it is not hidden due to unsatisfied dependency
+	 * constraints.
+	 *
+	 * @param {string} section_id
+	 * The configuration section ID
+	 *
+	 * @returns {boolean}
+	 * Returns `true` if the option element currently is active, otherwise it
+	 * returns `false`.
+	 */
 	isActive: function(section_id) {
 		var field = this.map.findElement('data-field', this.cbid(section_id));
 		return (field != null && !field.classList.contains('hidden'));
 	},
 
+	/** @private */
 	setActive: function(section_id, active) {
 		var field = this.map.findElement('data-field', this.cbid(section_id));
 
@@ -847,11 +1729,26 @@ var CBIAbstractValue = CBINode.extend({
 		return false;
 	},
 
+	/** @private */
 	triggerValidation: function(section_id) {
 		var elem = this.getUIElement(section_id);
 		return elem ? elem.triggerValidation() : true;
 	},
 
+	/**
+	 * Parse the option element input.
+	 *
+	 * The function is invoked when the `parse()` method has been invoked on
+	 * the parent form and triggers input value reading and validation.
+	 *
+	 * @param {string} section_id
+	 * The configuration section ID
+	 *
+	 * @returns {Promise<void>}
+	 * Returns a promise resolving once the input value has been read and
+	 * validated or rejecting in case the input value does not meet the
+	 * validation constraints.
+	 */
 	parse: function(section_id) {
 		var active = this.isActive(section_id),
 		    cval = this.cfgvalue(section_id),
@@ -877,6 +1774,26 @@ var CBIAbstractValue = CBINode.extend({
 		return Promise.resolve();
 	},
 
+	/**
+	 * Write the current input value into the configuration.
+	 *
+	 * This function is invoked upon saving the parent form when the option
+	 * element is valid and when its input value has been changed compared to
+	 * the initial value returned by
+	 * [cfgvalue()]{@link LuCI.form.AbstractValue#cfgvalue}.
+	 *
+	 * The default implementation simply sets the given input value in the
+	 * UCI configuration (or the associated JavaScript object property in
+	 * case of `JSONMap` forms). It may be overwritten by user code to
+	 * implement alternative save logic, e.g. to transform the input value
+	 * before it is written.
+	 *
+	 * @param {string} section_id
+	 * The configuration section ID
+	 *
+	 * @param {string|string[]}	formvalue
+	 * The input value to write.
+	 */
 	write: function(section_id, formvalue) {
 		return this.map.data.set(
 			this.uciconfig || this.section.uciconfig || this.map.config,
@@ -885,6 +1802,21 @@ var CBIAbstractValue = CBINode.extend({
 			formvalue);
 	},
 
+	/**
+	 * Remove the corresponding value from the configuration.
+	 *
+	 * This function is invoked upon saving the parent form when the option
+	 * element has been hidden due to unsatisfied dependencies or when the
+	 * user cleared the input value and the option is marked optional.
+	 *
+	 * The default implementation simply removes the associated option from the
+	 * UCI configuration (or the associated JavaScript object property in
+	 * case of `JSONMap` forms). It may be overwritten by user code to
+	 * implement alternative removal logic, e.g. to retain the original value.
+	 *
+	 * @param {string} section_id
+	 * The configuration section ID
+	 */
 	remove: function(section_id) {
 		return this.map.data.unset(
 			this.uciconfig || this.section.uciconfig || this.map.config,
@@ -893,15 +1825,101 @@ var CBIAbstractValue = CBINode.extend({
 	}
 });
 
-var CBITypedSection = CBIAbstractSection.extend({
+/**
+ * @class TypedSection
+ * @memberof LuCI.form
+ * @augments LuCI.form.AbstractSection
+ * @hideconstructor
+ * @classdesc
+ *
+ * The `TypedSection` class maps all or - if `filter()` is overwritten - a
+ * subset of the underlying UCI configuration sections of a given type.
+ *
+ * Layout wise, the configuration section instances mapped by the section
+ * element (sometimes referred to as "section nodes") are stacked beneath
+ * each other in a single column, with an optional section remove button next
+ * to each section node and a section add button at the end, depending on the
+ * value of the `addremove` property.
+ *
+ * @param {LuCI.form.Map|LuCI.form.JSONMap} form
+ * The configuration form this section is added to. It is automatically passed
+ * by [section()]{@link LuCI.form.Map#section}.
+ *
+ * @param {string} section_type
+ * The type of the UCI section to map.
+ *
+ * @param {string} [title]
+ * The title caption of the form section element.
+ *
+ * @param {string} [description]
+ * The description text of the form section element.
+ */
+var CBITypedSection = CBIAbstractSection.extend(/** @lends LuCI.form.TypedSection.prototype */ {
 	__name__: 'CBI.TypedSection',
 
+	/**
+	 * If set to `true`, the user may add or remove instances from the form
+	 * section widget, otherwise only preexisting sections may be edited.
+	 * The default is `false`.
+	 *
+	 * @name LuCI.form.TypedSection.prototype#addremove
+	 * @type boolean
+	 * @default false
+	 */
+
+	/**
+	 * If set to `true`, mapped section instances are treated as anonymous
+	 * UCI sections, which means that section instance elements will be
+	 * rendered without title element and that no name is required when adding
+	 * new sections. The default is `false`.
+	 *
+	 * @name LuCI.form.TypedSection.prototype#anonymous
+	 * @type boolean
+	 * @default false
+	 */
+
+	/**
+	 * When set to `true`, instead of rendering section instances one below
+	 * another, treat each instance as separate tab pane and render a tab menu
+	 * at the top of the form section element, allowing the user to switch
+	 * among instances. The default is `false`.
+	 *
+	 * @name LuCI.form.TypedSection.prototype#tabbed
+	 * @type boolean
+	 * @default false
+	 */
+
+	/**
+	 * Override the caption used for the section add button at the bottom of
+	 * the section form element. If set to a string, it will be used as-is,
+	 * if set to a function, the function will be invoked and its return value
+	 * is used as caption, after converting it to a string. If this property
+	 * is not set, the default is `Add`.
+	 *
+	 * @name LuCI.form.TypedSection.prototype#addbtntitle
+	 * @type string|function
+	 * @default null
+	 */
+
+	/**
+	 * Override the UCI configuration name to read the section IDs from. By
+	 * default, the configuration name is inherited from the parent `Map`.
+	 * By setting this property, a deviating configuration may be specified.
+	 * The default is `null`, means inheriting from the parent form.
+	 *
+	 * @name LuCI.form.TypedSection.prototype#uciconfig
+	 * @type string
+	 * @default null
+	 */
+
+	/** @override */
 	cfgsections: function() {
 		return this.map.data.sections(this.uciconfig || this.map.config, this.sectiontype)
 			.map(function(s) { return s['.name'] })
 			.filter(L.bind(this.filter, this));
 	},
 
+	/** @private */
 	handleAdd: function(ev, name) {
 		var config_name = this.uciconfig || this.map.config;
 
@@ -909,6 +1927,7 @@ var CBITypedSection = CBIAbstractSection.extend({
 		return this.map.save(null, true);
 	},
 
+	/** @private */
 	handleRemove: function(section_id, ev) {
 		var config_name = this.uciconfig || this.map.config;
 
@@ -916,6 +1935,7 @@ var CBITypedSection = CBIAbstractSection.extend({
 		return this.map.save(null, true);
 	},
 
+	/** @private */
 	renderSectionAdd: function(extra_class) {
 		if (!this.addremove)
 			return E([]);
@@ -962,6 +1982,7 @@ var CBITypedSection = CBIAbstractSection.extend({
 		return createEl;
 	},
 
+	/** @private */
 	renderSectionPlaceholder: function() {
 		return E([
 			E('em', _('This section contains no values yet')),
@@ -969,6 +1990,7 @@ var CBITypedSection = CBIAbstractSection.extend({
 		]);
 	},
 
+	/** @private */
 	renderContents: function(cfgsections, nodes) {
 		var section_id = null,
 		    config_name = this.uciconfig || this.map.config,
@@ -1018,6 +2040,7 @@ var CBITypedSection = CBIAbstractSection.extend({
 		return sectionEl;
 	},
 
+	/** @override */
 	render: function() {
 		var cfgsections = this.cfgsections(),
 		    renderTasks = [];
@@ -1029,13 +2052,175 @@ var CBITypedSection = CBIAbstractSection.extend({
 	}
 });
 
-var CBITableSection = CBITypedSection.extend({
+/**
+ * @class TableSection
+ * @memberof LuCI.form
+ * @augments LuCI.form.TypedSection
+ * @hideconstructor
+ * @classdesc
+ *
+ * The `TableSection` class maps all or - if `filter()` is overwritten - a
+ * subset of the underlying UCI configuration sections of a given type.
+ *
+ * Layout wise, the configuration section instances mapped by the section
+ * element (sometimes referred to as "section nodes") are rendered as rows
+ * within an HTML table element, with an optional section remove button in the
+ * last column and a section add button below the table, depending on the
+ * value of the `addremove` property.
+ *
+ * @param {LuCI.form.Map|LuCI.form.JSONMap} form
+ * The configuration form this section is added to. It is automatically passed
+ * by [section()]{@link LuCI.form.Map#section}.
+ *
+ * @param {string} section_type
+ * The type of the UCI section to map.
+ *
+ * @param {string} [title]
+ * The title caption of the form section element.
+ *
+ * @param {string} [description]
+ * The description text of the form section element.
+ */
+var CBITableSection = CBITypedSection.extend(/** @lends LuCI.form.TableSection.prototype */ {
 	__name__: 'CBI.TableSection',
 
+	/**
+	 * If set to `true`, the user may add or remove instances from the form
+	 * section widget, otherwise only preexisting sections may be edited.
+	 * The default is `false`.
+	 *
+	 * @name LuCI.form.TableSection.prototype#addremove
+	 * @type boolean
+	 * @default false
+	 */
+
+	/**
+	 * If set to `true`, mapped section instances are treated as anonymous
+	 * UCI sections, which means that section instance elements will be
+	 * rendered without title element and that no name is required when adding
+	 * new sections. The default is `false`.
+	 *
+	 * @name LuCI.form.TableSection.prototype#anonymous
+	 * @type boolean
+	 * @default false
+	 */
+
+	/**
+	 * Override the caption used for the section add button at the bottom of
+	 * the section form element. If set to a string, it will be used as-is,
+	 * if set to a function, the function will be invoked and its return value
+	 * is used as caption, after converting it to a string. If this property
+	 * is not set, the default is `Add`.
+	 *
+	 * @name LuCI.form.TableSection.prototype#addbtntitle
+	 * @type string|function
+	 * @default null
+	 */
+
+	/**
+	 * Override the per-section instance title caption shown in the first
+	 * column of the table unless `anonymous` is set to true. If set to a
+	 * string, it will be used as `String.format()` pattern with the name of
+	 * the underlying UCI section as first argument, if set to a function, the
+	 * function will be invoked with the section name as first argument and
+	 * its return value is used as caption, after converting it to a string.
+	 * If this property is not set, the default is the name of the underlying
+	 * UCI configuration section.
+	 *
+	 * @name LuCI.form.TableSection.prototype#sectiontitle
+	 * @type string|function
+	 * @default null
+	 */
+
+	/**
+	 * Override the per-section instance modal popup title caption shown when
+	 * clicking the `More…` button in a section specifying `max_cols`. If set
+	 * to a string, it will be used as `String.format()` pattern with the name
+	 * of the underlying UCI section as first argument, if set to a function,
+	 * the function will be invoked with the section name as first argument and
+	 * its return value is used as caption, after converting it to a string.
+	 * If this property is not set, the default is the name of the underlying
+	 * UCI configuration section.
+	 *
+	 * @name LuCI.form.TableSection.prototype#modaltitle
+	 * @type string|function
+	 * @default null
+	 */
+
+	/**
+	 * Override the UCI configuration name to read the section IDs from. By
+	 * default, the configuration name is inherited from the parent `Map`.
+	 * By setting this property, a deviating configuration may be specified.
+	 * The default is `null`, means inheriting from the parent form.
+	 *
+	 * @name LuCI.form.TableSection.prototype#uciconfig
+	 * @type string
+	 * @default null
+	 */
+
+	/**
+	 * Specify a maximum amount of columns to display. By default, one table
+	 * column is rendered for each child option of the form section element.
+	 * When this option is set to a positive number, then no more columns than
+	 * the given amount are rendered. When the number of child options exceeds
+	 * the specified amount, a `More…` button is rendered in the last column,
+	 * opening a modal dialog presenting all options elements in `NamedSection`
+	 * style when clicked.
+	 *
+	 * @name LuCI.form.TableSection.prototype#max_cols
+	 * @type number
+	 * @default null
+	 */
+
+	/**
+	 * If set to `true`, alternating `cbi-rowstyle-1` and `cbi-rowstyle-2` CSS
+	 * classes are added to the table row elements. Not all LuCI themes
+	 * implement these row style classes. The default is `false`.
+	 *
+	 * @name LuCI.form.TableSection.prototype#rowcolors
+	 * @type boolean
+	 * @default false
+	 */
+
+	/**
+	 * Enables a per-section instance row `Edit` button which triggers a certain
+	 * action when clicked. If set to a string, the string value is used
+	 * as `String.format()` pattern with the name of the underlying UCI section
+	 * as first format argument. The result is then interpreted as URL which
+	 * LuCI will navigate to when the user clicks the edit button.
+	 *
+	 * If set to a function, this function will be registered as click event
+	 * handler on the rendered edit button, receiving the section instance
+	 * name as first and the DOM click event as second argument.
+	 *
+	 * @name LuCI.form.TableSection.prototype#extedit
+	 * @type string|function
+	 * @default null
+	 */
+
+	/**
+	 * If set to `true`, a sort button is added to the last column, allowing
+	 * the user to reorder the section instances mapped by the section form
+	 * element.
+	 *
+	 * @name LuCI.form.TableSection.prototype#sortable
+	 * @type boolean
+	 * @default false
+	 */
+
+	/**
+	 * The `TableSection` implementation does not support option tabbing, so
+	 * its implementation of `tab()` will always throw an exception when
+	 * invoked.
+	 *
+	 * @override
+	 * @throws Throws an exception when invoked.
+	 */
 	tab: function() {
 		throw 'Tabs are not supported by TableSection';
 	},
 
+	/** @private */
 	renderContents: function(cfgsections, nodes) {
 		var section_id = null,
 		    config_name = this.uciconfig || this.map.config,
@@ -1106,6 +2291,7 @@ var CBITableSection = CBITypedSection.extend({
 		return sectionEl;
 	},
 
+	/** @private */
 	renderHeaderRows: function(max_cols, has_action) {
 		var has_titles = false,
 		    has_descriptions = false,
@@ -1189,6 +2375,7 @@ var CBITableSection = CBITypedSection.extend({
 		return trEls;
 	},
 
+	/** @private */
 	renderRowActions: function(section_id, more_label) {
 		var config_name = this.uciconfig || this.map.config;
 
@@ -1253,10 +2440,12 @@ var CBITableSection = CBITypedSection.extend({
 		return tdEl;
 	},
 
+	/** @private */
 	handleDragInit: function(ev) {
 		scope.dragState = { node: ev.target };
 	},
 
+	/** @private */
 	handleDragStart: function(ev) {
 		if (!scope.dragState || !scope.dragState.node.classList.contains('drag-handle')) {
 			scope.dragState = null;
@@ -1269,6 +2458,7 @@ var CBITableSection = CBITypedSection.extend({
 		ev.target.style.opacity = 0.4;
 	},
 
+	/** @private */
 	handleDragOver: function(ev) {
 		var n = scope.dragState.targetNode,
 		    r = scope.dragState.rect,
@@ -1288,16 +2478,19 @@ var CBITableSection = CBITypedSection.extend({
 		return false;
 	},
 
+	/** @private */
 	handleDragEnter: function(ev) {
 		scope.dragState.rect = ev.currentTarget.getBoundingClientRect();
 		scope.dragState.targetNode = ev.currentTarget;
 	},
 
+	/** @private */
 	handleDragLeave: function(ev) {
 		ev.currentTarget.classList.remove('drag-over-above');
 		ev.currentTarget.classList.remove('drag-over-below');
 	},
 
+	/** @private */
 	handleDragEnd: function(ev) {
 		var n = ev.target;
 
@@ -1310,6 +2503,7 @@ var CBITableSection = CBITypedSection.extend({
 			});
 	},
 
+	/** @private */
 	handleDrop: function(ev) {
 		var s = scope.dragState;
 
@@ -1337,10 +2531,12 @@ var CBITableSection = CBITypedSection.extend({
 		return false;
 	},
 
+	/** @private */
 	handleModalCancel: function(modalMap, ev) {
 		return Promise.resolve(ui.hideModal());
 	},
 
+	/** @private */
 	handleModalSave: function(modalMap, ev) {
 		return modalMap.save()
 			.then(L.bind(this.map.load, this.map))
@@ -1349,10 +2545,36 @@ var CBITableSection = CBITypedSection.extend({
 			.catch(function() {});
 	},
 
+	/**
+	 * Add further options to the per-section instanced modal popup.
+	 *
+	 * This function may be overwritten by user code to perform additional
+	 * setup steps before displaying the more options modal which is useful to
+	 * e.g. query additional data or to inject further option elements.
+	 *
+	 * The default implementation of this function does nothing.
+	 *
+	 * @abstract
+	 * @param {LuCI.form.NamedSection} modalSection
+	 * The `NamedSection` instance about to be rendered in the modal popup.
+	 *
+	 * @param {string} section_id
+	 * The ID of the underlying UCI section the modal popup belongs to.
+	 *
+	 * @param {Event} ev
+	 * The DOM event emitted by clicking the `More…` button.
+	 *
+	 * @returns {*|Promise<*>}
+	 * Return values of this function are ignored but if a promise is returned,
+	 * it is run to completion before the rendering is continued, allowing
+	 * custom logic to perform asynchroneous work before the modal dialog
+	 * is shown.
+	 */
 	addModalOptions: function(modalSection, section_id, ev) {
 
 	},
 
+	/** @private */
 	renderMoreOptionsModal: function(section_id, ev) {
 		var parent = this.map,
 		    title = parent.title,
@@ -1416,11 +2638,80 @@ var CBITableSection = CBITypedSection.extend({
 	}
 });
 
-var CBIGridSection = CBITableSection.extend({
+/**
+ * @class GridSection
+ * @memberof LuCI.form
+ * @augments LuCI.form.TableSection
+ * @hideconstructor
+ * @classdesc
+ *
+ * The `GridSection` class maps all or - if `filter()` is overwritten - a
+ * subset of the underlying UCI configuration sections of a given type.
+ *
+ * A grid section functions similar to a {@link LuCI.form.TableSection} but
+ * supports tabbing in the modal overlay. Option elements added with
+ * [option()]{@link LuCI.form.GridSection#option} are shown in the table while
+ * elements added with [taboption()]{@link LuCI.form.GridSection#taboption}
+ * are displayed in the modal popup.
+ *
+ * Another important difference is that the table cells show a readonly text
+ * preview of the corresponding option elements by default, unless the child
+ * option element is explicitely made writable by setting the `editable`
+ * property to `true`.
+ *
+ * Additionally, the grid section honours a `modalonly` property of child
+ * option elements. Refer to the [AbstractValue]{@link LuCI.form.AbstractValue}
+ * documentation for details.
+ *
+ * Layout wise, a grid section looks mostly identical to table sections.
+ *
+ * @param {LuCI.form.Map|LuCI.form.JSONMap} form
+ * The configuration form this section is added to. It is automatically passed
+ * by [section()]{@link LuCI.form.Map#section}.
+ *
+ * @param {string} section_type
+ * The type of the UCI section to map.
+ *
+ * @param {string} [title]
+ * The title caption of the form section element.
+ *
+ * @param {string} [description]
+ * The description text of the form section element.
+ */
+var CBIGridSection = CBITableSection.extend(/** @lends LuCI.form.GridSection.prototype */ {
+	/**
+	 * Add an option tab to the section.
+	 *
+	 * The modal option elements of a grid section may be divided into multiple
+	 * tabs to provide a better overview to the user.
+	 *
+	 * Before options can be moved into a tab pane, the corresponding tab
+	 * has to be defined first, which is done by calling this function.
+	 *
+	 * Note that tabs are only effective in modal popups, options added with
+	 * `option()` will not be assigned to a specific tab and are rendered in
+	 * the table view only.
+	 *
+	 * @param {string} name
+	 * The name of the tab to register. It may be freely chosen and just serves
+	 * as an identifier to differentiate tabs.
+	 *
+	 * @param {string} title
+	 * The human readable caption of the tab.
+	 *
+	 * @param {string} [description]
+	 * An additional description text for the corresponding tab pane. It is
+	 * displayed as text paragraph below the tab but before the tab pane
+	 * contents. If omitted, no description will be rendered.
+	 *
+	 * @throws {Error}
+	 * Throws an exeption if a tab with the same `name` already exists.
+	 */
 	tab: function(name, title, description) {
 		CBIAbstractSection.prototype.tab.call(this, name, title, description);
 	},
 
+	/** @private */
 	handleAdd: function(ev, name) {
 		var config_name = this.uciconfig || this.map.config,
 		    section_id = this.map.data.add(config_name, this.sectiontype, name);
@@ -1429,11 +2720,13 @@ var CBIGridSection = CBITableSection.extend({
 		return this.renderMoreOptionsModal(section_id);
 	},
 
+	/** @private */
 	handleModalSave: function(/* ... */) {
 		return this.super('handleModalSave', arguments)
 			.then(L.bind(function() { this.addedSection = null }, this));
 	},
 
+	/** @private */
 	handleModalCancel: function(/* ... */) {
 		var config_name = this.uciconfig || this.map.config;
 
@@ -1445,10 +2738,12 @@ var CBIGridSection = CBITableSection.extend({
 		return this.super('handleModalCancel', arguments);
 	},
 
+	/** @private */
 	renderUCISection: function(section_id) {
 		return this.renderOptions(null, section_id);
 	},
 
+	/** @private */
 	renderChildren: function(tab_name, section_id, in_table) {
 		var tasks = [], index = 0;
 
@@ -1465,6 +2760,7 @@ var CBIGridSection = CBITableSection.extend({
 		return Promise.all(tasks);
 	},
 
+	/** @private */
 	renderTextValue: function(section_id, opt) {
 		var title = this.stripTags(opt.title).trim(),
 		    descr = this.stripTags(opt.description).trim(),
@@ -1479,14 +2775,17 @@ var CBIGridSection = CBITableSection.extend({
 		}, (value != null) ? value : E('em', _('none')));
 	},
 
+	/** @private */
 	renderHeaderRows: function(section_id) {
 		return this.super('renderHeaderRows', [ NaN, true ]);
 	},
 
+	/** @private */
 	renderRowActions: function(section_id) {
 		return this.super('renderRowActions', [ section_id, _('Edit') ]);
 	},
 
+	/** @override */
 	parse: function() {
 		var section_ids = this.cfgsections(),
 		    tasks = [];
@@ -1506,7 +2805,36 @@ var CBIGridSection = CBITableSection.extend({
 	}
 });
 
-var CBINamedSection = CBIAbstractSection.extend({
+/**
+ * @class NamedSection
+ * @memberof LuCI.form
+ * @augments LuCI.form.AbstractSection
+ * @hideconstructor
+ * @classdesc
+ *
+ * The `NamedSection` class maps exactly one UCI section instance which is
+ * specified when constructing the class instance.
+ *
+ * Layout and functionality wise, a named section is essentially a
+ * `TypedSection` which allows exactly one section node.
+ *
+ * @param {LuCI.form.Map|LuCI.form.JSONMap} form
+ * The configuration form this section is added to. It is automatically passed
+ * by [section()]{@link LuCI.form.Map#section}.
+ *
+ * @param {string} section_id
+ * The name (ID) of the UCI section to map.
+ *
+ * @param {string} section_type
+ * The type of the UCI section to map.
+ *
+ * @param {string} [title]
+ * The title caption of the form section element.
+ *
+ * @param {string} [description]
+ * The description text of the form section element.
+ */
+var CBINamedSection = CBIAbstractSection.extend(/** @lends LuCI.form.NamedSection.prototype */ {
 	__name__: 'CBI.NamedSection',
 	__init__: function(map, section_id /*, ... */) {
 		this.super('__init__', this.varargs(arguments, 2, map));
@@ -1514,10 +2842,40 @@ var CBINamedSection = CBIAbstractSection.extend({
 		this.section = section_id;
 	},
 
+	/**
+	 * If set to `true`, the user may remove or recreate the sole mapped
+	 * configuration instance from the form section widget, otherwise only a
+	 * preexisting section may be edited. The default is `false`.
+	 *
+	 * @name LuCI.form.NamedSection.prototype#addremove
+	 * @type boolean
+	 * @default false
+	 */
+
+	/**
+	 * Override the UCI configuration name to read the section IDs from. By
+	 * default, the configuration name is inherited from the parent `Map`.
+	 * By setting this property, a deviating configuration may be specified.
+	 * The default is `null`, means inheriting from the parent form.
+	 *
+	 * @name LuCI.form.NamedSection.prototype#uciconfig
+	 * @type string
+	 * @default null
+	 */
+
+	/**
+	 * The `NamedSection` class overwrites the generic `cfgsections()`
+	 * implementation to return a one-element array containing the mapped
+	 * section ID as sole element. User code should not normally change this.
+	 *
+	 * @returns {string[]}
+	 * Returns a one-element array containing the mapped section ID.
+	 */
 	cfgsections: function() {
 		return [ this.section ];
 	},
 
+	/** @private */
 	handleAdd: function(ev) {
 		var section_id = this.section,
 		    config_name = this.uciconfig || this.map.config;
@@ -1526,6 +2884,7 @@ var CBINamedSection = CBIAbstractSection.extend({
 		return this.map.save(null, true);
 	},
 
+	/** @private */
 	handleRemove: function(ev) {
 		var section_id = this.section,
 		    config_name = this.uciconfig || this.map.config;
@@ -1534,6 +2893,7 @@ var CBINamedSection = CBIAbstractSection.extend({
 		return this.map.save(null, true);
 	},
 
+	/** @private */
 	renderContents: function(data) {
 		var ucidata = data[0], nodes = data[1],
 		    section_id = this.section,
@@ -1581,6 +2941,7 @@ var CBINamedSection = CBIAbstractSection.extend({
 		return sectionEl;
 	},
 
+	/** @override */
 	render: function() {
 		var config_name = this.uciconfig || this.map.config,
 		    section_id = this.section;
@@ -1592,9 +2953,71 @@ var CBINamedSection = CBIAbstractSection.extend({
 	}
 });
 
-var CBIValue = CBIAbstractValue.extend({
+/**
+ * @class Value
+ * @memberof LuCI.form
+ * @augments LuCI.form.AbstractValue
+ * @hideconstructor
+ * @classdesc
+ *
+ * The `Value` class represents a simple one-line form input using the
+ * {@link LuCI.ui.Textfield} or - in case choices are added - the
+ * {@link LuCI.ui.Combobox} class as underlying widget.
+ *
+ * @param {LuCI.form.Map|LuCI.form.JSONMap} form
+ * The configuration form this section is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {LuCI.form.AbstractSection} section
+ * The configuration section this option is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {string} option
+ * The name of the UCI option to map.
+ *
+ * @param {string} [title]
+ * The title caption of the option element.
+ *
+ * @param {string} [description]
+ * The description text of the option element.
+ */
+var CBIValue = CBIAbstractValue.extend(/** @lends LuCI.form.Value.prototype */ {
 	__name__: 'CBI.Value',
 
+	/**
+	 * If set to `true`, the field is rendered as password input, otherwise
+	 * as plain text input.
+	 *
+	 * @name LuCI.form.Value.prototype#password
+	 * @type boolean
+	 * @default false
+	 */
+
+	/**
+	 * Set a placeholder string to use when the input field is empty.
+	 *
+	 * @name LuCI.form.Value.prototype#placeholder
+	 * @type string
+	 * @default null
+	 */
+
+	/**
+	 * Add a predefined choice to the form option. By adding one or more
+	 * choices, the plain text input field is turned into a combobox widget
+	 * which prompts the user to select a predefined choice, or to enter a
+	 * custom value.
+	 *
+	 * @param {string} key
+	 * The choice value to add.
+	 *
+	 * @param {Node|string} value
+	 * The caption for the choice value. May be a DOM node, a document fragment
+	 * or a plain text string. If omitted, the `key` value is used as caption.
+	 */
 	value: function(key, val) {
 		this.keylist = this.keylist || [];
 		this.keylist.push(String(key));
@@ -1603,12 +3026,14 @@ var CBIValue = CBIAbstractValue.extend({
 		this.vallist.push(dom.elem(val) ? val : String(val != null ? val : key));
 	},
 
+	/** @override */
 	render: function(option_index, section_id, in_table) {
 		return Promise.resolve(this.cfgvalue(section_id))
 			.then(this.renderWidget.bind(this, section_id, option_index))
 			.then(this.renderFrame.bind(this, section_id, in_table, option_index));
 	},
 
+	/** @private */
 	renderFrame: function(section_id, in_table, option_index, nodes) {
 		var config_name = this.uciconfig || this.section.uciconfig || this.map.config,
 		    depend_list = this.transformDepList(section_id),
@@ -1685,6 +3110,7 @@ var CBIValue = CBIAbstractValue.extend({
 		return optionEl;
 	},
 
+	/** @private */
 	renderWidget: function(section_id, option_index, cfgvalue) {
 		var value = (cfgvalue != null) ? cfgvalue : this.default,
 		    choices = this.transformChoices(),
@@ -1718,9 +3144,42 @@ var CBIValue = CBIAbstractValue.extend({
 	}
 });
 
-var CBIDynamicList = CBIValue.extend({
+/**
+ * @class DynamicList
+ * @memberof LuCI.form
+ * @augments LuCI.form.Value
+ * @hideconstructor
+ * @classdesc
+ *
+ * The `DynamicList` class represents a multi value widget allowing the user
+ * to enter multiple unique values, optionally selected from a set of
+ * predefined choices. It builds upon the {@link LuCI.ui.DynamicList} widget.
+ *
+ * @param {LuCI.form.Map|LuCI.form.JSONMap} form
+ * The configuration form this section is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {LuCI.form.AbstractSection} section
+ * The configuration section this option is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {string} option
+ * The name of the UCI option to map.
+ *
+ * @param {string} [title]
+ * The title caption of the option element.
+ *
+ * @param {string} [description]
+ * The description text of the option element.
+ */
+var CBIDynamicList = CBIValue.extend(/** @lends LuCI.form.DynamicList.prototype */ {
 	__name__: 'CBI.DynamicList',
 
+	/** @private */
 	renderWidget: function(section_id, option_index, cfgvalue) {
 		var value = (cfgvalue != null) ? cfgvalue : this.default,
 		    choices = this.transformChoices(),
@@ -1739,7 +3198,39 @@ var CBIDynamicList = CBIValue.extend({
 	},
 });
 
-var CBIListValue = CBIValue.extend({
+/**
+ * @class ListValue
+ * @memberof LuCI.form
+ * @augments LuCI.form.Value
+ * @hideconstructor
+ * @classdesc
+ *
+ * The `ListValue` class implements a simple static HTML select element
+ * allowing the user to chose a single value from a set of predefined choices.
+ * It builds upon the {@link LuCI.ui.Select} widget.
+ *
+ * @param {LuCI.form.Map|LuCI.form.JSONMap} form
+ * The configuration form this section is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {LuCI.form.AbstractSection} section
+ * The configuration section this option is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {string} option
+ * The name of the UCI option to map.
+ *
+ * @param {string} [title]
+ * The title caption of the option element.
+ *
+ * @param {string} [description]
+ * The description text of the option element.
+ */
+var CBIListValue = CBIValue.extend(/** @lends LuCI.form.ListValue.prototype */ {
 	__name__: 'CBI.ListValue',
 
 	__init__: function() {
@@ -1748,6 +3239,15 @@ var CBIListValue = CBIValue.extend({
 		this.deplist = [];
 	},
 
+	/**
+	 * Set the size attribute of the underlying HTML select element.
+	 *
+	 * @name LuCI.form.ListValue.prototype#size
+	 * @type number
+	 * @default null
+	 */
+
+	 /** @private */
 	renderWidget: function(section_id, option_index, cfgvalue) {
 		var choices = this.transformChoices();
 		var widget = new ui.Select((cfgvalue != null) ? cfgvalue : this.default, choices, {
@@ -1763,7 +3263,38 @@ var CBIListValue = CBIValue.extend({
 	},
 });
 
-var CBIFlagValue = CBIValue.extend({
+/**
+ * @class FlagValue
+ * @memberof LuCI.form
+ * @augments LuCI.form.Value
+ * @hideconstructor
+ * @classdesc
+ *
+ * The `FlagValue` element builds upon the {@link LuCI.ui.Checkbox} widget to
+ * implement a simple checkbox element.
+ *
+ * @param {LuCI.form.Map|LuCI.form.JSONMap} form
+ * The configuration form this section is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {LuCI.form.AbstractSection} section
+ * The configuration section this option is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {string} option
+ * The name of the UCI option to map.
+ *
+ * @param {string} [title]
+ * The title caption of the option element.
+ *
+ * @param {string} [description]
+ * The description text of the option element.
+ */
+var CBIFlagValue = CBIValue.extend(/** @lends LuCI.form.FlagValue.prototype */ {
 	__name__: 'CBI.FlagValue',
 
 	__init__: function() {
@@ -1774,6 +3305,23 @@ var CBIFlagValue = CBIValue.extend({
 		this.default = this.disabled;
 	},
 
+	/**
+	 * Sets the input value to use for the checkbox checked state.
+	 *
+	 * @name LuCI.form.FlagValue.prototype#enabled
+	 * @type number
+	 * @default 1
+	 */
+
+	/**
+	 * Sets the input value to use for the checkbox unchecked state.
+	 *
+	 * @name LuCI.form.FlagValue.prototype#disabled
+	 * @type number
+	 * @default 0
+	 */
+
+	/** @private */
 	renderWidget: function(section_id, option_index, cfgvalue) {
 		var widget = new ui.Checkbox((cfgvalue != null) ? cfgvalue : this.default, {
 			id: this.cbid(section_id),
@@ -1785,12 +3333,25 @@ var CBIFlagValue = CBIValue.extend({
 		return widget.render();
 	},
 
+	/**
+	 * Query the checked state of the underlying checkbox widget and return
+	 * either the `enabled` or the `disabled` property value, depending on
+	 * the checked state.
+	 *
+	 * @override
+	 */
 	formvalue: function(section_id) {
 		var elem = this.getUIElement(section_id),
 		    checked = elem ? elem.isChecked() : false;
 		return checked ? this.enabled : this.disabled;
 	},
 
+	/**
+	 * Query the checked state of the underlying checkbox widget and return
+	 * either a localized `Yes` or `No` string, depending on the checked state.
+	 *
+	 * @override
+	 */
 	textvalue: function(section_id) {
 		var cval = this.cfgvalue(section_id);
 
@@ -1800,6 +3361,7 @@ var CBIFlagValue = CBIValue.extend({
 		return (cval == this.enabled) ? _('Yes') : _('No');
 	},
 
+	/** @override */
 	parse: function(section_id) {
 		if (this.isActive(section_id)) {
 			var fval = this.formvalue(section_id);
@@ -1818,7 +3380,39 @@ var CBIFlagValue = CBIValue.extend({
 	},
 });
 
-var CBIMultiValue = CBIDynamicList.extend({
+/**
+ * @class MultiValue
+ * @memberof LuCI.form
+ * @augments LuCI.form.DynamicList
+ * @hideconstructor
+ * @classdesc
+ *
+ * The `MultiValue` class is a modified variant of the `DynamicList` element
+ * which leverages the {@link LuCI.ui.Dropdown} widget to implement a multi
+ * select dropdown element.
+ *
+ * @param {LuCI.form.Map|LuCI.form.JSONMap} form
+ * The configuration form this section is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {LuCI.form.AbstractSection} section
+ * The configuration section this option is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {string} option
+ * The name of the UCI option to map.
+ *
+ * @param {string} [title]
+ * The title caption of the option element.
+ *
+ * @param {string} [description]
+ * The description text of the option element.
+ */
+var CBIMultiValue = CBIDynamicList.extend(/** @lends LuCI.form.MultiValue.prototype */ {
 	__name__: 'CBI.MultiValue',
 
 	__init__: function() {
@@ -1826,6 +3420,27 @@ var CBIMultiValue = CBIDynamicList.extend({
 		this.placeholder = _('-- Please choose --');
 	},
 
+	/**
+	 * Allows to specify the [display_items]{@link LuCI.ui.Dropdown.InitOptions}
+	 * property of the underlying dropdown widget. If omitted, the value of
+	 * the `size` property is used or `3` when `size` is unspecified as well.
+	 *
+	 * @name LuCI.form.MultiValue.prototype#display_size
+	 * @type number
+	 * @default null
+	 */
+
+	/**
+	 * Allows to specify the [dropdown_items]{@link LuCI.ui.Dropdown.InitOptions}
+	 * property of the underlying dropdown widget. If omitted, the value of
+	 * the `size` property is used or `-1` when `size` is unspecified as well.
+	 *
+	 * @name LuCI.form.MultiValue.prototype#dropdown_size
+	 * @type number
+	 * @default null
+	 */
+
+	/** @private */
 	renderWidget: function(section_id, option_index, cfgvalue) {
 		var value = (cfgvalue != null) ? cfgvalue : this.default,
 		    choices = this.transformChoices();
@@ -1845,11 +3460,80 @@ var CBIMultiValue = CBIDynamicList.extend({
 	},
 });
 
-var CBITextValue = CBIValue.extend({
+/**
+ * @class TextValue
+ * @memberof LuCI.form
+ * @augments LuCI.form.Value
+ * @hideconstructor
+ * @classdesc
+ *
+ * The `TextValue` class implements a multi-line textarea input using
+ * {@link LuCI.ui.Textarea}.
+ *
+ * @param {LuCI.form.Map|LuCI.form.JSONMap} form
+ * The configuration form this section is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {LuCI.form.AbstractSection} section
+ * The configuration section this option is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {string} option
+ * The name of the UCI option to map.
+ *
+ * @param {string} [title]
+ * The title caption of the option element.
+ *
+ * @param {string} [description]
+ * The description text of the option element.
+ */
+var CBITextValue = CBIValue.extend(/** @lends LuCI.form.TextValue.prototype */ {
 	__name__: 'CBI.TextValue',
 
+	/** @ignore */
 	value: null,
 
+	/**
+	 * Enforces the use of a monospace font for the textarea contents when set
+	 * to `true`.
+	 *
+	 * @name LuCI.form.TextValue.prototype#monospace
+	 * @type boolean
+	 * @default false
+	 */
+
+	/**
+	 * Allows to specify the [cols]{@link LuCI.ui.Textarea.InitOptions}
+	 * property of the underlying textarea widget.
+	 *
+	 * @name LuCI.form.TextValue.prototype#cols
+	 * @type number
+	 * @default null
+	 */
+
+	/**
+	 * Allows to specify the [rows]{@link LuCI.ui.Textarea.InitOptions}
+	 * property of the underlying textarea widget.
+	 *
+	 * @name LuCI.form.TextValue.prototype#rows
+	 * @type number
+	 * @default null
+	 */
+
+	/**
+	 * Allows to specify the [wrap]{@link LuCI.ui.Textarea.InitOptions}
+	 * property of the underlying textarea widget.
+	 *
+	 * @name LuCI.form.TextValue.prototype#wrap
+	 * @type number
+	 * @default null
+	 */
+
+	/** @private */
 	renderWidget: function(section_id, option_index, cfgvalue) {
 		var value = (cfgvalue != null) ? cfgvalue : this.default;
 
@@ -1868,9 +3552,64 @@ var CBITextValue = CBIValue.extend({
 	}
 });
 
-var CBIDummyValue = CBIValue.extend({
+/**
+ * @class DummyValue
+ * @memberof LuCI.form
+ * @augments LuCI.form.Value
+ * @hideconstructor
+ * @classdesc
+ *
+ * The `DummyValue` element wraps an {@link LuCI.ui.Hiddenfield} widget and
+ * renders the underlying UCI option or default value as readonly text.
+ *
+ * @param {LuCI.form.Map|LuCI.form.JSONMap} form
+ * The configuration form this section is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {LuCI.form.AbstractSection} section
+ * The configuration section this option is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {string} option
+ * The name of the UCI option to map.
+ *
+ * @param {string} [title]
+ * The title caption of the option element.
+ *
+ * @param {string} [description]
+ * The description text of the option element.
+ */
+var CBIDummyValue = CBIValue.extend(/** @lends LuCI.form.DummyValue.prototype */ {
 	__name__: 'CBI.DummyValue',
 
+	/**
+	 * Set an URL which is opened when clicking on the dummy value text.
+	 *
+	 * By setting this property, the dummy value text is wrapped in an `<a>`
+	 * element with the property value used as `href` attribute.
+	 *
+	 * @name LuCI.form.DummyValue.prototype#href
+	 * @type string
+	 * @default null
+	 */
+
+	/**
+	 * Treat the UCI option value (or the `default` property value) as HTML.
+	 *
+	 * By default, the value text is HTML escaped before being rendered as
+	 * text. In some cases it may be needed to actually interpret and render
+	 * HTML contents as-is. When set to `true`, HTML escaping is disabled.
+	 *
+	 * @name LuCI.form.DummyValue.prototype#rawhtml
+	 * @type boolean
+	 * @default null
+	 */
+
+	/** @private */
 	renderWidget: function(section_id, option_index, cfgvalue) {
 		var value = (cfgvalue != null) ? cfgvalue : this.default,
 		    hiddenEl = new ui.Hiddenfield(value, { id: this.cbid(section_id) }),
@@ -1888,13 +3627,99 @@ var CBIDummyValue = CBIValue.extend({
 		]);
 	},
 
+	/** @override */
 	remove: function() {},
+
+	/** @override */
 	write: function() {}
 });
 
-var CBIButtonValue = CBIValue.extend({
+/**
+ * @class ButtonValue
+ * @memberof LuCI.form
+ * @augments LuCI.form.Value
+ * @hideconstructor
+ * @classdesc
+ *
+ * The `DummyValue` element wraps an {@link LuCI.ui.Hiddenfield} widget and
+ * renders the underlying UCI option or default value as readonly text.
+ *
+ * @param {LuCI.form.Map|LuCI.form.JSONMap} form
+ * The configuration form this section is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {LuCI.form.AbstractSection} section
+ * The configuration section this option is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {string} option
+ * The name of the UCI option to map.
+ *
+ * @param {string} [title]
+ * The title caption of the option element.
+ *
+ * @param {string} [description]
+ * The description text of the option element.
+ */
+var CBIButtonValue = CBIValue.extend(/** @lends LuCI.form.ButtonValue.prototype */ {
 	__name__: 'CBI.ButtonValue',
 
+	/**
+	 * Override the rendered button caption.
+	 *
+	 * By default, the option title - which is passed as fourth argument to the
+	 * constructor - is used as caption for the button element. When setting
+	 * this property to a string, it is used as `String.format()` pattern with
+	 * the underlying UCI section name passed as first format argument. When
+	 * set to a function, it is invoked passing the section ID as sole argument
+	 * and the resulting return value is converted to a string before being
+	 * used as button caption.
+	 *
+	 * The default is `null`, means the option title is used as caption.
+	 *
+	 * @name LuCI.form.ButtonValue.prototype#inputtitle
+	 * @type string|function
+	 * @default null
+	 */
+
+	/**
+	 * Override the button style class.
+	 *
+	 * By setting this property, a specific `cbi-button-*` CSS class can be
+	 * selected to influence the style of the resulting button.
+	 *
+	 * Suitable values which are implemented by most themes are `positive`,
+	 * `negative` and `primary`.
+	 *
+	 * The default is `null`, means a neutral button styling is used.
+	 *
+	 * @name LuCI.form.ButtonValue.prototype#inputstyle
+	 * @type string
+	 * @default null
+	 */
+
+	/**
+	 * Override the button click action.
+	 *
+	 * By default, the underlying UCI option (or default property) value is
+	 * copied into a hidden field tied to the button element and the save
+	 * action is triggered on the parent form element.
+	 *
+	 * When this property is set to a function, it is invoked instead of
+	 * performing the default actions. The handler function will receive the
+	 * DOM click element as first and the underlying configuration section ID
+	 * as second argument.
+	 *
+	 * @name LuCI.form.ButtonValue.prototype#onclick
+	 * @type function
+	 * @default null
+	 */
+
+	/** @private */
 	renderWidget: function(section_id, option_index, cfgvalue) {
 		var value = (cfgvalue != null) ? cfgvalue : this.default,
 		    hiddenEl = new ui.Hiddenfield(value, { id: this.cbid(section_id) }),
@@ -1924,9 +3749,48 @@ var CBIButtonValue = CBIValue.extend({
 	}
 });
 
-var CBIHiddenValue = CBIValue.extend({
+/**
+ * @class HiddenValue
+ * @memberof LuCI.form
+ * @augments LuCI.form.Value
+ * @hideconstructor
+ * @classdesc
+ *
+ * The `HiddenValue` element wraps an {@link LuCI.ui.Hiddenfield} widget.
+ *
+ * Hidden value widgets used to be necessary in legacy code which actually
+ * submitted the underlying HTML form the server. With client side handling of
+ * forms, there are more efficient ways to store hidden state data.
+ *
+ * Since this widget has no visible content, the title and description values
+ * of this form element should be set to `null` as well to avoid a broken or
+ * distorted form layout when rendering the option element.
+ *
+ * @param {LuCI.form.Map|LuCI.form.JSONMap} form
+ * The configuration form this section is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {LuCI.form.AbstractSection} section
+ * The configuration section this option is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {string} option
+ * The name of the UCI option to map.
+ *
+ * @param {string} [title]
+ * The title caption of the option element.
+ *
+ * @param {string} [description]
+ * The description text of the option element.
+ */
+var CBIHiddenValue = CBIValue.extend(/** @lends LuCI.form.HiddenValue.prototype */ {
 	__name__: 'CBI.HiddenValue',
 
+	/** @private */
 	renderWidget: function(section_id, option_index, cfgvalue) {
 		var widget = new ui.Hiddenfield((cfgvalue != null) ? cfgvalue : this.default, {
 			id: this.cbid(section_id)
@@ -1936,7 +3800,38 @@ var CBIHiddenValue = CBIValue.extend({
 	}
 });
 
-var CBIFileUpload = CBIValue.extend({
+/**
+ * @class FileUpload
+ * @memberof LuCI.form
+ * @augments LuCI.form.Value
+ * @hideconstructor
+ * @classdesc
+ *
+ * The `FileUpload` element wraps an {@link LuCI.ui.FileUpload} widget and
+ * offers the ability to browse, upload and select remote files.
+ *
+ * @param {LuCI.form.Map|LuCI.form.JSONMap} form
+ * The configuration form this section is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {LuCI.form.AbstractSection} section
+ * The configuration section this option is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {string} option
+ * The name of the UCI option to map.
+ *
+ * @param {string} [title]
+ * The title caption of the option element.
+ *
+ * @param {string} [description]
+ * The description text of the option element.
+ */
+var CBIFileUpload = CBIValue.extend(/** @lends LuCI.form.FileUpload.prototype */ {
 	__name__: 'CBI.FileSelect',
 
 	__init__: function(/* ... */) {
@@ -1948,6 +3843,67 @@ var CBIFileUpload = CBIValue.extend({
 		this.root_directory = '/etc/luci-uploads';
 	},
 
+	/**
+	 * Toggle display of hidden files.
+	 *
+	 * Display hidden files when rendering the remote directory listing.
+	 * Note that this is merely a cosmetic feature, hidden files are always
+	 * included in received remote file listings.
+	 *
+	 * The default is `false`, means hidden files are not displayed.
+	 *
+	 * @name LuCI.form.FileUpload.prototype#show_hidden
+	 * @type boolean
+	 * @default false
+	 */
+
+	/**
+	 * Toggle file upload functionality.
+	 *
+	 * When set to `true`, the underlying widget provides a button which lets
+	 * the user select and upload local files to the remote system.
+	 * Note that this is merely a cosmetic feature, remote upload access is
+	 * controlled by the session ACL rules.
+	 *
+	 * The default is `true`, means file upload functionality is displayed.
+	 *
+	 * @name LuCI.form.FileUpload.prototype#enable_upload
+	 * @type boolean
+	 * @default true
+	 */
+
+	/**
+	 * Toggle remote file delete functionality.
+	 *
+	 * When set to `true`, the underlying widget provides a buttons which let
+	 * the user delete files from remote directories. Note that this is merely
+	 * a cosmetic feature, remote delete permissions are controlled by the
+	 * session ACL rules.
+	 *
+	 * The default is `true`, means file removal buttons are displayed.
+	 *
+	 * @name LuCI.form.FileUpload.prototype#enable_remove
+	 * @type boolean
+	 * @default true
+	 */
+
+	/**
+	 * Specify the root directory for file browsing.
+	 *
+	 * This property defines the topmost directory the file browser widget may
+	 * navigate to, the UI will not allow browsing directories outside this
+	 * prefix. Note that this is merely a cosmetic feature, remote file access
+	 * and directory listing permissions are controlled by the session ACL
+	 * rules.
+	 *
+	 * The default is `/etc/luci-uploads`.
+	 *
+	 * @name LuCI.form.FileUpload.prototype#root_directory
+	 * @type string
+	 * @default /etc/luci-uploads
+	 */
+
+	/** @private */
 	renderWidget: function(section_id, option_index, cfgvalue) {
 		var browserEl = new ui.FileUpload((cfgvalue != null) ? cfgvalue : this.default, {
 			id: this.cbid(section_id),
@@ -1962,7 +3918,45 @@ var CBIFileUpload = CBIValue.extend({
 	}
 });
 
-var CBISectionValue = CBIValue.extend({
+/**
+ * @class SectionValue
+ * @memberof LuCI.form
+ * @augments LuCI.form.Value
+ * @hideconstructor
+ * @classdesc
+ *
+ * The `SectionValue` widget embeds a form section element within an option
+ * element container, allowing to nest form sections into other sections.
+ *
+ * @param {LuCI.form.Map|LuCI.form.JSONMap} form
+ * The configuration form this section is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {LuCI.form.AbstractSection} section
+ * The configuration section this option is added to. It is automatically passed
+ * by [option()]{@link LuCI.form.AbstractSection#option} or
+ * [taboption()]{@link LuCI.form.AbstractSection#taboption} when adding the
+ * option to the section.
+ *
+ * @param {string} option
+ * The internal name of the option element holding the section. Since a section
+ * container element does not read or write any configuration itself, the name
+ * is only used internally and does not need to relate to any underlying UCI
+ * option name.
+ *
+ * @param {LuCI.form.AbstractSection} subsection_class
+ * The class to use for instantiating the nested section element. Note that
+ * the class value itself is expected here, not a class instance obtained by
+ * calling `new`. The given class argument must be a subclass of the
+ * `AbstractSection` class.
+ *
+ * @param {...*} [class_args]
+ * All further arguments are passed as-is to the subclass constructor. Refer
+ * to the corresponding class constructor documentations for details.
+ */
+var CBISectionValue = CBIValue.extend(/** @lends LuCI.form.SectionValue.prototype */ {
 	__name__: 'CBI.ContainerValue',
 	__init__: function(map, section, option, cbiClass /*, ... */) {
 		this.super('__init__', [map, section, option]);
@@ -1974,30 +3968,124 @@ var CBISectionValue = CBIValue.extend({
 		this.subsection.parentoption = this;
 	},
 
+	/**
+	 * Access the embedded section instance.
+	 *
+	 * This property holds a reference to the instantiated nested section.
+	 *
+	 * @name LuCI.form.SectionValue.prototype#subsection
+	 * @type LuCI.form.AbstractSection
+	 * @readonly
+	 */
+
+	/** @override */
 	load: function(section_id) {
 		return this.subsection.load();
 	},
 
+	/** @override */
 	parse: function(section_id) {
 		return this.subsection.parse();
 	},
 
+	/** @private */
 	renderWidget: function(section_id, option_index, cfgvalue) {
 		return this.subsection.render();
 	},
 
+	/** @private */
 	checkDepends: function(section_id) {
 		this.subsection.checkDepends();
 		return CBIValue.prototype.checkDepends.apply(this, [ section_id ]);
 	},
 
+	/**
+	 * Since the section container is not rendering an own widget,
+	 * its `value()` implementation is a no-op.
+	 *
+	 * @override
+	 */
+	value: function() {},
+
+	/**
+	 * Since the section container is not tied to any UCI configuration,
+	 * its `write()` implementation is a no-op.
+	 *
+	 * @override
+	 */
 	write: function() {},
+
+	/**
+	 * Since the section container is not tied to any UCI configuration,
+	 * its `remove()` implementation is a no-op.
+	 *
+	 * @override
+	 */
 	remove: function() {},
+
+	/**
+	 * Since the section container is not tied to any UCI configuration,
+	 * its `cfgvalue()` implementation will always return `null`.
+	 *
+	 * @override
+	 * @returns {null}
+	 */
 	cfgvalue: function() { return null },
+
+	/**
+	 * Since the section container is not tied to any UCI configuration,
+	 * its `formvalue()` implementation will always return `null`.
+	 *
+	 * @override
+	 * @returns {null}
+	 */
 	formvalue: function() { return null }
 });
 
-return baseclass.extend({
+/**
+ * @class form
+ * @memberof LuCI
+ * @hideconstructor
+ * @classdesc
+ *
+ * The LuCI form class provides high level abstractions for creating creating
+ * UCI- or JSON backed configurations forms.
+ *
+ * To import the class in views, use `'require form'`, to import it in
+ * external JavaScript, use `L.require("form").then(...)`.
+ *
+ * A typical form is created by first constructing a
+ * {@link LuCI.form.Map} or {@link LuCI.form.JSONMap} instance using `new` and
+ * by subsequently adding sections and options to it. Finally
+ * [render()]{@link LuCI.form.Map#render} is invoked on the instance to
+ * assemble the HTML markup and insert it into the DOM.
+ *
+ * Example:
+ *
+ * <pre>
+ * 'use strict';
+ * 'require form';
+ *
+ * var m, s, o;
+ *
+ * m = new form.Map('example', 'Example form',
+ *	'This is an example form mapping the contents of /etc/config/example');
+ *
+ * s = m.section(form.NamedSection, 'first_section', 'example', 'The first section',
+ * 	'This sections maps "config example first_section" of /etc/config/example');
+ *
+ * o = s.option(form.Flag, 'some_bool', 'A checkbox option');
+ *
+ * o = s.option(form.ListValue, 'some_choice', 'A select element');
+ * o.value('choice1', 'The first choice');
+ * o.value('choice2', 'The second choice');
+ *
+ * m.render().then(function(node) {
+ * 	document.body.appendChild(node);
+ * });
+ * </pre>
+ */
+return baseclass.extend(/** @lends LuCI.form.prototype */ {
 	Map: CBIMap,
 	JSONMap: CBIJSONMap,
 	AbstractSection: CBIAbstractSection,