jenkins-bot has submitted this change and it was merged.
Change subject: Tool*.js: Consolidate and cross-link some documentation
......................................................................
Tool*.js: Consolidate and cross-link some documentation
Change-Id: I58462b7b41ee41194dffdfaf943b18d10d2a8cdb
---
M src/ToolFactory.js
M src/ToolGroup.js
2 files changed, 26 insertions(+), 29 deletions(-)
Approvals:
Jforrester: Looks good to me, approved
jenkins-bot: Verified
diff --git a/src/ToolFactory.js b/src/ToolFactory.js
index bb78423..27d9222 100644
--- a/src/ToolFactory.js
+++ b/src/ToolFactory.js
@@ -25,10 +25,10 @@
/**
* Get tools from the factory
*
- * @param {Array} include Included tools
- * @param {Array} exclude Excluded tools
- * @param {Array} promote Promoted tools
- * @param {Array} demote Demoted tools
+ * @param {Array|string} [include] Included tools, see #extract for format
+ * @param {Array|string} [exclude] Excluded tools, see #extract for format
+ * @param {Array|string} [promote] Promoted tools, see #extract for format
+ * @param {Array|string} [demote] Demoted tools, see #extract for format
* @return {string[]} List of tools
*/
OO.ui.ToolFactory.prototype.getTools = function ( include, exclude, promote,
demote ) {
@@ -56,17 +56,24 @@
/**
* Get a flat list of names from a list of names or groups.
*
- * Tools can be specified in the following ways:
+ * Normally, `collection` is an array of tool specifications. Tools can be
specified in the
+ * following ways:
*
- * - A specific tool: `{ name: 'tool-name' }` or `'tool-name'`
- * - All tools in a group: `{ group: 'group-name' }`
- * - All tools: `'*'`
+ * - To include an individual tool, use the symbolic name: `{ name:
'tool-name' }` or `'tool-name'`.
+ * - To include all tools in a group, use the group name: `{ group:
'group-name' }`. (To assign the
+ * tool to a group, use OO.ui.Tool.static.group.)
+ *
+ * Alternatively, to include all tools that are not yet assigned to any other
toolgroup, use the
+ * catch-all selector `'*'`.
+ *
+ * If `used` is passed, tool names that appear as properties in this object
will be considered
+ * already assigned, and will not be returned even if specified otherwise. The
tool names extracted
+ * by this function call will be added as new properties in the object.
*
* @private
- * @param {Array|string} collection List of tools
- * @param {Object} [used] Object with names that should be skipped as
properties; extracted
- * names will be added as properties
- * @return {string[]} List of extracted names
+ * @param {Array|string} collection List of tools, see above
+ * @param {Object} [used] Object containing information about used tools, see
above
+ * @return {string[]} List of extracted tool names
*/
OO.ui.ToolFactory.prototype.extract = function ( collection, used ) {
var i, len, item, name, tool,
diff --git a/src/ToolGroup.js b/src/ToolGroup.js
index bb1b56c..bb06762 100644
--- a/src/ToolGroup.js
+++ b/src/ToolGroup.js
@@ -4,19 +4,9 @@
* to which a tool belongs determines how the tool is arranged and displayed
in the toolbar. Toolgroups
* themselves are created on demand with a {@link OO.ui.ToolGroupFactory
toolgroup factory}.
*
- * Toolgroups can contain individual tools, groups of tools, or all available
tools:
- *
- * To include an individual tool (or array of individual tools), specify tools
by symbolic name:
- *
- * include: [ 'tool-name' ] or [ { name: 'tool-name' }]
- *
- * To include a group of tools, specify the group name. (The tool's static
‘group’ config is used to assign the tool to a group.)
- *
- * include: [ { group: 'group-name' } ]
- *
- * To include all tools that are not yet assigned to a toolgroup, use the
catch-all selector, an asterisk (*):
- *
- * include: '*'
+ * Toolgroups can contain individual tools, groups of tools, or all available
tools, as specified
+ * using the `include` config option. See OO.ui.ToolFactory#extract on
documentation of the format.
+ * The options `exclude`, `promote`, and `demote` support the same formats.
*
* See {@link OO.ui.Toolbar toolbars} for a full example. For more information
about toolbars in general,
* please see the [OOjs UI documentation on MediaWiki][1].
@@ -31,10 +21,10 @@
* @constructor
* @param {OO.ui.Toolbar} toolbar
* @param {Object} [config] Configuration options
- * @cfg {Array|string} [include=[]] List of tools to include in the toolgroup.
- * @cfg {Array|string} [exclude=[]] List of tools to exclude from the
toolgroup.
- * @cfg {Array|string} [promote=[]] List of tools to promote to the beginning
of the toolgroup.
- * @cfg {Array|string} [demote=[]] List of tools to demote to the end of the
toolgroup.
+ * @cfg {Array|string} [include] List of tools to include in the toolgroup,
see above.
+ * @cfg {Array|string} [exclude] List of tools to exclude from the toolgroup,
see above.
+ * @cfg {Array|string} [promote] List of tools to promote to the beginning of
the toolgroup, see above.
+ * @cfg {Array|string} [demote] List of tools to demote to the end of the
toolgroup, see above.
* This setting is particularly useful when tools have been added to the
toolgroup
* en masse (e.g., via the catch-all selector).
*/
--
To view, visit https://gerrit.wikimedia.org/r/255788
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: I58462b7b41ee41194dffdfaf943b18d10d2a8cdb
Gerrit-PatchSet: 2
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Bartosz Dziewoński <matma....@gmail.com>
Gerrit-Reviewer: Jforrester <jforres...@wikimedia.org>
Gerrit-Reviewer: jenkins-bot <>
_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
