From 8dfdeec6a84414522e905e5533ab25443d5a08c9 Mon Sep 17 00:00:00 2001 From: "James D. Forrester" Date: Sat, 5 Sep 2015 13:16:23 -0700 Subject: [PATCH] build: Enable all remaining jsduck jsDoc rules except two Enabling 'checkAnnotations' with a set of extra tags bespoke to this repo, and 'checkRedudantAccess' means we're pretty close to compliant in core. Leaving 'checkRedundantParams' and 'checkReturnTypes' off for now. Change-Id: I89c4d5250fee30fdfd87a68e173cf222c08cab32 --- .jscsrc | 10 ++++ resources/src/jquery/jquery.placeholder.js | 3 +- resources/src/jquery/jquery.tablesorter.js | 49 +++++++------------ resources/src/jquery/jquery.textSelection.js | 8 +-- .../mw.widgets.CalendarWidget.js | 8 +-- .../mw.widgets.DateInputWidget.js | 6 +-- .../mw.widgets.TitleWidget.js | 4 +- .../mw.widgets.UserInputWidget.js | 2 +- .../mediawiki.Upload.BookletLayout.js | 16 +++--- .../src/mediawiki/mediawiki.Upload.Dialog.js | 1 - resources/src/mediawiki/mediawiki.Uri.js | 5 +- .../src/mediawiki/mediawiki.experiments.js | 2 +- resources/src/mediawiki/mediawiki.feedback.js | 2 +- .../src/mediawiki/mediawiki.notification.js | 7 +-- 14 files changed, 59 insertions(+), 64 deletions(-) diff --git a/.jscsrc b/.jscsrc index c1fbc9ae49..3b94b90f07 100644 --- a/.jscsrc +++ b/.jscsrc @@ -7,7 +7,17 @@ "disallowQuotedKeysInObjects": "allButReserved", "requireDotNotation": { "allExcept": [ "keywords" ] }, "jsDoc": { + "checkAnnotations": { + "preset": "jsduck5", + "extra": { + "context": true, + "source": true, + "see": true, + "private": true + } + }, "checkParamNames": true, + "checkRedundantAccess": true, "checkRedundantReturns": true, "checkTypes": "strictNativeCase", "requireNewlineAfterDescription": true, diff --git a/resources/src/jquery/jquery.placeholder.js b/resources/src/jquery/jquery.placeholder.js index 9c18a919c1..c472ac7b58 100644 --- a/resources/src/jquery/jquery.placeholder.js +++ b/resources/src/jquery/jquery.placeholder.js @@ -1,4 +1,4 @@ -/** +/*! * HTML5 placeholder emulation for jQuery plugin * * This will automatically use the HTML5 placeholder attribute if supported, or emulate this behavior if not. @@ -13,6 +13,7 @@ * @version 2.1.0 * @license MIT */ + ( function ( $ ) { var isInputSupported = 'placeholder' in document.createElement( 'input' ), diff --git a/resources/src/jquery/jquery.tablesorter.js b/resources/src/jquery/jquery.tablesorter.js index c39dc55af3..2318b33a19 100644 --- a/resources/src/jquery/jquery.tablesorter.js +++ b/resources/src/jquery/jquery.tablesorter.js @@ -1,4 +1,4 @@ -/** +/*! * TableSorter for MediaWiki * * Written 2011 Leo Koppelkamm @@ -12,52 +12,37 @@ * and mw.language.months. * * Uses 'tableSorterCollation' in mw.config (if available) - */ -/** * - * @description Create a sortable table with multi-column sorting capabilities + * Create a sortable table with multi-column sorting capabilities * - * @example $( 'table' ).tablesorter(); - * @desc Create a simple tablesorter interface. + * // Create a simple tablesorter interface + * $( 'table' ).tablesorter(); * - * @example $( 'table' ).tablesorter( { sortList: [ { 0: 'desc' }, { 1: 'asc' } ] } ); - * @desc Create a tablesorter interface initially sorting on the first and second column. + * // Create a tablesorter interface, initially sorting on the first and second column + * $( 'table' ).tablesorter( { sortList: [ { 0: 'desc' }, { 1: 'asc' } ] } ); * - * @option String cssHeader ( optional ) A string of the class name to be appended - * to sortable tr elements in the thead of the table. Default value: - * "header" + * @param {string} [cssHeader="header"] A string of the class name to be appended to sortable + * tr elements in the thead of the table. * - * @option String cssAsc ( optional ) A string of the class name to be appended to - * sortable tr elements in the thead on a ascending sort. Default value: - * "headerSortUp" + * @param {string} [cssAsc="headerSortUp"] A string of the class name to be appended to + * sortable tr elements in the thead on a ascending sort. * - * @option String cssDesc ( optional ) A string of the class name to be appended - * to sortable tr elements in the thead on a descending sort. Default - * value: "headerSortDown" + * @param {string} [cssDesc="headerSortDown"] A string of the class name to be appended to + * sortable tr elements in the thead on a descending sort. * - * @option String sortMultisortKey ( optional ) A string of the multi-column sort - * key. Default value: "shiftKey" + * @param {string} [sortMultisortKey="shiftKey"] A string of the multi-column sort key. * - * @option Boolean cancelSelection ( optional ) Boolean flag indicating if - * tablesorter should cancel selection of the table headers text. - * Default value: true + * @param {boolean} [cancelSelection=true] Boolean flag indicating iftablesorter should cancel + * selection of the table headers text. * - * @option Array sortList ( optional ) An array containing objects specifying sorting. - * By passing more than one object, multi-sorting will be applied. Object structure: + * @param {Array} [sortList] An array containing objects specifying sorting. By passing more + * than one object, multi-sorting will be applied. Object structure: * { : } - * Default value: [] * * @event sortEnd.tablesorter: Triggered as soon as any sorting has been applied. * - * @type jQuery - * - * @name tablesorter - * - * @cat Plugins/Tablesorter - * * @author Christian Bach/christian.bach@polyester.se */ - ( function ( $, mw ) { var ts, parsers = []; diff --git a/resources/src/jquery/jquery.textSelection.js b/resources/src/jquery/jquery.textSelection.js index b901642495..5e93ba62c1 100644 --- a/resources/src/jquery/jquery.textSelection.js +++ b/resources/src/jquery/jquery.textSelection.js @@ -96,7 +96,7 @@ * Inserts text at the beginning and end of a text selection, optionally * inserting text at the caret when selection is empty. * - * @fixme document the options parameters + * FIXME document the options parameters */ encapsulateSelection: function ( options ) { return this.each( function () { @@ -268,7 +268,7 @@ * * Will focus the textarea in some browsers (IE/Opera) * - * @fixme document the options parameters + * FIXME document the options parameters */ getCaretPosition: function ( options ) { function getCaret( e ) { @@ -367,7 +367,7 @@ return getCaret( this.get( 0 ) ); }, /** - * @fixme document the options parameters + * FIXME document the options parameters */ setSelection: function ( options ) { return this.each( function () { @@ -415,7 +415,7 @@ * @param {boolean} options Whether to force a scroll even if the caret position * is already visible. Defaults to false * - * @fixme document the options parameters (function body suggests options.force is a boolean, not options itself) + * FIXME document the options parameters (function body suggests options.force is a boolean, not options itself) */ scrollToCaretPosition: function ( options ) { function getLineLength( e ) { diff --git a/resources/src/mediawiki.widgets/mw.widgets.CalendarWidget.js b/resources/src/mediawiki.widgets/mw.widgets.CalendarWidget.js index d5e5b960c8..7a7b9cda0f 100644 --- a/resources/src/mediawiki.widgets/mw.widgets.CalendarWidget.js +++ b/resources/src/mediawiki.widgets/mw.widgets.CalendarWidget.js @@ -119,7 +119,7 @@ * internally and for dates accepted by #setDate and returned by #getDate. * * @private - * @returns {string} Format + * @return {string} Format */ mw.widgets.CalendarWidget.prototype.getDateFormat = function () { return { @@ -132,7 +132,7 @@ * Get the date precision this calendar uses, 'day' or 'month'. * * @private - * @returns {string} Precision, 'day' or 'month' + * @return {string} Precision, 'day' or 'month' */ mw.widgets.CalendarWidget.prototype.getPrecision = function () { return this.precision; @@ -142,7 +142,7 @@ * Get list of possible display layers. * * @private - * @returns {string[]} Layers + * @return {string[]} Layers */ mw.widgets.CalendarWidget.prototype.getDisplayLayers = function () { return [ 'month', 'year', 'duodecade' ].slice( this.precision === 'month' ? 1 : 0 ); @@ -462,7 +462,7 @@ * Get current date, in the format 'YYYY-MM-DD' or 'YYYY-MM', depending on precision. Digits will * not be localised. * - * @returns {string|null} Date string + * @return {string|null} Date string */ mw.widgets.CalendarWidget.prototype.getDate = function () { return this.date; diff --git a/resources/src/mediawiki.widgets/mw.widgets.DateInputWidget.js b/resources/src/mediawiki.widgets/mw.widgets.DateInputWidget.js index b1e5151bc5..1ffcc66191 100644 --- a/resources/src/mediawiki.widgets/mw.widgets.DateInputWidget.js +++ b/resources/src/mediawiki.widgets/mw.widgets.DateInputWidget.js @@ -536,7 +536,7 @@ * @private * @param {string} date Date string, to be valid, must be in 'YYYY-MM-DD' or 'YYYY-MM' format or * (unless the field is required) empty - * @returns {boolean} + * @return {boolean} */ mw.widgets.DateInputWidget.prototype.validateDate = function ( date ) { var isValid; @@ -551,7 +551,7 @@ /** * @private * @param {string} date Date string, to be valid, must be in 'YYYY-MM-DD' or 'YYYY-MM' format - * @returns {boolean} + * @return {boolean} */ mw.widgets.DateInputWidget.prototype.isValidDate = function ( date ) { // "Half-strict mode": for example, for the format 'YYYY-MM-DD', 2015-1-3 instead of 2015-01-03 @@ -571,7 +571,7 @@ * @private * @param {string} date Date string, to be valid, must be empty (no date selected) or in * 'YYYY-MM-DD' or 'YYYY-MM' format to be valid - * @returns {boolean} + * @return {boolean} */ mw.widgets.DateInputWidget.prototype.isInRange = function ( date ) { var momentDate = moment( date, 'YYYY-MM-DD' ), diff --git a/resources/src/mediawiki.widgets/mw.widgets.TitleWidget.js b/resources/src/mediawiki.widgets/mw.widgets.TitleWidget.js index 76fe9595e9..67f3e01c1c 100644 --- a/resources/src/mediawiki.widgets/mw.widgets.TitleWidget.js +++ b/resources/src/mediawiki.widgets/mw.widgets.TitleWidget.js @@ -155,7 +155,7 @@ * Get option widgets from the server response * * @param {Object} data Query result - * @returns {OO.ui.OptionWidget[]} Menu items + * @return {OO.ui.OptionWidget[]} Menu items */ mw.widgets.TitleWidget.prototype.getOptionsFromData = function ( data ) { var i, len, index, pageExists, pageExistsExact, suggestionPage, page, redirect, redirects, @@ -269,7 +269,7 @@ * Get title object corresponding to given value, or #getQueryValue if not given. * * @param {string} [value] Value to get a title for - * @returns {mw.Title|null} Title object, or null if value is invalid + * @return {mw.Title|null} Title object, or null if value is invalid */ mw.widgets.TitleWidget.prototype.getTitle = function ( value ) { var title = value !== undefined ? value : this.getQueryValue(), diff --git a/resources/src/mediawiki.widgets/mw.widgets.UserInputWidget.js b/resources/src/mediawiki.widgets/mw.widgets.UserInputWidget.js index 0d0fb735fa..164fd20d0a 100644 --- a/resources/src/mediawiki.widgets/mw.widgets.UserInputWidget.js +++ b/resources/src/mediawiki.widgets/mw.widgets.UserInputWidget.js @@ -99,7 +99,7 @@ * Get list of menu items from a server response. * * @param {Object} data Query result - * @returns {OO.ui.MenuOptionWidget[]} Menu items + * @return {OO.ui.MenuOptionWidget[]} Menu items */ mw.widgets.UserInputWidget.prototype.getLookupMenuOptionsFromData = function ( data ) { var len, i, user, diff --git a/resources/src/mediawiki/mediawiki.Upload.BookletLayout.js b/resources/src/mediawiki/mediawiki.Upload.BookletLayout.js index c616829d89..4ce2c1a4e3 100644 --- a/resources/src/mediawiki/mediawiki.Upload.BookletLayout.js +++ b/resources/src/mediawiki/mediawiki.Upload.BookletLayout.js @@ -218,7 +218,7 @@ * * @protected * @fires fileSaved - * @returns {jQuery.Promise} Rejects the promise with an + * @return {jQuery.Promise} Rejects the promise with an * {@link OO.ui.Error error}, or resolves if the upload was successful. */ mw.Upload.BookletLayout.prototype.saveFile = function () { @@ -253,7 +253,7 @@ * state and state details. * * @protected - * @returns {OO.ui.Error} Error to display for given state and details. + * @return {OO.ui.Error} Error to display for given state and details. */ mw.Upload.BookletLayout.prototype.getErrorMessageForStateDetails = function () { var message, @@ -370,7 +370,7 @@ * * @protected * @fires selectFile - * @returns {OO.ui.FormLayout} + * @return {OO.ui.FormLayout} */ mw.Upload.BookletLayout.prototype.renderUploadForm = function () { var fieldset; @@ -402,7 +402,7 @@ * property. * * @protected - * @returns {OO.ui.FormLayout} + * @return {OO.ui.FormLayout} */ mw.Upload.BookletLayout.prototype.renderInfoForm = function () { var fieldset; @@ -464,7 +464,7 @@ * sets the {@link #insertForm insertForm} property. * * @protected - * @returns {OO.ui.FormLayout} + * @return {OO.ui.FormLayout} */ mw.Upload.BookletLayout.prototype.renderInsertForm = function () { var fieldset; @@ -491,7 +491,7 @@ * {@link #uploadForm upload form}. * * @protected - * @returns {File|null} + * @return {File|null} */ mw.Upload.BookletLayout.prototype.getFile = function () { return this.selectFileWidget.getValue(); @@ -502,7 +502,7 @@ * {@link #infoForm information form}. * * @protected - * @returns {string} + * @return {string} */ mw.Upload.BookletLayout.prototype.getFilename = function () { return this.filenameWidget.getValue(); @@ -513,7 +513,7 @@ * {@link #infoForm information form}. * * @protected - * @returns {string} + * @return {string} */ mw.Upload.BookletLayout.prototype.getText = function () { return this.descriptionWidget.getValue(); diff --git a/resources/src/mediawiki/mediawiki.Upload.Dialog.js b/resources/src/mediawiki/mediawiki.Upload.Dialog.js index 53afca812d..5f2569c404 100644 --- a/resources/src/mediawiki/mediawiki.Upload.Dialog.js +++ b/resources/src/mediawiki/mediawiki.Upload.Dialog.js @@ -211,5 +211,4 @@ this.uploadBooklet.clear(); }, this ); }; - }( jQuery, mediaWiki ) ); diff --git a/resources/src/mediawiki/mediawiki.Uri.js b/resources/src/mediawiki/mediawiki.Uri.js index 9d29b4cd74..ba5ece8753 100644 --- a/resources/src/mediawiki/mediawiki.Uri.js +++ b/resources/src/mediawiki/mediawiki.Uri.js @@ -158,12 +158,11 @@ }() ); /** - * @class mw.Uri - * @constructor - * * Construct a new URI object. Throws error if arguments are illegal/impossible, or * otherwise don't parse. * + * @class mw.Uri + * @constructor * @param {Object|string} [uri] URI string, or an Object with appropriate properties (especially * another URI object to clone). Object must have non-blank `protocol`, `host`, and `path` * properties. If omitted (or set to `undefined`, `null` or empty string), then an object diff --git a/resources/src/mediawiki/mediawiki.experiments.js b/resources/src/mediawiki/mediawiki.experiments.js index b62e8d1037..ad1069feda 100644 --- a/resources/src/mediawiki/mediawiki.experiments.js +++ b/resources/src/mediawiki/mediawiki.experiments.js @@ -76,7 +76,7 @@ * that the user will be assigned to that bucket * @param {string} token A token that uniquely identifies the user for the * duration of the experiment - * @returns {string} The bucket + * @return {string} The bucket */ getBucket: function ( experiment, token ) { var buckets = experiment.buckets, diff --git a/resources/src/mediawiki/mediawiki.feedback.js b/resources/src/mediawiki/mediawiki.feedback.js index d226ed9d6a..68818be499 100644 --- a/resources/src/mediawiki/mediawiki.feedback.js +++ b/resources/src/mediawiki/mediawiki.feedback.js @@ -497,7 +497,7 @@ /** * Get the bug report link * - * @returns {string} Link to the external bug report form + * @return {string} Link to the external bug report form */ mw.Feedback.Dialog.prototype.getBugReportLink = function () { return this.bugReportLink; diff --git a/resources/src/mediawiki/mediawiki.notification.js b/resources/src/mediawiki/mediawiki.notification.js index 3f7b8fdc72..36b45f177f 100644 --- a/resources/src/mediawiki/mediawiki.notification.js +++ b/resources/src/mediawiki/mediawiki.notification.js @@ -16,11 +16,12 @@ * The underscore in the name is to avoid a bug . * It is not part of the actual class name. * + * The constructor is not publicly accessible; use mw.notification#notify instead. + * This does not insert anything into the document (see #start). + * * @class mw.Notification_ * @alternateClassName mw.Notification - * - * @constructor The constructor is not publicly accessible; use mw.notification#notify instead. - * This does not insert anything into the document (see #start). + * @constructor * @private */ function Notification( message, options ) { -- 2.20.1