jenkins-bot has submitted this change and it was merged. Change subject: Document code with JSDuck ......................................................................
Document code with JSDuck Change-Id: Ieb812a2fb85135f6db18a9a02c94efd83695a19e --- M .gitignore A jsduck.external.js A jsduck.json M modules/ext.templateDataGenerator.data.js M modules/ext.templateDataGenerator.editPage.js M modules/ext.templateDataGenerator.ui.js M modules/ext.templateDataGenerator.ui.tdDialog.js M modules/widgets/ext.templateDataGenerator.dragDropWidget.js M modules/widgets/ext.templateDataGenerator.languageSearchWidget.js M package.json 10 files changed, 81 insertions(+), 15 deletions(-) Approvals: Jforrester: Looks good to me, approved jenkins-bot: Verified diff --git a/.gitignore b/.gitignore index 02b1abb..ecfc87b 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ *~ *.kate-swp .*.swp +/docs node_modules composer.lock vendor diff --git a/jsduck.external.js b/jsduck.external.js new file mode 100644 index 0000000..850c92a --- /dev/null +++ b/jsduck.external.js @@ -0,0 +1,14 @@ +/** + * @class jQuery + * <http://api.jquery.com/> + */ + +/** + * @class jQuery.Event + * <http://api.jquery.com/Types/#Event> + */ + +/** + * @class jQuery.Promise + * <http://api.jquery.com/Types/#Promise> + */ diff --git a/jsduck.json b/jsduck.json new file mode 100644 index 0000000..024956b --- /dev/null +++ b/jsduck.json @@ -0,0 +1,11 @@ +{ + "--title": "TemplateData - Documentation", + "--processes": "0", + "--warnings-exit-nonzero": true, + "--external": "OO.*", + "--output": "docs", + "--": [ + "jsduck.external.js", + "modules" + ] +} diff --git a/modules/ext.templateDataGenerator.data.js b/modules/ext.templateDataGenerator.data.js index 68c2277..7e3f85b 100644 --- a/modules/ext.templateDataGenerator.data.js +++ b/modules/ext.templateDataGenerator.data.js @@ -1,5 +1,9 @@ /** * TemplateData Dialog + * @class + * @mixins OO.EventEmitter + * + * @constructor * @param {Object} config Dialog configuration object */ mw.TemplateData.Model = function mwTemplateDataModel( config ) { diff --git a/modules/ext.templateDataGenerator.editPage.js b/modules/ext.templateDataGenerator.editPage.js index 580d660..da75303 100644 --- a/modules/ext.templateDataGenerator.editPage.js +++ b/modules/ext.templateDataGenerator.editPage.js @@ -1,5 +1,5 @@ ( function () { - /** + /*! * TemplateData Generator button fixture * The button will appear on Template namespaces only, above the edit textbox * diff --git a/modules/ext.templateDataGenerator.ui.js b/modules/ext.templateDataGenerator.ui.js index 285f5c5..6f8bbb5 100644 --- a/modules/ext.templateDataGenerator.ui.js +++ b/modules/ext.templateDataGenerator.ui.js @@ -1,33 +1,31 @@ ( function () { + 'use strict'; /** * TemplateData Generator data model. * This singleton is independent of any UI; it expects * a templatedata string, converts it into the object * model and manages it, fully event-driven. * - * @author Moriel Schottlender + * @class + * @singleton */ - 'use strict'; mw.libs.tdgUi = ( function () { var isPageSubLevel, isDocPage, pageName, parentPage, $textbox, - /** - * ooui Window Manager - */ + // ooui Window Manager tdgDialog, windowManager, - /** - * Edit window elements - */ + // Edit window elements editOpenDialogButton, editNoticeLabel, editArea = { /** * Display error message in the edit window + * * @param {string} msg Message to display * @param {string} type Message type 'notice' or 'error' * @param {boolean} [parseHTML] The message should be parsed @@ -57,6 +55,8 @@ /** * Respond to edit dialog button click. + * + * @method onEditOpenDialogButton */ onEditOpenDialogButton = function () { // Reset notice message @@ -73,6 +73,8 @@ /** * Respond to edit dialog apply event + * + * @method onDialogApply * @param {string} templateDataString New templatedata string */ onDialogApply = function ( templateDataString ) { @@ -82,6 +84,8 @@ /** * Replace the old templatedata string with the new one, or * insert the new one into the page if an old one doesn't exist + * + * @method replaceTemplateData * @param {string} newTemplateData New templatedata string * @return {string} Full wikitext content with the new templatedata * string. diff --git a/modules/ext.templateDataGenerator.ui.tdDialog.js b/modules/ext.templateDataGenerator.ui.tdDialog.js index 564a074..cf742e0 100644 --- a/modules/ext.templateDataGenerator.ui.tdDialog.js +++ b/modules/ext.templateDataGenerator.ui.tdDialog.js @@ -1,5 +1,10 @@ /** * TemplateData Dialog + * + * @class + * @extends OO.ui.ProcessDialog + * + * @constructor * @param {Object} config Dialog configuration object */ mw.TemplateData.Dialog = function mwTemplateDataDialog( config ) { @@ -56,7 +61,14 @@ ]; /** - * @inheritdoc + * Initialize window contents. + * + * The first time the window is opened, #initialize is called so that changes to the window that + * will persist between openings can be made. See #getSetupProcess for a way to make changes each + * time the window opens. + * + * @throws {Error} If not attached to a manager + * @chainable */ mw.TemplateData.Dialog.prototype.initialize = function () { var templateParamsFieldset, addParamFieldlayout, languageActionFieldLayout, @@ -223,6 +235,10 @@ this.descriptionInput.setValue( description ); }; +/** + * Respond to add param input change. + * @param {string} value New parameter name + */ mw.TemplateData.Dialog.prototype.onAddParamInputChange = function ( value ) { var allProps = mw.TemplateData.Model.static.getAllProperties( true ); @@ -278,12 +294,18 @@ this.paramOrderWidget.addItems( [ dragItem ] ); }; +/** + * Respond to param order widget reorder event + * @param {mw.TemplateData.DragDropItemWidget} item Item reordered + * @param {number} newIndex New index of the item + */ mw.TemplateData.Dialog.prototype.onParamOrderWidgetReorder = function ( item, newIndex ) { this.model.reorderParamOrderKey( item.getData(), newIndex ); }; /** * Respond to description input change event + * @param {string} value Description value */ mw.TemplateData.Dialog.prototype.onDescriptionInputChange = function ( value ) { if ( this.model.getTemplateDescription() !== value ) { @@ -732,7 +754,9 @@ }; /** - * @inheritdoc + * Get a process for setting up a window for use. + * + * @param {Object} [data] Dialog opening data */ mw.TemplateData.Dialog.prototype.getSetupProcess = function ( data ) { return mw.TemplateData.Dialog.super.prototype.getSetupProcess.call( this, data ) @@ -874,7 +898,10 @@ }; /** - * @inheritdoc + * Get a process for taking action. + * + * @param {string} [action] Symbolic name of action + * @return {OO.ui.Process} Action process */ mw.TemplateData.Dialog.prototype.getActionProcess = function ( action ) { if ( action === 'back' ) { diff --git a/modules/widgets/ext.templateDataGenerator.dragDropWidget.js b/modules/widgets/ext.templateDataGenerator.dragDropWidget.js index b00bf45..c49ec8f 100644 --- a/modules/widgets/ext.templateDataGenerator.dragDropWidget.js +++ b/modules/widgets/ext.templateDataGenerator.dragDropWidget.js @@ -49,7 +49,7 @@ * Reorder the key into its new index. Find the item first, then add * it back in its new place. * @param {string} key Unique key - * @param {[type]} newIndex New index + * @param {number} newIndex New index */ mw.TemplateData.DragDropWidget.prototype.reorderKey = function ( key, newIndex ) { var i, len, item; diff --git a/modules/widgets/ext.templateDataGenerator.languageSearchWidget.js b/modules/widgets/ext.templateDataGenerator.languageSearchWidget.js index 94ab009..f835ec5 100644 --- a/modules/widgets/ext.templateDataGenerator.languageSearchWidget.js +++ b/modules/widgets/ext.templateDataGenerator.languageSearchWidget.js @@ -48,7 +48,11 @@ /* Methods */ /** - * @inheritdoc + * Handle select widget select events. + * + * Clears existing results. Subclasses should repopulate items according to new query. + * + * @param {string} value New value */ mw.TemplateData.LanguageSearchWidget.prototype.onQueryChange = function () { // Parent method diff --git a/package.json b/package.json index e6f633e..b43d5be 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,8 @@ "name": "templatedata", "version": "0.0.0", "scripts": { - "test": "grunt test" + "test": "grunt test", + "doc": "jsduck" }, "repository": { "type": "git", -- To view, visit https://gerrit.wikimedia.org/r/194997 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: merged Gerrit-Change-Id: Ieb812a2fb85135f6db18a9a02c94efd83695a19e Gerrit-PatchSet: 4 Gerrit-Project: mediawiki/extensions/TemplateData Gerrit-Branch: master Gerrit-Owner: Krinkle <krinklem...@gmail.com> Gerrit-Reviewer: Jforrester <jforres...@wikimedia.org> Gerrit-Reviewer: Krinkle <krinklem...@gmail.com> Gerrit-Reviewer: Mooeypoo <mor...@gmail.com> Gerrit-Reviewer: jenkins-bot <> _______________________________________________ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
