jenkins-bot has submitted this change and it was merged.
Change subject: build: Enable jscs-jsdoc's 'requireParamTypes' rule and make
pass
......................................................................
build: Enable jscs-jsdoc's 'requireParamTypes' rule and make pass
Change-Id: I79bb4053b0bd29c4214b2665b40e03cc6eac0de1
---
M .jscsrc
M resources/mw.FlickrChecker.js
M resources/mw.GroupProgressBar.js
M resources/mw.LanguageUpWiz.js
M resources/mw.UploadWizard.js
M resources/mw.UploadWizardDescription.js
M resources/mw.UploadWizardDetails.js
M resources/mw.UploadWizardLicenseInput.js
M resources/mw.UploadWizardUpload.js
M resources/mw.UploadWizardUploadInterface.js
M resources/ui/uw.ui.Thanks.js
M resources/ui/uw.ui.Upload.js
M resources/uw.EventFlowLogger.js
13 files changed, 70 insertions(+), 69 deletions(-)
Approvals:
Bartosz Dziewoński: Looks good to me, approved
jenkins-bot: Verified
diff --git a/.jscsrc b/.jscsrc
index f049b84..dcb0f23 100644
--- a/.jscsrc
+++ b/.jscsrc
@@ -8,6 +8,7 @@
"see": true
}
},
+ "requireParamTypes": true,
"requireReturnTypes": true
},
diff --git a/resources/mw.FlickrChecker.js b/resources/mw.FlickrChecker.js
index 62e03af..e645d49 100644
--- a/resources/mw.FlickrChecker.js
+++ b/resources/mw.FlickrChecker.js
@@ -60,9 +60,9 @@
* retrieved, do nothing. Note that the license look-up system
is fragile on purpose. If Flickr
* changes the name associated with a license ID, it's better
for the lookup to fail than to use
* an incorrect license.
- * @param url - the source URL to check
- * @param $selector - the element to insert the license name
into
- * @param upload - the upload object to set the deed for
+ * @param {string} url The source URL to check
+ * @param {string} $selector The element to insert the license
name into
+ * @param {UploadWizardUpload} upload The upload object to set
the deed for
*/
checkFlickr: function ( flickrInputUrl ) {
var photoIdMatches, albumIdMatches,
userCollectionMatches, userPhotostreamMatches, groupPoolMatches,
userGalleryMatches, userFavoritesMatches;
@@ -182,7 +182,7 @@
/**
* Retrieves a list of photos in group pool and displays it.
*
- * @param groupPoolMatches result of `this.url.match`
+ * @param {object} groupPoolMatches Result of `this.url.match`
* @see {@link getPhotos}
*/
getGroupPool: function ( groupPoolMatches ) {
@@ -215,9 +215,9 @@
/**
* Constructs an unordered list of sets in the collection.
*
- * @param appendId true if you want to append
+ * @param {boolean} appendId True if you want to append
* id="mwe-upwiz-files-collection-chooser"; false otherwise
- * @param data the retrieved data
+ * @param {Object} data The retrieved data
* @see {@link getCollection}
*/
buildCollectionLinks: function ( appendId, data ) {
@@ -257,7 +257,7 @@
/**
* Retrieves a list of sets in a collection and displays it.
*
- * @param userCollectionMatches result of this.url.match
+ * @param {Object} userCollectionMatches Result of
this.url.match
*/
getCollection: function ( userCollectionMatches ) {
var that = this;
@@ -300,7 +300,7 @@
/**
* Retrieves a list of photos in photoset and displays it.
*
- * @param albumIdMatches result of this.url.match
+ * @param {Object} albumIdMatches Result of this.url.match
* @see {@link getPhotos}
*/
getPhotoset: function ( albumIdMatches ) {
@@ -618,7 +618,7 @@
/**
* Retrieve the URL of the largest version available on Flickr
and set that
* as the upload URL.
- * @param index Index of the image we need to set the URL for
+ * @param {number} index Index of the image for which we need
to set the URL
*/
setImageURL: function ( index ) {
var largestSize,
diff --git a/resources/mw.GroupProgressBar.js b/resources/mw.GroupProgressBar.js
index 4b5ec17..d7796d8 100644
--- a/resources/mw.GroupProgressBar.js
+++ b/resources/mw.GroupProgressBar.js
@@ -117,7 +117,7 @@
* sets the beginning time (useful for figuring out estimated
time remaining)
* if time parameter omitted, will set beginning time to now
*
- * @param time optional; the time this bar is presumed to have
started (epoch milliseconds)
+ * @param {number} [time] The time this bar is presumed to have
started (epoch milliseconds)
*/
setBeginTime: function ( time ) {
this.beginTime = time ? time : ( new Date() ).getTime();
@@ -129,7 +129,7 @@
* We did some tricky calculations in startUploads to try to
weight each individual file's progress against
* the overall progress.
*
- * @param fraction the amount of whatever it is that's done
whatever it's done
+ * @param {number} fraction The amount of whatever it is that's
done whatever it's done
*/
showProgress: function ( fraction ) {
var t, timeString,
@@ -154,8 +154,8 @@
/**
* Calculate remaining time for all uploads to complete.
*
- * @param fraction fraction of progress to show
- * @return {number} estimated time remaining (in milliseconds)
+ * @param {number} fraction Fraction of progress to show
+ * @return {number} Estimated time remaining (in milliseconds)
*/
getRemainingTime: function ( fraction ) {
var elapsedTime, rate;
@@ -172,7 +172,7 @@
/**
* Show the overall count as we upload
*
- * @param count -- the number of items that have done whatever
has been done e.g. in "uploaded 2 of 5", this is the 2
+ * @param {number} count The number of items that have done
whatever has been done e.g. in "uploaded 2 of 5", this is the 2
*/
showCount: function ( count ) {
this.$selector
diff --git a/resources/mw.LanguageUpWiz.js b/resources/mw.LanguageUpWiz.js
index 441e2b6..523e998 100644
--- a/resources/mw.LanguageUpWiz.js
+++ b/resources/mw.LanguageUpWiz.js
@@ -85,9 +85,9 @@
/**
* Get an HTML select menu of all our languages.
*
- * @param name desired name of select element
- * @param code selected language code
- * @return {HTML} select element configured as desired
+ * @param {string} name Desired name of select element
+ * @param {string} code Selected language code
+ * @return {HTML} The `select` element configured as desired
*/
getMenu: function ( name, code ) {
var $select;
@@ -131,9 +131,9 @@
* Otherwise, if handed "foo-bar-baz" language, try to match
most specific language,
* "foo-bar-baz", then "foo-bar", then "foo"
*
- * @param code A string representing a language code, which we
may or may not have.
+ * @param {string} code A string representing a language code,
which we may or may not have.
* Expected to be separated with
dashes as codes from ISO 639, e.g. "zh-tw" for Chinese ( Traditional )
- * @return {string} a language code which is close to the
supplied parameter, or fall back to mw.LanguageUpWiz.defaultCode
+ * @return {string} A language code which is close to the
supplied parameter, or fall back to mw.LanguageUpWiz.defaultCode
*/
getClosest: function ( code ) {
mw.LanguageUpWiz.initialize();
diff --git a/resources/mw.UploadWizard.js b/resources/mw.UploadWizard.js
index 14ea458..c67ab99 100644
--- a/resources/mw.UploadWizard.js
+++ b/resources/mw.UploadWizard.js
@@ -322,7 +322,7 @@
* When an upload is filled with a real file, accept it in the
wizard's list of uploads
* and set up some other interfaces
*
- * @param UploadWizardUpload
+ * @param {UploadWizardUpload} upload
*/
setUploadFilled: function ( upload ) {
this.uploads.push( upload );
@@ -337,7 +337,7 @@
* We need to grep through the array of uploads, since we don't
know the current index.
* We need to update file counts for obvious reasons.
*
- * @param upload
+ * @param {UploadWizardUpload} upload
*/
removeUpload: function ( upload ) {
// remove the div that passed along the trigger
@@ -394,7 +394,7 @@
* This is useful to clean out file inputs that we don't want
for some reason (error, empty...)
* We are using a second array to iterate, because we will be
splicing the main one, _this.uploads
*
- * @param Function criterion: function to test the upload,
returns boolean; true if should be removed
+ * @param {function} criterion Function to test the upload,
returns boolean; true if should be removed
*/
removeMatchingUploads: function ( criterion ) {
var toRemove = [];
@@ -506,8 +506,8 @@
* or with function and id -- function will be called to generate the
hint every time
* TODO v1.1 split into two plugins?
*
- * @param key {string} -- will base the tooltip on a message found
with this key
- * @param fn {function} optional -- call this function every time tip
is created to generate message. If present HTML element gets an id of the exact
key specified
+ * @param {string} key Will base the tooltip on a message found with
this key
+ * @param {function} [fn] Call this function every time tip is created
to generate message. If present, HTML element gets an id of the exact key
specified
*/
$.fn.addHint = function ( key, fn ) {
var attrs, contentSource, html = false;
diff --git a/resources/mw.UploadWizardDescription.js
b/resources/mw.UploadWizardDescription.js
index 2f56fc4..f597274 100644
--- a/resources/mw.UploadWizardDescription.js
+++ b/resources/mw.UploadWizardDescription.js
@@ -2,8 +2,9 @@
/**
* Object that represents an indvidual language description, in the
details portion of Upload Wizard
*
- * @param languageCode -- string
- * @param required -- boolean -- the first description is required and
should be validated and displayed a bit differently
+ * @param {string} languageCode
+ * @param {boolean} required The first description is required and
should be validated and displayed a bit differently
+ * @param {string} [initialValue] If set, an initial value to which to
set the language.
*/
mw.UploadWizardDescription = function ( languageCode, required,
initialValue ) {
var errorLabelDiv, fieldnameDiv;
diff --git a/resources/mw.UploadWizardDetails.js
b/resources/mw.UploadWizardDetails.js
index 06ba8b5..cd909b1 100644
--- a/resources/mw.UploadWizardDetails.js
+++ b/resources/mw.UploadWizardDetails.js
@@ -1,15 +1,14 @@
-/**
- * Object that represents the Details (step 2) portion of the UploadWizard
- * n.b. each upload gets its own details.
- *
- * @param UploadWizardUpload
- * @param API
- * @param containerDiv The div to put the interface into
- */
( function ( mw, uw, $, OO ) {
var NS_FILE = mw.config.get( 'wgNamespaceIds' ).file;
+ /**
+ * Object that represents the Details (step 2) portion of the
UploadWizard
+ * n.b. each upload gets its own details.
+ *
+ * @param {UploadWizardUpload} upload
+ * @param {HTML} containerDiv The div to put the interface into
+ */
mw.UploadWizardDetails = function ( upload, containerDiv ) {
var descriptionAdderDiv, titleContainerDiv, $categoriesDiv,
categoriesHinter,
@@ -963,7 +962,7 @@
/**
* show file destination field as "busy" while checking
*
- * @param busy boolean true = show busy-ness, false = remove
+ * @param {boolean} busy True = show busy-ness, false = remove
*/
toggleDestinationBusy: function ( busy ) {
if ( busy ) {
@@ -980,7 +979,7 @@
* XXX would be simpler if we created all these divs in the DOM
and had a more jquery-friendly way of selecting
* attrs. Instead we create & destroy whole interface each
time. Won't someone think of the DOM elements?
*
- * @param result
+ * @param {Object} result Result to process
*/
processDestinationCheck: function ( result ) {
var titleString, errHtml, completeErrorLink,
@@ -1104,9 +1103,9 @@
/**
* Remove a description
*
- * @param description
+ * @param {jQuery} description Description HTML from which to
remove the `div`
*/
- removeDescription: function ( description ) {
+ removeDescription: function ( description ) {
$( description.div ).remove();
this.descriptions = $.grep(
@@ -1144,7 +1143,7 @@
/**
* Given the API result pull some info into the form ( for
instance, extracted from EXIF, desired filename )
*
- * @param result Upload API result object
+ * @param {Object} result Upload API result object
*/
populate: function () {
this.upload.setThumbnail(
diff --git a/resources/mw.UploadWizardLicenseInput.js
b/resources/mw.UploadWizardLicenseInput.js
index cbcdf7f..d9242d2 100644
--- a/resources/mw.UploadWizardLicenseInput.js
+++ b/resources/mw.UploadWizardLicenseInput.js
@@ -126,8 +126,8 @@
/**
* Creates the license input interface in toggleable groups.
*
- * @param jQuery selector
- * @param license input configuration groups
+ * @param {jQuery} $el Selector
+ * @param {Object} configGroups License input configuration
groups
*/
createGroupedInputs: function ( $el, configGroups ) {
var input = this;
@@ -374,7 +374,7 @@
/**
* Sets the value(s) of a license input. This is a little bit
klugey because it relies on an inverted dict, and in some
* cases we are now letting license inputs create multiple
templates.
- * @param object of license-key to boolean values, e.g. {
'cc_by_sa_30': true, gfdl: true, 'flickrreview|cc_by_sa_30': false }
+ * @param {object} values License-key to boolean values, e.g. {
'cc_by_sa_30': true, gfdl: true, 'flickrreview|cc_by_sa_30': false }
*/
setValues: function ( values ) {
var trueCount, trueLicenseName,
diff --git a/resources/mw.UploadWizardUpload.js
b/resources/mw.UploadWizardUpload.js
index b9b8059..4dfbe30 100644
--- a/resources/mw.UploadWizardUpload.js
+++ b/resources/mw.UploadWizardUpload.js
@@ -135,7 +135,7 @@
/**
* Wear our current progress, for observing processes to see
- * @param fraction
+ * @param {number} fraction
*/
mw.UploadWizardUpload.prototype.setTransportProgress = function (
fraction ) {
if ( this.state === 'aborted' ) {
@@ -171,7 +171,7 @@
/**
* To be executed when an individual upload finishes. Processes the
result and updates step 2's details
- * @param result the API result in parsed JSON form
+ * @param {Object} result The API result in parsed JSON form
*/
mw.UploadWizardUpload.prototype.setTransported = function ( result ) {
// default error state
@@ -569,8 +569,8 @@
/**
* Shows an error dialog informing the user that the selected file is
to large
- * @param size integer - the size of the file in bytes
- * @param maxSize integer - the maximum file size
+ * @param {number} size Size of the file in bytes
+ * @param {number} maxSize Maximum file size
*/
mw.UploadWizardUpload.prototype.showMaxSizeWarning = function ( size,
maxSize ) {
var ed = new mw.ErrorDialog(
@@ -626,7 +626,7 @@
/**
* Accept the result from a successful API upload transport, and fill
our own info
*
- * @param result The JSON object from a successful API upload result.
+ * @param {Object} result The JSON object from a successful API upload
result.
*/
mw.UploadWizardUpload.prototype.extractUploadInfo = function (
resultUpload ) {
if ( resultUpload.filekey ) {
@@ -645,7 +645,7 @@
* Extract image info into our upload object
* Image info is obtained from various different API methods
* This may overwrite metadata obtained from FileReader.
- * @param imageinfo JSON object obtained from API result.
+ * @param {Object} imageinfo JSON object obtained from API result.
*/
mw.UploadWizardUpload.prototype.extractImageInfo = function ( imageinfo
) {
var key,
@@ -1062,9 +1062,9 @@
* Given a jQuery selector, subscribe to the "ready" event that fills
the thumbnail
* This will trigger if the thumbnail is added in the future or if it
already has been
*
- * @param selector
- * @param width Width constraint
- * @param height Height constraint (optional)
+ * @param {string} selector String representing a jQuery selector
+ * @param {number} width Width constraint
+ * @param {number} [height] Height constraint
*/
mw.UploadWizardUpload.prototype.setThumbnail = function ( selector,
width, height ) {
var upload = this,
diff --git a/resources/mw.UploadWizardUploadInterface.js
b/resources/mw.UploadWizardUploadInterface.js
index a023853..42c000c 100644
--- a/resources/mw.UploadWizardUploadInterface.js
+++ b/resources/mw.UploadWizardUploadInterface.js
@@ -5,8 +5,8 @@
* @class mw.UploadWizardUploadInterface
* @mixins OO.EventEmitter
* @constructor
- * @param upload
- * @param div to insert file interface
+ * @param {object} upload …
+ * @param {jQuery} filesDiv DIV into which to insert file interface
*/
mw.UploadWizardUploadInterface = function
MWUploadWizardUploadInterface( upload, filesDiv ) {
var $preview,
@@ -142,7 +142,7 @@
/**
* change the graphic indicator at the far end of the row for this file
- * @param String statusClass: corresponds to a class mwe-upwiz-status
which changes style of indicator.
+ * @param {string} statusClass Corresponds to a class mwe-upwiz-status
which changes style of indicator.
*/
mw.UploadWizardUploadInterface.prototype.showIndicator = function (
statusClass ) {
this.clearIndicator();
@@ -164,7 +164,7 @@
/**
* Set the preview image on the file page for this upload.
- * @param HTMLImageElement
+ * @param {HTMLImageElement} image
*/
mw.UploadWizardUploadInterface.prototype.setPreview = function ( image
) {
var $preview = $( this.div ).find( '.mwe-upwiz-file-preview' );
@@ -178,8 +178,8 @@
/**
* Set the status line for this upload with an internationalized
message string.
- * @param String msgKey: key for the message
- * @param Array args: array of values, in case any need to be fed to
the image.
+ * @param {string} msgKey Key for the message
+ * @param {array} args Array of values, in case any need to be fed to
the image.
*/
mw.UploadWizardUploadInterface.prototype.setStatus = function ( msgKey,
args ) {
var $s;
@@ -223,7 +223,7 @@
/**
* Put the visual state of an individual upload into "progress"
- * @param fraction The fraction of progress. Float between 0 and 1
+ * @param {number} fraction The fraction of progress. Float between 0
and 1
*/
mw.UploadWizardUploadInterface.prototype.showTransportProgress =
function () {
// if fraction available, update individual progress bar /
estimates, etc.
@@ -249,8 +249,8 @@
/**
* Show that transport has failed
- * @param String code: error code from API
- * @param {string|Object} info: extra info
+ * @param {string} code Error code from API
+ * @param {string|Object} info Extra info
* @param {jQuery} [$additionalStatus]
*/
mw.UploadWizardUploadInterface.prototype.showError = function ( code,
info, $additionalStatus ) {
@@ -473,8 +473,8 @@
* or otherwise get it to do what you want.
* It is helpful to sometimes move them to cover certain elements on
the page, and
* even to pass events like hover
- * @param selector jquery-compatible selector, for a single element
- * @param positionTracking string, optional, whether to do
position-polling ('poll')
+ * @param {string} selector A jQuery-compatible selector, for a single
element
+ * @param {string} [positionTracking] Whether to do position-polling
('poll')
* on the selected element or whether to listen to window-resize
events ('resize')
*/
mw.UploadWizardUploadInterface.prototype.moveFileInputToCover =
function ( selector, positionTracking ) {
@@ -619,9 +619,9 @@
/**
* Create a checkbox to process the object reference parameter
- * @param index number of the file for which the field is being created
- * @param setDisabled disable in case there already is an image in the
referring list
- * @return {jQuery} div containing a checkbox, label, and optional notice
+ * @param {number} index Number of the file for which the field is being
created
+ * @param {boolean} setDisabled Disable in case there already is an
image in the referring list
+ * @return {jQuery} A `div` containing a checkbox, label, and optional
notice
*/
mw.UploadWizardUploadInterface.prototype.createImagePickerField =
function ( index, setDisabled ) {
var $fieldContainer = $( '<div>' ).attr( {
diff --git a/resources/ui/uw.ui.Thanks.js b/resources/ui/uw.ui.Thanks.js
index e6b6682..58e2c21 100644
--- a/resources/ui/uw.ui.Thanks.js
+++ b/resources/ui/uw.ui.Thanks.js
@@ -191,8 +191,8 @@
/**
* Drops a parameter from the given url
- * @param url
- * @param paramName parameter to be dropped
+ * @param {string} url URL from which to drop a parameter
+ * @param {string} paramName parameter to be dropped
* @return {string}
* @private
*/
diff --git a/resources/ui/uw.ui.Upload.js b/resources/ui/uw.ui.Upload.js
index 7d797ad..2b63c6c 100644
--- a/resources/ui/uw.ui.Upload.js
+++ b/resources/ui/uw.ui.Upload.js
@@ -281,7 +281,7 @@
/**
* Shows an error dialog informing the user that some uploads have been
omitted
* since they went over the max files limit.
- * @param filesUploaded integer - the number of files that have been
attempted to upload
+ * @param {number} filesUploaded The number of files that have been
attempted to upload
*/
uw.ui.Upload.prototype.showTooManyFilesWarning = function (
filesUploaded ) {
var dialog = new mw.ErrorDialog(
diff --git a/resources/uw.EventFlowLogger.js b/resources/uw.EventFlowLogger.js
index a5bb241..3982304 100644
--- a/resources/uw.EventFlowLogger.js
+++ b/resources/uw.EventFlowLogger.js
@@ -21,7 +21,7 @@
* Event logging helper for funnel analysis. Should be instantiated at
the very beginning; uses internal state
* to link events together.
* @constructor
- * @param eventLog mw.eventLog object, for dependency injection
+ * @param {Object} eventLog mw.eventLog object, for dependency injection
*/
uw.EventFlowLogger = function UWEventFlowLogger( eventLog ) {
this.eventLog = eventLog;
--
To view, visit https://gerrit.wikimedia.org/r/247737
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: I79bb4053b0bd29c4214b2665b40e03cc6eac0de1
Gerrit-PatchSet: 2
Gerrit-Project: mediawiki/extensions/UploadWizard
Gerrit-Branch: master
Gerrit-Owner: Jforrester <[email protected]>
Gerrit-Reviewer: Bartosz Dziewoński <[email protected]>
Gerrit-Reviewer: jenkins-bot <>
_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
