From b6cdd33376225a74a897c406c21cb981c5cbaadc Mon Sep 17 00:00:00 2001
From: "James D. Forrester" <jforrester@wikimedia.org>
Date: Sat, 5 Sep 2015 11:55:03 -0700
Subject: [PATCH] build: Enable jscs jsDoc rule 'requireParamTypes' and make
 pass

Change-Id: Id0e10dba3548a981ba6d301bd3cd04adbe143e64
---
 .jscsrc                                       |  1 +
 .../src/jquery/jquery.expandableField.js      |  4 ++--
 .../jquery/jquery.qunit.completenessTest.js   | 20 +++++++++----------
 resources/src/jquery/jquery.tablesorter.js    | 10 +++++-----
 resources/src/jquery/jquery.textSelection.js  |  2 +-
 .../mediawiki.action.history.js               |  2 +-
 .../mediawiki.special.preferences.js          |  4 ++--
 .../src/mediawiki/mediawiki.jqueryMsg.js      |  2 +-
 resources/src/mediawiki/mediawiki.util.js     |  4 ++--
 tests/qunit/data/testrunner.js                |  4 ++--
 .../jquery/jquery.textSelection.test.js       | 14 ++++++-------
 11 files changed, 34 insertions(+), 33 deletions(-)

diff --git a/.jscsrc b/.jscsrc
index 13f7f603b3..9ab6f3cc71 100644
--- a/.jscsrc
+++ b/.jscsrc
@@ -7,6 +7,7 @@
 	"disallowQuotedKeysInObjects": "allButReserved",
 	"requireDotNotation": { "allExcept": [ "keywords" ] },
 	"jsDoc": {
+		"requireParamTypes": true,
 		"requireReturnTypes": true
 	},
 
diff --git a/resources/src/jquery/jquery.expandableField.js b/resources/src/jquery/jquery.expandableField.js
index b9bb77a8df..10c11ea834 100644
--- a/resources/src/jquery/jquery.expandableField.js
+++ b/resources/src/jquery/jquery.expandableField.js
@@ -39,8 +39,8 @@
 		},
 		/**
 		 * Sets the value of a property, and updates the widget accordingly
-		 * @param property String Name of property
-		 * @param value Mixed Value to set property with
+		 * @param {String} property Name of property
+		 * @param {Mixed} value Value to set property with
 		 */
 		configure: function ( context, property, value ) {
 			// TODO: Validate creation using fallback values
diff --git a/resources/src/jquery/jquery.qunit.completenessTest.js b/resources/src/jquery/jquery.qunit.completenessTest.js
index e34592cb14..d890d95630 100644
--- a/resources/src/jquery/jquery.qunit.completenessTest.js
+++ b/resources/src/jquery/jquery.qunit.completenessTest.js
@@ -55,10 +55,10 @@
 	 *
 	 * @example
 	 *  var myTester = new CompletenessTest( myLib );
-	 * @param masterVariable {Object} The root variable that contains all object
+	 * @param {Object} masterVariable The root variable that contains all object
 	 *  members. CompletenessTest will recursively traverse objects and keep track
 	 *  of all methods.
-	 * @param ignoreFn {Function} Optionally pass a function to filter out certain
+	 * @param {Function} [ignoreFn] Optionally pass a function to filter out certain
 	 *  methods. Example: You may want to filter out instances of jQuery or some
 	 *  other constructor. Otherwise "missingTests" will include all methods that
 	 *  were not called from that instance.
@@ -186,12 +186,12 @@
 		 * Depending on the action it either injects our listener into the methods, or
 		 * reads from our tracker and records which methods have not been called by the test suite.
 		 *
-		 * @param currName {String|Null} Name of the given object member (Initially this is null).
-		 * @param currVar {mixed} The variable to check (initially an object,
+		 * @param {String|Null} currName Name of the given object member (Initially this is null).
+		 * @param {mixed} currVar The variable to check (initially an object,
 		 *  further down it could be anything).
-		 * @param masterVariable {Object} Throughout our interation, always keep track of the master/root.
+		 * @param {Object} masterVariable Throughout our interation, always keep track of the master/root.
 		 *  Initially this is the same as currVar.
-		 * @param parentPathArray {Array} Array of names that indicate our breadcrumb path starting at
+		 * @param {Array} parentPathArray Array of names that indicate our breadcrumb path starting at
 		 *  masterVariable. Not including currName.
 		 */
 		walkTheObject: function ( currObj, currName, masterVariable, parentPathArray ) {
@@ -258,7 +258,7 @@
 		 * was called during the test suite (as far as the tracker knows).
 		 * If not it adds it to missingTests.
 		 *
-		 * @param fnName {String}
+		 * @param {String} fnName
 		 * @return {Boolean}
 		 */
 		hasTest: function ( fnName ) {
@@ -275,9 +275,9 @@
 		 * Injects a function (such as a spy that updates methodCallTracker when
 		 * it's called) inside another function.
 		 *
-		 * @param masterVariable {Object}
-		 * @param objectPathArray {Array}
-		 * @param injectFn {Function}
+		 * @param {Object} masterVariable
+		 * @param {Array} objectPathArray
+		 * @param {Function} injectFn
 		 */
 		injectCheck: function ( obj, key, injectFn ) {
 			var spy,
diff --git a/resources/src/jquery/jquery.tablesorter.js b/resources/src/jquery/jquery.tablesorter.js
index 40c828a42f..81a20d07bf 100644
--- a/resources/src/jquery/jquery.tablesorter.js
+++ b/resources/src/jquery/jquery.tablesorter.js
@@ -248,7 +248,7 @@
 	 *
 	 * After this, it will look at all rows at the bottom for footer rows
 	 * And place these in a tfoot using similar rules.
-	 * @param $table jQuery object for a <table>
+	 * @param {jQuery} $table jQuery object for a <table>
 	 */
 	function emulateTHeadAndFoot( $table ) {
 		var $thead, $tfoot, i, len,
@@ -545,7 +545,7 @@
 	 * Replace all rowspanned cells in the body with clones in each row, so sorting
 	 * need not worry about them.
 	 *
-	 * @param $table jQuery object for a <table>
+	 * @param {jQuery} $table jQuery object for a <table>
 	 */
 	function explodeRowspans( $table ) {
 		var spanningRealCellIndex, rowSpan, colSpan,
@@ -726,8 +726,8 @@
 			monthNames: {},
 
 			/**
-			 * @param $tables {jQuery}
-			 * @param settings {Object} (optional)
+			 * @param {jQuery} $tables
+			 * @param {Object} [settings]
 			 */
 			construct: function ( $tables, settings ) {
 				return $tables.each( function ( i, table ) {
@@ -907,7 +907,7 @@
 					 * Passing an empty array will reset sorting (basically just reset the headers
 					 * making the table appear unsorted).
 					 *
-					 * @param sortList {Array} (optional) List of sort objects.
+					 * @param {Array} [sortList] List of sort objects.
 					 */
 					$table.data( 'tablesorter' ).sort = function ( sortList ) {
 
diff --git a/resources/src/jquery/jquery.textSelection.js b/resources/src/jquery/jquery.textSelection.js
index 2573813dcf..95c0346c12 100644
--- a/resources/src/jquery/jquery.textSelection.js
+++ b/resources/src/jquery/jquery.textSelection.js
@@ -411,7 +411,7 @@
 			 *
 			 * Scroll a textarea to the current cursor position. You can set the cursor
 			 * position with setSelection()
-			 * @param options boolean Whether to force a scroll even if the caret position
+			 * @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)
diff --git a/resources/src/mediawiki.action/mediawiki.action.history.js b/resources/src/mediawiki.action/mediawiki.action.history.js
index 2ebfe921aa..077d5e3a09 100644
--- a/resources/src/mediawiki.action/mediawiki.action.history.js
+++ b/resources/src/mediawiki.action/mediawiki.action.history.js
@@ -9,7 +9,7 @@ jQuery( function ( $ ) {
 	/**
 	 * @ignore
 	 * @context {Element} input
-	 * @param e {jQuery.Event}
+	 * @param {jQuery.Event} e
 	 */
 	function updateDiffRadios() {
 		var nextState = 'before',
diff --git a/resources/src/mediawiki.special/mediawiki.special.preferences.js b/resources/src/mediawiki.special/mediawiki.special.preferences.js
index 57489faa6b..bad1c0837d 100644
--- a/resources/src/mediawiki.special/mediawiki.special.preferences.js
+++ b/resources/src/mediawiki.special/mediawiki.special.preferences.js
@@ -51,8 +51,8 @@ jQuery( function ( $ ) {
 	 * It uses document.getElementById for security reasons (HTML injections in $()).
 	 *
 	 * @ignore
-	 * @param String name: the name of a tab without the prefix ("mw-prefsection-")
-	 * @param String mode: [optional] A hash will be set according to the current
+	 * @param {String} name the name of a tab without the prefix ("mw-prefsection-")
+	 * @param {String} [mode] A hash will be set according to the current
 	 *  open section. Set mode 'noHash' to surpress this.
 	 */
 	function switchPrefTab( name, mode ) {
diff --git a/resources/src/mediawiki/mediawiki.jqueryMsg.js b/resources/src/mediawiki/mediawiki.jqueryMsg.js
index 0502304319..f778b7f473 100644
--- a/resources/src/mediawiki/mediawiki.jqueryMsg.js
+++ b/resources/src/mediawiki/mediawiki.jqueryMsg.js
@@ -1024,7 +1024,7 @@
 		 * from the server, since the replacement is done at save time.
 		 * It may, though, if the wikitext appears in extension-controlled content.
 		 *
-		 * @param nodes
+		 * @param {String[]} nodes
 		 */
 		wikilink: function ( nodes ) {
 			var page, anchor, url;
diff --git a/resources/src/mediawiki/mediawiki.util.js b/resources/src/mediawiki/mediawiki.util.js
index 2b4fa755f4..e6c98beda2 100644
--- a/resources/src/mediawiki/mediawiki.util.js
+++ b/resources/src/mediawiki/mediawiki.util.js
@@ -113,8 +113,8 @@
 		 * For index.php use `mw.config.get( 'wgScript' )`.
 		 *
 		 * @since 1.18
-		 * @param str string Name of script (eg. 'api'), defaults to 'index'
-		 * @return {string} Address to script (eg. '/w/api.php' )
+		 * @param {string} str Name of script (e.g. 'api'), defaults to 'index'
+		 * @return {string} Address to script (e.g. '/w/api.php' )
 		 */
 		wikiScript: function ( str ) {
 			str = str || 'index';
diff --git a/tests/qunit/data/testrunner.js b/tests/qunit/data/testrunner.js
index fb4667a714..b57b6cfd9f 100644
--- a/tests/qunit/data/testrunner.js
+++ b/tests/qunit/data/testrunner.js
@@ -8,7 +8,7 @@
 	/**
 	 * Add bogus to url to prevent IE crazy caching
 	 *
-	 * @param value {String} a relative path (eg. 'data/foo.js'
+	 * @param {String} value a relative path (eg. 'data/foo.js'
 	 * or 'data/test.php?foo=bar').
 	 * @return {String} Such as 'data/foo.js?131031765087663960'
 	 */
@@ -164,7 +164,7 @@
 	/**
 	 * Reset mw.config and others to a fresh copy of the live config for each test(),
 	 * and restore it back to the live one afterwards.
-	 * @param localEnv {Object} [optional]
+	 * @param {Object} [localEnv]
 	 * @example (see test suite at the bottom of this file)
 	 * </code>
 	 */
diff --git a/tests/qunit/suites/resources/jquery/jquery.textSelection.test.js b/tests/qunit/suites/resources/jquery/jquery.textSelection.test.js
index ad229acff8..2e6f05edea 100644
--- a/tests/qunit/suites/resources/jquery/jquery.textSelection.test.js
+++ b/tests/qunit/suites/resources/jquery/jquery.textSelection.test.js
@@ -5,13 +5,13 @@
 	/**
 	 * Test factory for $.fn.textSelection( 'encapsulateText' )
 	 *
-	 * @param options {object} associative array containing:
-	 *   description {string}
-	 *   input {string}
-	 *   output {string}
-	 *   start {int} starting char for selection
-	 *   end {int} ending char for selection
-	 *   params {object} add'l parameters for $().textSelection( 'encapsulateText' )
+	 * @param {Object} options Associative configuration array
+	 * @param {string} options.description Description
+	 * @param {string} options.input Input
+	 * @param {string} options.output Output
+	 * @param {int} options.start Starting char for selection
+	 * @param {int} options.end Ending char for selection
+	 * @param {object} options.params Additional parameters for $().textSelection( 'encapsulateText' )
 	 */
 	function encapsulateTest( options ) {
 		var opt = $.extend( {
-- 
2.20.1