jenkins-bot has submitted this change and it was merged. Change subject: doc: Improve and fix minor issues in base classes ......................................................................
doc: Improve and fix minor issues in base classes * Remove useless descriptions so they show up when querying items that need descriptions. * Omit redundant @method. * Use @return instead of @returns. * Add missing @inheritable. * Consistent Tag order (@abstract, @class, @extends, etc.) * Fix collapsed lists (need an empty line before first list item). * Don't document Class.static itself (just like we don't document Class.prototype itself either). OO.ui: * Index #deferMsg, #resolveMsg and #Keys. OO.ui.ToolFactory: * Index #getTools. OO.ui.ToolGroup: * Move second paragraph to below the first one. Separating them between other tags is confusing. Change-Id: Iaaf547db2becedbbcaecee6b35a2217c6cbb8f3b --- M src/OO.ui.Dialog.js M src/OO.ui.Element.js M src/OO.ui.Frame.js M src/OO.ui.Layout.js M src/OO.ui.Tool.js M src/OO.ui.ToolFactory.js M src/OO.ui.ToolGroup.js M src/OO.ui.Toolbar.js M src/OO.ui.Widget.js M src/OO.ui.Window.js M src/OO.ui.WindowSet.js M src/OO.ui.js 12 files changed, 91 insertions(+), 126 deletions(-) Approvals: Trevor Parscal: Looks good to me, approved jenkins-bot: Verified diff --git a/src/OO.ui.Dialog.js b/src/OO.ui.Dialog.js index e8bdb04..f54166b 100644 --- a/src/OO.ui.Dialog.js +++ b/src/OO.ui.Dialog.js @@ -1,8 +1,6 @@ /** - * Modal dialog box. - * - * @class * @abstract + * @class * @extends OO.ui.Window * * @constructor @@ -54,6 +52,7 @@ * * @static * @property {Object} + * @inheritable */ OO.ui.Dialog.static.sizeCssClasses = { 'small': 'oo-ui-dialog-small', @@ -65,8 +64,6 @@ /** * Handle close button click events. - * - * @method */ OO.ui.Dialog.prototype.onCloseButtonClick = function () { this.close( { 'action': 'cancel' } ); @@ -75,7 +72,6 @@ /** * Handle window mouse wheel events. * - * @method * @param {jQuery.Event} e Mouse wheel event */ OO.ui.Dialog.prototype.onWindowMouseWheel = function () { @@ -85,7 +81,6 @@ /** * Handle document key down events. * - * @method * @param {jQuery.Event} e Key down event */ OO.ui.Dialog.prototype.onDocumentKeyDown = function ( e ) { @@ -106,7 +101,6 @@ /** * Handle frame document key down events. * - * @method * @param {jQuery.Event} e Key down event */ OO.ui.Dialog.prototype.onFrameDocumentKeyDown = function ( e ) { diff --git a/src/OO.ui.Element.js b/src/OO.ui.Element.js index 59a3850..14539cf 100644 --- a/src/OO.ui.Element.js +++ b/src/OO.ui.Element.js @@ -1,8 +1,8 @@ /** * DOM element abstraction. * - * @class * @abstract + * @class * * @constructor * @param {Object} [config] Configuration options @@ -30,11 +30,6 @@ /* Static Properties */ -/** - * @static - * @property - * @inheritable - */ OO.ui.Element.static = {}; /** @@ -51,12 +46,12 @@ /* Static Methods */ /** - * Gets a jQuery function within a specific document. + * Get a jQuery function within a specific document. * * @static * @param {jQuery|HTMLElement|HTMLDocument|Window} context Context to bind the function to * @param {OO.ui.Frame} [frame] Frame of the document context - * @returns {Function} Bound jQuery function + * @return {Function} Bound jQuery function */ OO.ui.Element.getJQuery = function ( context, frame ) { function wrapper( selector ) { @@ -77,7 +72,7 @@ * * @static * @param {jQuery|HTMLElement|HTMLDocument|Window} obj Object to get the document for - * @returns {HTMLDocument} Document object + * @return {HTMLDocument} Document object * @throws {Error} If context is invalid */ OO.ui.Element.getDocument = function ( obj ) { @@ -105,7 +100,7 @@ * * @static * @param {jQuery|HTMLElement|HTMLDocument|Window} obj Context to get the window for - * @returns {Window} Window object + * @return {Window} Window object */ OO.ui.Element.getWindow = function ( obj ) { var doc = this.getDocument( obj ); @@ -117,7 +112,7 @@ * * @static * @param {jQuery|HTMLElement|HTMLDocument|Window} obj Context to get the direction for - * @returns {string} Text direction, either `ltr` or `rtl` + * @return {string} Text direction, either `ltr` or `rtl` */ OO.ui.Element.getDir = function ( obj ) { var isDoc, isWin; @@ -145,7 +140,7 @@ * @param {Window} from Window of the child frame * @param {Window} [to=window] Window of the parent frame * @param {Object} [offset] Offset to start with, used internally - * @returns {Object} Offset object, containing left and top properties + * @return {Object} Offset object, containing left and top properties */ OO.ui.Element.getFrameOffset = function ( from, to, offset ) { var i, len, frames, frame, rect; @@ -187,7 +182,7 @@ * @static * @param {jQuery} $from * @param {jQuery} $to - * @returns {Object} Translated position coordinates, containing top and left properties + * @return {Object} Translated position coordinates, containing top and left properties */ OO.ui.Element.getRelativePosition = function ( $from, $to ) { var from = $from.offset(), @@ -304,7 +299,7 @@ }; /** - * Scroll element into view + * Scroll element into view. * * @static * @param {HTMLElement} el Element to scroll into view @@ -367,7 +362,7 @@ * * Override this method to base the result on instance information. * - * @returns {string} HTML tag name + * @return {string} HTML tag name */ OO.ui.Element.prototype.getTagName = function () { return this.constructor.static.tagName; @@ -376,7 +371,7 @@ /** * Get the DOM document. * - * @returns {HTMLDocument} Document object + * @return {HTMLDocument} Document object */ OO.ui.Element.prototype.getElementDocument = function () { return OO.ui.Element.getDocument( this.$element ); @@ -385,7 +380,7 @@ /** * Get the DOM window. * - * @returns {Window} Window object + * @return {Window} Window object */ OO.ui.Element.prototype.getElementWindow = function () { return OO.ui.Element.getWindow( this.$element ); @@ -394,7 +389,6 @@ /** * Get closest scrollable container. * - * @method * @see #static-method-getClosestScrollableContainer */ OO.ui.Element.prototype.getClosestScrollableElementContainer = function () { @@ -404,7 +398,7 @@ /** * Get group element is in. * - * @returns {OO.ui.GroupElement|null} Group element, null if none + * @return {OO.ui.GroupElement|null} Group element, null if none */ OO.ui.Element.prototype.getElementGroup = function () { return this.elementGroup; @@ -422,9 +416,8 @@ }; /** - * Scroll element into view + * Scroll element into view. * - * @method * @see #static-method-scrollIntoView * @param {Object} [config={}] */ diff --git a/src/OO.ui.Frame.js b/src/OO.ui.Frame.js index fae99be..d1040dd 100644 --- a/src/OO.ui.Frame.js +++ b/src/OO.ui.Frame.js @@ -35,6 +35,10 @@ /* Static Properties */ +/** + * @static + * @inheritdoc + */ OO.ui.Frame.static.tagName = 'iframe'; /* Events */ diff --git a/src/OO.ui.Layout.js b/src/OO.ui.Layout.js index bb2a735..c5b7e71 100644 --- a/src/OO.ui.Layout.js +++ b/src/OO.ui.Layout.js @@ -1,8 +1,8 @@ /** * Container for elements. * - * @class * @abstract + * @class * @extends OO.ui.Element * @mixins OO.EventEmitter * diff --git a/src/OO.ui.Tool.js b/src/OO.ui.Tool.js index f2c5a18..98b4ad1 100644 --- a/src/OO.ui.Tool.js +++ b/src/OO.ui.Tool.js @@ -1,8 +1,8 @@ /** * Generic toolbar tool. * - * @class * @abstract + * @class * @extends OO.ui.Widget * @mixins OO.ui.IconedElement * @@ -61,6 +61,10 @@ /* Static Properties */ +/** + * @static + * @inheritdoc + */ OO.ui.Tool.static.tagName = 'span'; /** @@ -110,11 +114,11 @@ /** * Check if this tool is compatible with given data. * - * @method * @static + * @method * @inheritable * @param {Mixed} data Data to check - * @returns {boolean} Tool can be used with data + * @return {boolean} Tool can be used with data */ OO.ui.Tool.static.isCompatibleWith = function () { return false; @@ -128,7 +132,6 @@ * This is an abstract method that must be overridden in a concrete subclass. * * @abstract - * @method */ OO.ui.Tool.prototype.onUpdateState = function () { throw new Error( @@ -142,7 +145,6 @@ * This is an abstract method that must be overridden in a concrete subclass. * * @abstract - * @method */ OO.ui.Tool.prototype.onSelect = function () { throw new Error( @@ -153,7 +155,6 @@ /** * Check if the button is active. * - * @method * @param {boolean} Button is active */ OO.ui.Tool.prototype.isActive = function () { @@ -163,7 +164,6 @@ /** * Make the button appear active or inactive. * - * @method * @param {boolean} state Make button appear active */ OO.ui.Tool.prototype.setActive = function ( state ) { @@ -178,7 +178,6 @@ /** * Get the tool title. * - * @method * @param {string|Function} title Title text or a function that returns text * @chainable */ @@ -191,8 +190,7 @@ /** * Get the tool title. * - * @method - * @returns {string} Title text + * @return {string} Title text */ OO.ui.Tool.prototype.getTitle = function () { return this.title; @@ -201,8 +199,7 @@ /** * Get the tool's symbolic name. * - * @method - * @returns {string} Symbolic name of tool + * @return {string} Symbolic name of tool */ OO.ui.Tool.prototype.getName = function () { return this.constructor.static.name; @@ -210,8 +207,6 @@ /** * Update the title. - * - * @method */ OO.ui.Tool.prototype.updateTitle = function () { var titleTooltips = this.toolGroup.constructor.static.titleTooltips, @@ -242,8 +237,6 @@ /** * Destroy tool. - * - * @method */ OO.ui.Tool.prototype.destroy = function () { this.toolbar.disconnect( this ); diff --git a/src/OO.ui.ToolFactory.js b/src/OO.ui.ToolFactory.js index 95d110b..aa8fd0f 100644 --- a/src/OO.ui.ToolFactory.js +++ b/src/OO.ui.ToolFactory.js @@ -16,6 +16,7 @@ /* Methods */ +/** */ OO.ui.ToolFactory.prototype.getTools = function ( include, exclude, promote, demote ) { var i, len, included, promoted, demoted, auto = [], @@ -42,14 +43,15 @@ * Get a flat list of names from a list of names or groups. * * 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: `'*'` + * + * - A specific tool: `{ 'name': 'tool-name' }` or `'tool-name'` + * - All tools in a group: `{ 'group': 'group-name' }` + * - All tools: `'*'` * * @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 + * names will be added as properties * @return {string[]} List of extracted names */ OO.ui.ToolFactory.prototype.extract = function ( collection, used ) { diff --git a/src/OO.ui.ToolGroup.js b/src/OO.ui.ToolGroup.js index 15f78f3..affdecf 100644 --- a/src/OO.ui.ToolGroup.js +++ b/src/OO.ui.ToolGroup.js @@ -1,15 +1,16 @@ /** * Collection of tools. * - * @class + * 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: `'*'` + * * @abstract + * @class * @extends OO.ui.Widget * @mixins OO.ui.GroupElement - * - * 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: `'*'` * * @constructor * @param {OO.ui.Toolbar} toolbar @@ -93,7 +94,6 @@ /** * Handle mouse down events. * - * @method * @param {jQuery.Event} e Mouse down event */ OO.ui.ToolGroup.prototype.onMouseDown = function ( e ) { @@ -112,7 +112,6 @@ /** * Handle captured mouse up events. * - * @method * @param {Event} e Mouse up event */ OO.ui.ToolGroup.prototype.onCapturedMouseUp = function ( e ) { @@ -125,7 +124,6 @@ /** * Handle mouse up events. * - * @method * @param {jQuery.Event} e Mouse up event */ OO.ui.ToolGroup.prototype.onMouseUp = function ( e ) { @@ -142,7 +140,6 @@ /** * Handle mouse over events. * - * @method * @param {jQuery.Event} e Mouse over event */ OO.ui.ToolGroup.prototype.onMouseOver = function ( e ) { @@ -156,7 +153,6 @@ /** * Handle mouse out events. * - * @method * @param {jQuery.Event} e Mouse out event */ OO.ui.ToolGroup.prototype.onMouseOut = function ( e ) { @@ -173,10 +169,9 @@ * Only tool links are considered, which prevents other elements in the tool such as popups from * triggering tool group interactions. * - * @method * @private * @param {jQuery.Event} e - * @returns {OO.ui.Tool|null} Tool, `null` if none was found + * @return {OO.ui.Tool|null} Tool, `null` if none was found */ OO.ui.ToolGroup.prototype.getTargetTool = function ( e ) { var tool, @@ -193,6 +188,7 @@ * Handle tool registry register events. * * If a tool is registered after the group is created, we must repopulate the list to account for: + * * - a tool being added that may be included * - a tool already included being overridden * @@ -213,8 +209,6 @@ /** * Add and remove tools based on configuration. - * - * @method */ OO.ui.ToolGroup.prototype.populate = function () { var i, len, name, tool, @@ -270,8 +264,6 @@ /** * Destroy tool group. - * - * @method */ OO.ui.ToolGroup.prototype.destroy = function () { var name; diff --git a/src/OO.ui.Toolbar.js b/src/OO.ui.Toolbar.js index faea30a..1556a2b 100644 --- a/src/OO.ui.Toolbar.js +++ b/src/OO.ui.Toolbar.js @@ -62,8 +62,7 @@ /** * Get the tool factory. * - * @method - * @returns {OO.Factory} Tool factory + * @return {OO.Factory} Tool factory */ OO.ui.Toolbar.prototype.getToolFactory = function () { return this.toolFactory; @@ -72,7 +71,6 @@ /** * Handles mouse down events. * - * @method * @param {jQuery.Event} e Mouse down event */ OO.ui.Toolbar.prototype.onMouseDown = function ( e ) { @@ -95,11 +93,11 @@ * Setup toolbar. * * 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: `'*'` - Using this will make the group a list with a "More" label by default * - * @method + * - A specific tool: `{ 'name': 'tool-name' }` or `'tool-name'` + * - All tools in a group: `{ 'group': 'group-name' }` + * - All tools: `'*'` - Using this will make the group a list with a "More" label by default + * * @param {Object.<string,Array>} groups List of tool group configurations * @param {Array|string} [groups.include] Tools to include * @param {Array|string} [groups.exclude] Tools to exclude @@ -198,7 +196,7 @@ * This is a stub that should be overridden to provide access to accelerator information. * * @param {string} name Symbolic name of tool - * @returns {string|undefined} Tool accelerator label if available + * @return {string|undefined} Tool accelerator label if available */ OO.ui.Toolbar.prototype.getToolAccelerator = function () { return undefined; diff --git a/src/OO.ui.Widget.js b/src/OO.ui.Widget.js index 9b33cde..765a78e 100644 --- a/src/OO.ui.Widget.js +++ b/src/OO.ui.Widget.js @@ -1,8 +1,8 @@ /** * User interface control. * - * @class * @abstract + * @class * @extends OO.ui.Element * @mixins OO.EventEmitter * @@ -47,7 +47,6 @@ /** * Check if the widget is disabled. * - * @method * @param {boolean} Button is disabled */ OO.ui.Widget.prototype.isDisabled = function () { @@ -57,7 +56,6 @@ /** * Update the disabled state, in case of changes in parent widget. * - * @method * @chainable */ OO.ui.Widget.prototype.updateDisabled = function () { @@ -70,7 +68,6 @@ * * This should probably change the widgets's appearance and prevent it from being used. * - * @method * @param {boolean} disabled Disable widget * @chainable */ diff --git a/src/OO.ui.Window.js b/src/OO.ui.Window.js index f4d6dbe..9a36bc1 100644 --- a/src/OO.ui.Window.js +++ b/src/OO.ui.Window.js @@ -4,8 +4,8 @@ * There are two ways to specify a title: set the static `title` property or provide a `title` * property in the configuration options. The latter will override the former. * - * @class * @abstract + * @class * @extends OO.ui.Element * @mixins OO.EventEmitter * @@ -112,8 +112,7 @@ /** * Check if window is visible. * - * @method - * @returns {boolean} Window is visible + * @return {boolean} Window is visible */ OO.ui.Window.prototype.isVisible = function () { return this.visible; @@ -122,8 +121,7 @@ /** * Check if window is opening. * - * @method - * @returns {boolean} Window is opening + * @return {boolean} Window is opening */ OO.ui.Window.prototype.isOpening = function () { return this.opening; @@ -132,8 +130,7 @@ /** * Check if window is closing. * - * @method - * @returns {boolean} Window is closing + * @return {boolean} Window is closing */ OO.ui.Window.prototype.isClosing = function () { return this.closing; @@ -142,8 +139,7 @@ /** * Get the window frame. * - * @method - * @returns {OO.ui.Frame} Frame of window + * @return {OO.ui.Frame} Frame of window */ OO.ui.Window.prototype.getFrame = function () { return this.frame; @@ -152,7 +148,7 @@ /** * Get the title of the window. * - * @returns {string} Title text + * @return {string} Title text */ OO.ui.Window.prototype.getTitle = function () { return this.title; @@ -161,7 +157,7 @@ /** * Get the window icon. * - * @returns {string} Symbolic name of icon + * @return {string} Symbolic name of icon */ OO.ui.Window.prototype.getIcon = function () { return this.icon; @@ -220,7 +216,7 @@ }; /** - * Set the position of window to fit with contents.. + * Set the position of window to fit with contents. * * @param {string} left Left offset * @param {string} top Top offset @@ -273,7 +269,6 @@ * * Once this method is called, this.$$ can be used to create elements within the frame. * - * @method * @fires initialize * @chainable */ @@ -314,7 +309,6 @@ * * When you override this method, you must call the parent method at the very beginning. * - * @method * @abstract * @param {Object} [data] Window opening data */ @@ -330,7 +324,6 @@ * * When you override this method, you must call the parent method at the very end. * - * @method * @abstract * @param {Object} [data] Window closing data */ @@ -343,7 +336,6 @@ * * Do not override this method. See #setup for a way to make changes each time the window opens. * - * @method * @param {Object} [data] Window opening data * @fires open * @chainable @@ -370,7 +362,6 @@ * * See #teardown for a way to do something each time the window closes. * - * @method * @param {Object} [data] Window closing data * @fires close * @chainable diff --git a/src/OO.ui.WindowSet.js b/src/OO.ui.WindowSet.js index 147c485..fdc7ade 100644 --- a/src/OO.ui.WindowSet.js +++ b/src/OO.ui.WindowSet.js @@ -20,13 +20,15 @@ this.factory = factory; /** - * List of all windows associated with this window set + * List of all windows associated with this window set. + * * @property {OO.ui.Window[]} */ this.windowList = []; /** * Mapping of OO.ui.Window objects created by name from the #factory. + * * @property {Object} */ this.windows = {}; @@ -73,7 +75,6 @@ /** * Handle a window that's being opened. * - * @method * @param {OO.ui.Window} win Window that's being opened * @param {Object} [config] Window opening information * @fires opening @@ -89,7 +90,6 @@ /** * Handle a window that's been opened. * - * @method * @param {OO.ui.Window} win Window that's been opened * @param {Object} [config] Window opening information * @fires open @@ -101,7 +101,6 @@ /** * Handle a window that's being closed. * - * @method * @param {OO.ui.Window} win Window that's being closed * @param {Object} [config] Window closing information * @fires closing @@ -114,7 +113,6 @@ /** * Handle a window that's been closed. * - * @method * @param {OO.ui.Window} win Window that's been closed * @param {Object} [config] Window closing information * @fires close @@ -126,8 +124,7 @@ /** * Get the current window. * - * @method - * @returns {OO.ui.Window} Current window + * @return {OO.ui.Window} Current window */ OO.ui.WindowSet.prototype.getCurrentWindow = function () { return this.currentWindow; diff --git a/src/OO.ui.js b/src/OO.ui.js index 59a9640..0dec3f9 100644 --- a/src/OO.ui.js +++ b/src/OO.ui.js @@ -9,6 +9,28 @@ OO.ui.bind = $.proxy; /** + * @property {Object} + */ +OO.ui.Keys = { + 'UNDEFINED': 0, + 'BACKSPACE': 8, + 'DELETE': 46, + 'LEFT': 37, + 'RIGHT': 39, + 'UP': 38, + 'DOWN': 40, + 'ENTER': 13, + 'END': 35, + 'HOME': 36, + 'TAB': 9, + 'PAGEUP': 33, + 'PAGEDOWN': 34, + 'ESCAPE': 27, + 'SHIFT': 16, + 'SPACE': 32 +}; + +/** * Get the user's language and any fallback languages. * * These language codes are used to localize user interface elements in the user's language. @@ -16,7 +38,7 @@ * In environments that provide a localization system, this function should be overridden to * return the user's language(s). The default implementation returns English (en) only. * - * @returns {string[]} Language codes, in descending order of priority + * @return {string[]} Language codes, in descending order of priority */ OO.ui.getUserLanguages = function () { return [ 'en' ]; @@ -28,7 +50,7 @@ * @param {Object.<string,Mixed>} obj Object keyed by language code * @param {string|null} [lang] Language code, if omitted or null defaults to any user language * @param {string} [fallback] Fallback code, used if no matching language can be found - * @returns {Mixed} Local value + * @return {Mixed} Local value */ OO.ui.getLocalValue = function ( obj, lang, fallback ) { var i, len, langs; @@ -95,7 +117,7 @@ * @abstract * @param {string} key Message key * @param {Mixed...} [params] Message parameters - * @returns {string} Translated message with parameters substituted + * @return {string} Translated message with parameters substituted */ OO.ui.msg = function ( key ) { var message = messages[key], params = Array.prototype.slice.call( arguments, 1 ); @@ -112,12 +134,14 @@ return message; }; +/** */ OO.ui.deferMsg = function ( key ) { return function () { return OO.ui.msg( key ); }; }; +/** */ OO.ui.resolveMsg = function ( msg ) { if ( $.isFunction( msg ) ) { return msg(); @@ -126,23 +150,3 @@ }; } )(); - -// Add more as you need -OO.ui.Keys = { - 'UNDEFINED': 0, - 'BACKSPACE': 8, - 'DELETE': 46, - 'LEFT': 37, - 'RIGHT': 39, - 'UP': 38, - 'DOWN': 40, - 'ENTER': 13, - 'END': 35, - 'HOME': 36, - 'TAB': 9, - 'PAGEUP': 33, - 'PAGEDOWN': 34, - 'ESCAPE': 27, - 'SHIFT': 16, - 'SPACE': 32 -}; -- To view, visit https://gerrit.wikimedia.org/r/117232 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: merged Gerrit-Change-Id: Iaaf547db2becedbbcaecee6b35a2217c6cbb8f3b Gerrit-PatchSet: 1 Gerrit-Project: oojs/ui Gerrit-Branch: master Gerrit-Owner: Krinkle <krinklem...@gmail.com> Gerrit-Reviewer: Krinkle <krinklem...@gmail.com> Gerrit-Reviewer: Trevor Parscal <tpars...@wikimedia.org> Gerrit-Reviewer: jenkins-bot <> _______________________________________________ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits