eslint: Re-enable valid-jsdoc and make a pass

Change-Id: I5c3c942d5a9c51628619227c4bbaefd1d92a842d

.eslintrc.json

@@ -13,7 +13,6 @@
 		"OO": false
 	},
 	"rules": {
-		"dot-notation": 0,
-		"valid-jsdoc": 0
+		"dot-notation": 0
 	}
 }

resources/src/jquery/jquery.accessKeyLabel.js

@@ -204,6 +204,8 @@
 	 *
 	 * @method updateTooltipAccessKeys_getAccessKeyPrefix
 	 * @deprecated since 1.27 Use #getAccessKeyModifiers
+	 * @param {Object} [ua] An object with a 'userAgent' and 'platform' property.
+	 * @return {string}
 	 */
 	$.fn.updateTooltipAccessKeys.getAccessKeyPrefix = function ( ua ) {
 		return getAccessKeyModifiers( ua ).join( '-' ) + '-';

resources/src/jquery/jquery.confirmable.js

@@ -12,6 +12,7 @@
 		return data;
 	};
 
+	// eslint-disable-next-line valid-jsdoc
 	/**
 	 * Enable inline confirmation for given clickable element (like `<a />` or `<button />`).
 	 *

resources/src/jquery/jquery.expandableField.js

@@ -19,6 +19,9 @@
 	$.expandableField = {
 		/**
 		 * Expand the field, make the callback
+		 *
+		 * @param {jQuery.Event} e Event
+		 * @param {Object} context
 		 */
 		expandField: function ( e, context ) {
 			context.config.beforeExpand.call( context.data.$field, context );
@@ -29,6 +32,9 @@
 		},
 		/**
 		 * Condense the field, make the callback
+		 *
+		 * @param {jQuery.Event} e Event
+		 * @param {Object} context
 		 */
 		condenseField: function ( e, context ) {
 			context.config.beforeCondense.call( context.data.$field, context );

resources/src/jquery/jquery.hidpi.js

@@ -65,6 +65,7 @@
 	 *
 	 * @static
 	 * @inheritable
+	 * @param {number} baseRatio Base ratio
 	 * @return {number} Device pixel ratio
 	 */
 	$.bracketDevicePixelRatio = function ( baseRatio ) {

resources/src/jquery/jquery.qunit.completenessTest.js

@@ -211,14 +211,14 @@
 
 			// Hard ignores
 			if ( this.ignoreFn( currVal, this, currPathArray ) ) {
-				return null;
+				return;
 			}
 
 			// Handle the lazy limit
 			this.lazyCounter++;
 			if ( this.lazyCounter > this.lazyLimit ) {
 				log( 'CompletenessTest.fn.walkTheObject> Limit reached: ' + this.lazyCounter, currPathArray );
-				return null;
+				return;
 			}
 
 			// Functions

resources/src/jquery/jquery.tablesorter.js

@@ -407,8 +407,8 @@
 	 * in default (ascending) order when their header cell is clicked the next time.
 	 *
 	 * @param {jQuery} $headers
-	 * @param {number[][]} sortList
-	 * @param {number[][]} headerToColumns
+	 * @param {Array} sortList 2D number array
+	 * @param {Array} headerToColumns 2D number array
 	 */
 	function setHeadersOrder( $headers, sortList, headerToColumns ) {
 		// Loop through all headers to retrieve the indices of the columns the header spans across:
@@ -776,6 +776,7 @@
 		/**
 		 * @param {jQuery} $tables
 		 * @param {Object} [settings]
+		 * @return {jQuery}
 		 */
 		construct: function ( $tables, settings ) {
 			return $tables.each( function ( i, table ) {

resources/src/jquery/jquery.textSelection.js

@@ -32,14 +32,17 @@
 
 		/**
 		 * Helper function to get an IE TextRange object for an element
+		 *
+		 * @param {HTMLElement} element
+		 * @return {TextRange}
 		 */
-		function rangeForElementIE( e ) {
+		function rangeForElementIE( element ) {
 			var sel;
-			if ( e.nodeName.toLowerCase() === 'input' ) {
-				return e.createTextRange();
+			if ( element.nodeName.toLowerCase() === 'input' ) {
+				return element.createTextRange();
 			} else {
 				sel = document.body.createTextRange();
-				sel.moveToElementText( e );
+				sel.moveToElementText( element );
 				return sel;
 			}
 		}
@@ -48,6 +51,8 @@
 		 * Helper function for IE for activating the textarea. Called only in the
 		 * IE-specific code paths below; makes use of IE-specific non-standard
 		 * function setActive() if possible to avoid screen flicker.
+		 *
+		 * @param {HTMLElement} element
 		 */
 		function activateElementOnIE( element ) {
 			if ( element.setActive ) {
@@ -60,12 +65,16 @@
 		fn = {
 			/**
 			 * Get the contents of the textarea
+			 *
+			 * @return {string}
 			 */
 			getContents: function () {
 				return this.val();
 			},
 			/**
 			 * Set the contents of the textarea, replacing anything that was there before
+			 *
+			 * @param {string} content
 			 */
 			setContents: function ( content ) {
 				this.val( content );
@@ -73,6 +82,8 @@
 			/**
 			 * Get the currently selected text in this textarea. Will focus the textarea
 			 * in some browsers (IE/Opera)
+			 *
+			 * @return {string}
 			 */
 			getSelection: function () {
 				var retval, range,
@@ -97,7 +108,9 @@
 			 * Inserts text at the beginning and end of a text selection, optionally
 			 * inserting text at the caret when selection is empty.
 			 *
+			 * @param {Object} options Options
 			 * FIXME document the options parameters
+			 * @return {jQuery}
 			 */
 			encapsulateSelection: function ( options ) {
 				return this.each( function () {
@@ -133,6 +146,11 @@
 					 * Do the splitlines stuff.
 					 *
 					 * Wrap each line of the selected text with pre and post
+					 *
+					 * @param {string} selText Selected text
+					 * @param {string} pre Text before
+					 * @param {string} post Text after
+					 * @return {string} Wrapped text
 					 */
 					function doSplitLines( selText, pre, post ) {
 						var i,
@@ -269,7 +287,9 @@
 			 *
 			 * Will focus the textarea in some browsers (IE/Opera)
 			 *
+			 * @param {Object} options Options
 			 * FIXME document the options parameters
+			 * @return {number} Position
 			 */
 			getCaretPosition: function ( options ) {
 				function getCaret( e ) {
@@ -366,7 +386,9 @@
 				return getCaret( this.get( 0 ) );
 			},
 			/**
+			 * @param {Object} options options
 			 * FIXME document the options parameters
+			 * @return {jQuery}
 			 */
 			setSelection: function ( options ) {
 				return this.each( function () {
@@ -411,10 +433,11 @@
 			 * Scroll a textarea to the current cursor position. You can set the cursor
 			 * position with setSelection()
 			 *
-			 * @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)
+			 * @param {Object} options options
+			 * @cfg {boolean} [force=false] Whether to force a scroll even if the caret position
+			 *  is already visible.
+			 * FIXME document the options parameters
+			 * @return {jQuery}
 			 */
 			scrollToCaretPosition: function ( options ) {
 				function getLineLength( e ) {

resources/src/mediawiki.action/mediawiki.action.history.js

@@ -10,6 +10,7 @@ jQuery( function ( $ ) {
 	 * @ignore
 	 * @context {Element} input
 	 * @param {jQuery.Event} e
+	 * @return {boolean} False to cancel the default event
 	 */
 	function updateDiffRadios() {
 		var nextState = 'before',

resources/src/mediawiki.legacy/protect.js

@@ -4,6 +4,8 @@
 		/**
 		 * Set up the protection chaining interface (i.e. "unlock move permissions" checkbox)
 		 * on the protection form
+		 *
+		 * @return {boolean}
 		 */
 		init: function () {
 			var $cell = $( '<td>' ),
@@ -47,6 +49,7 @@
 			$( '#mwProtect-reason' ).byteLimit( 180 );
 
 			this.updateCascadeCheckbox();
+			return true;
 		},
 
 		/**

resources/src/mediawiki.legacy/wikibits.js

@@ -166,6 +166,8 @@
 
 	/**
 	 * @deprecated since 1.17 Use mw.loader instead. Warnings added in 1.25.
+	 * @param {string} url
+	 * @return {HTMLElement} Script tag
 	 */
 	function importScriptURI( url ) {
 		var s;
@@ -188,6 +190,9 @@
 
 	/**
 	 * @deprecated since 1.17 Use mw.loader instead. Warnings added in 1.25.
+	 * @param {string} url
+	 * @param {string} media
+	 * @return {HTMLElement} Link tag
 	 */
 	function importStylesheetURI( url, media ) {
 		var l = document.createElement( 'link' );

resources/src/mediawiki.special/mediawiki.special.apisandbox.js

@@ -715,6 +715,8 @@
 
 		/**
 		 * Update the current query when the page hash changes
+		 *
+		 * @return {boolean} Successful
 		 */
 		loadFromHash: function () {
 			var params, m, re,

resources/src/mediawiki.special/mediawiki.special.upload.js

@@ -269,6 +269,8 @@
 	$( function () {
 		/**
 		 * Is the FileAPI available with sufficient functionality?
+		 *
+		 * @return {boolean}
 		 */
 		function hasFileAPI() {
 			return window.FileReader !== undefined;
@@ -501,6 +503,9 @@
 
 		/**
 		 * Check if the file does not exceed the maximum size
+		 *
+		 * @param {File} file
+		 * @return {boolean}
 		 */
 		function checkMaxUploadSize( file ) {
 			var maxSize, $error;

resources/src/mediawiki.toolbar/toolbar.js

@@ -28,6 +28,11 @@
 	 *  current cursor position.
 	 * @param {string} [button.imageId] `id` attribute of the button HTML element. Can be
 	 *  used to define the image with CSS if it's not provided as `imageFile`.
+	 * @param {string} [speedTip]
+	 * @param {string} [tagOpen]
+	 * @param {string} [tagClose]
+	 * @param {string} [sampleText]
+	 * @param {string} [imageId]
 	 */
 	function insertButton( button, speedTip, tagOpen, tagClose, sampleText, imageId ) {
 		var $button;

resources/src/mediawiki.widgets.datetime/CalendarWidget.js

@@ -202,6 +202,7 @@
 		return this.selected;
 	};
 
+	// eslint-disable-next-line valid-jsdoc
 	/**
 	 * Set the selected dates
 	 *
@@ -250,6 +251,7 @@
 		return this.focusedDate;
 	};
 
+	// eslint-disable-next-line valid-jsdoc
 	/**
 	 * Set the currently-focused date
 	 *
@@ -498,6 +500,7 @@
 	 *
 	 * @protected
 	 * @param {jQuery.Event} e Key down event
+	 * @return {boolean} False to cancel the default event
 	 */
 	mw.widgets.datetime.CalendarWidget.prototype.onKeyDown = function ( e ) {
 		var focusedDate = this.getFocusedDate();

resources/src/mediawiki.widgets.datetime/DateTimeFormatter.js

@@ -125,6 +125,7 @@
 		return this.local;
 	};
 
+	// eslint-disable-next-line valid-jsdoc
 	/**
 	 * Toggle whether dates are in local time or UTC
 	 *

resources/src/mediawiki.widgets.datetime/DateTimeInputWidget.js

@@ -583,6 +583,7 @@
 	 * @private
 	 * @param {jQuery} $field
 	 * @param {jQuery.Event} e Key down event
+	 * @return {boolean} False to cancel the default event
 	 */
 	mw.widgets.datetime.DateTimeInputWidget.prototype.onFieldKeyDown = function ( $field, e ) {
 		var spec = $field.data( 'mw-widgets-datetime-dateTimeInputWidget-fieldSpec' );
@@ -704,6 +705,7 @@
 	 * @private
 	 * @param {jQuery} $field
 	 * @param {jQuery.Event} e Change event
+	 * @return {boolean} False to cancel the default event
 	 */
 	mw.widgets.datetime.DateTimeInputWidget.prototype.onFieldWheel = function ( $field, e ) {
 		var delta = 0,

resources/src/mediawiki.widgets/mw.widgets.CalendarWidget.js

@@ -408,6 +408,7 @@
 	 * what gets clicked.
 	 *
 	 * @private
+	 * @param {jQuery.Event} e Click event
 	 */
 	mw.widgets.CalendarWidget.prototype.onBodyClick = function ( e ) {
 		var
@@ -504,6 +505,7 @@
 	 *
 	 * @private
 	 * @param {jQuery.Event} e Mouse click event
+	 * @return {boolean} False to cancel the default event
 	 */
 	mw.widgets.CalendarWidget.prototype.onClick = function ( e ) {
 		if ( !this.isDisabled() && e.which === 1 ) {
@@ -517,6 +519,7 @@
 	 *
 	 * @private
 	 * @param {jQuery.Event} e Key down event
+	 * @return {boolean} False to cancel the default event
 	 */
 	mw.widgets.CalendarWidget.prototype.onKeyDown = function ( e ) {
 		var

resources/src/mediawiki.widgets/mw.widgets.CategoryCapsuleItemWidget.js

@@ -94,7 +94,8 @@
 	 * @extends mw.Title
 	 *
 	 * @constructor
-	 * @inheritdoc
+	 * @param {string} title
+	 * @param {number} [namespace]
 	 */
 	function ForeignTitle( title, namespace ) {
 		// We only need to handle categories here... but we don't know the target language.
@@ -109,11 +110,10 @@
 	};
 
 	/**
-	 * @class mw.widgets.CategoryCapsuleItemWidget
-	 *
 	 * Category selector capsule item widget. Extends OO.ui.CapsuleItemWidget with the ability to link
 	 * to the given page, and to show its existence status (i.e., whether it is a redlink).
 	 *
+	 * @class mw.widgets.CategoryCapsuleItemWidget
 	 * @uses mw.Api
 	 * @extends OO.ui.CapsuleItemWidget
 	 *

resources/src/mediawiki.widgets/mw.widgets.DateInputWidget.js

@@ -488,6 +488,7 @@
 	 *
 	 * @private
 	 * @param {jQuery.Event} e Mouse click event
+	 * @return {boolean} False to cancel the default event
 	 */
 	mw.widgets.DateInputWidget.prototype.onClick = function ( e ) {
 		if ( !this.isDisabled() && e.which === 1 ) {
@@ -501,6 +502,7 @@
 	 *
 	 * @private
 	 * @param {jQuery.Event} e Key press event
+	 * @return {boolean} False to cancel the default event
 	 */
 	mw.widgets.DateInputWidget.prototype.onKeyPress = function ( e ) {
 		if ( !this.isDisabled() &&
@@ -516,6 +518,7 @@
 	 *
 	 * @private
 	 * @param {jQuery.Event} e Key press event
+	 * @return {boolean} False to cancel the default event
 	 */
 	mw.widgets.DateInputWidget.prototype.onCalendarKeyPress = function ( e ) {
 		if ( !this.isDisabled() && e.which === OO.ui.Keys.ENTER ) {
@@ -530,6 +533,7 @@
 	 *
 	 * @private
 	 * @param {jQuery.Event} e Mouse click event
+	 * @return {boolean} False to cancel the default event
 	 */
 	mw.widgets.DateInputWidget.prototype.onCalendarClick = function ( e ) {
 		if (

resources/src/mediawiki.widgets/mw.widgets.NamespaceInputWidget.js

@@ -36,6 +36,8 @@
 
 	/**
 	 * @private
+	 * @param {Object} [config] Configuration options
+	 * @return {Object[]} Dropdown options
 	 */
 	mw.widgets.NamespaceInputWidget.prototype.getNamespaceDropdownOptions = function ( config ) {
 		var options,

resources/src/mediawiki.widgets/mw.widgets.SearchInputWidget.js

@@ -13,6 +13,7 @@
 	 * @extends mw.widgets.TitleInputWidget
 	 *
 	 * @constructor
+	 * @param {Object} [config] Configuration options
 	 * @cfg {boolean} [pushPending=true] Visually mark the input field as "pending", while
 	 *  requesting suggestions.
 	 * @cfg {boolean} [performSearchOnClick=true] If true, the script will start a search when-

resources/src/mediawiki.widgets/mw.widgets.TitleInputWidget.js

@@ -15,6 +15,7 @@
 	 * @mixins OO.ui.mixin.LookupElement
 	 *
 	 * @constructor
+	 * @param {Object} [config] Configuration options
 	 * @cfg {boolean} [suggestions=true] Display search suggestions
 	 * @cfg {RegExp|Function|string} [validate] Perform title validation
 	 */

resources/src/mediawiki.widgets/mw.widgets.TitleSearchWidget.js

@@ -15,6 +15,7 @@
 	 * @mixins mw.widgets.TitleWidget
 	 *
 	 * @constructor
+	 * @param {Object} [config] Configuration options
 	 */
 	mw.widgets.TitleSearchWidget = function MwWidgetsTitleSearchWidget( config ) {
 		config = config || {};

resources/src/mediawiki.widgets/mw.widgets.UserInputWidget.js

@@ -90,6 +90,7 @@
 	 *
 	 * @method
 	 * @param {Mixed} response Response from server
+	 * @return {Object}
 	 */
 	mw.widgets.UserInputWidget.prototype.getLookupCacheDataFromResponse = function ( response ) {
 		return response.query.allusers || {};

resources/src/mediawiki/api.js

@@ -354,6 +354,7 @@
 		 *
 		 * @since 1.22
 		 * @param {string} type Token type
+		 * @param {string} [assert]
 		 * @return {jQuery.Promise} Received token.
 		 */
 		getToken: function ( type, assert ) {

resources/src/mediawiki/api/upload.js

@@ -46,6 +46,7 @@
 	 * Get new iframe object for an upload.
 	 *
 	 * @private
+	 * @param {string} id
 	 * @return {HTMLIframeElement}
 	 */
 	function getNewIframe( id ) {
@@ -59,6 +60,8 @@
 	 * Shortcut for getting hidden inputs
 	 *
 	 * @private
+	 * @param {string} name
+	 * @param {string} val
 	 * @return {jQuery}
 	 */
 	function getHiddenInput( name, val ) {
@@ -374,6 +377,7 @@
 		 *
 		 * @param {string} filekey
 		 * @param {Object} data
+		 * @return {jQuery.Promise}
 		 */
 		uploadFromStash: function ( filekey, data ) {
 			data.filekey = filekey;

resources/src/mediawiki/api/watch.js

@@ -12,6 +12,7 @@
 	 * @param {string|mw.Title|string[]|mw.Title[]} pages Full page name or instance of mw.Title, or an
 	 *  array thereof. If an array is passed, the return value passed to the promise will also be an
 	 *  array of appropriate objects.
+	 * @param {Object} [addParams]
 	 * @return {jQuery.Promise}
 	 * @return {Function} return.done
 	 * @return {Object|Object[]} return.done.watch Object or list of objects (depends on the `pages`

resources/src/mediawiki/htmlform/htmlform.Element.js

@@ -10,6 +10,7 @@
 	 * Currently only supports passing 'hide-if' data.
 	 *
 	 * @ignore
+	 * @param {Object} [config] Configuration options
 	 */
 	mw.htmlform.Element = function ( config ) {
 		// Configuration initialization

resources/src/mediawiki/mediawiki.ForeignStructuredUpload.BookletLayout.js

@@ -18,6 +18,9 @@
 	 * @class mw.ForeignStructuredUpload.BookletLayout
 	 * @uses mw.ForeignStructuredUpload
 	 * @extends mw.Upload.BookletLayout
+	 *
+	 * @constructor
+	 * @param {Object} config Configuration options
 	 * @cfg {string} [target] Used to choose the target repository.
 	 *     If nothing is passed, the {@link mw.ForeignUpload#property-target default} is used.
 	 */

resources/src/mediawiki/mediawiki.ForeignStructuredUpload.js

@@ -1,8 +1,5 @@
 ( function ( mw, $, OO ) {
 	/**
-	 * @class mw.ForeignStructuredUpload
-	 * @extends mw.ForeignUpload
-	 *
 	 * Used to represent an upload in progress on the frontend.
 	 *
 	 * This subclass will upload to a wiki using a structured metadata
@@ -14,7 +11,12 @@
 	 * **TODO: This currently only supports uploads under CC-BY-SA 4.0,
 	 * and should really have support for more licenses.**
 	 *
-	 * @inheritdoc
+	 * @class mw.ForeignStructuredUpload
+	 * @extends mw.ForeignUpload
+	 *
+	 * @constructor
+	 * @param {string} [target]
+	 * @param {Object} [apiconfig]
 	 */
 	function ForeignStructuredUpload( target, apiconfig ) {
 		this.date = undefined;

resources/src/mediawiki/mediawiki.ForeignUpload.js

@@ -1,8 +1,5 @@
 ( function ( mw, OO, $ ) {
 	/**
-	 * @class mw.ForeignUpload
-	 * @extends mw.Upload
-	 *
 	 * Used to represent an upload in progress on the frontend.
 	 *
 	 * Subclassed to upload to a foreign API, with no other goodies. Use
@@ -12,6 +9,9 @@
 	 * an object, we assume you want the default, and treat it as apiconfig
 	 * instead.
 	 *
+	 * @class mw.ForeignUpload
+	 * @extends mw.Upload
+	 *
 	 * @constructor
 	 * @param {string} [target] Used to set up the target
 	 *     wiki. If not remote, this class behaves identically to mw.Upload (unless further subclassed)
@@ -115,6 +115,8 @@
 
 	/**
 	 * Override from mw.Upload to make sure the API info is found and allowed
+	 *
+	 * @inheritdoc
 	 */
 	ForeignUpload.prototype.upload = function () {
 		var upload = this;
@@ -126,6 +128,8 @@
 
 	/**
 	 * Override from mw.Upload to make sure the API info is found and allowed
+	 *
+	 * @inheritdoc
 	 */
 	ForeignUpload.prototype.uploadToStash = function () {
 		var upload = this;

resources/src/mediawiki/mediawiki.Title.js

@@ -12,9 +12,6 @@
 	 * directly, passing invalid titles will result in an exception. Use #newFromText to use the
 	 * logic directly and get null for invalid titles which is easier to work with.
 	 *
-	 * @class mw.Title
-	 */
-	/**
 	 * Note that in the constructor and #newFromText method, `namespace` is the **default** namespace
 	 * only, and can be overridden by a namespace prefix in `title`. If you do not want this behavior,
 	 * use #makeTitle. Compare:
@@ -31,7 +28,8 @@
 	 *     mw.Title.newFromText( 'Template:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo'
 	 *     mw.Title.makeTitle( NS_TEMPLATE, 'Template:Foo' ).getPrefixedText();   // => 'Template:Template:Foo'
 	 *
-	 * @method constructor
+	 * @class mw.Title
+	 * @constructor
 	 * @param {string} title Title of the page. If no second argument given,
 	 *  this will be searched for a namespace
 	 * @param {number} [namespace=NS_MAIN] If given, will used as default namespace for the given title
@@ -47,8 +45,6 @@
 		this.title = parsed.title;
 		this.ext = parsed.ext;
 		this.fragment = parsed.fragment;
-
-		return this;
 	}
 
 	/* Private members */

resources/src/mediawiki/mediawiki.Upload.Dialog.js

@@ -29,6 +29,9 @@
 	 * @uses mw.Upload
 	 * @uses mw.Upload.BookletLayout
 	 * @extends OO.ui.ProcessDialog
+	 *
+	 * @constructor
+	 * @param {Object} [config] Configuration options
 	 * @cfg {Function} [bookletClass=mw.Upload.BookletLayout] Booklet class to be
 	 *     used for the steps
 	 * @cfg {Object} [booklet] Booklet constructor configuration

resources/src/mediawiki/mediawiki.Upload.js

@@ -2,8 +2,6 @@
 	var UP;
 
 	/**
-	 * @class mw.Upload
-	 *
 	 * Used to represent an upload in progress on the frontend.
 	 * Most of the functionality is implemented in mw.Api.plugin.upload,
 	 * but this model class will tie it together as well as let you perform
@@ -43,6 +41,8 @@
 	 *       } );
 	 *     } );
 	 *
+	 * @class mw.Upload
+	 *
 	 * @constructor
 	 * @param {Object|mw.Api} [apiconfig] A mw.Api object (or subclass), or configuration
 	 *     to pass to the constructor of mw.Api.

resources/src/mediawiki/mediawiki.Uri.js

@@ -143,6 +143,7 @@
 	 * @param {string|Function} documentLocation A full url, or function returning one.
 	 *  If passed a function, the return value may change over time and this will be honoured. (T74334)
 	 * @member mw
+	 * @return {Function} Uri class
 	 */
 	mw.UriRelative = function ( documentLocation ) {
 		var getDefaultUri = ( function () {

resources/src/mediawiki/mediawiki.confirmCloseWindow.js

@@ -1,8 +1,5 @@
 ( function ( mw, $ ) {
 	/**
-	 * @method confirmCloseWindow
-	 * @member mw
-	 *
 	 * Prevent the closing of a window with a confirm message (the onbeforeunload event seems to
 	 * work in most browsers.)
 	 *
@@ -24,6 +21,8 @@
 	 *         // do whatever you wanted to do
 	 *     }
 	 *
+	 * @method confirmCloseWindow
+	 * @member mw
 	 * @param {Object} [options]
 	 * @param {string} [options.namespace] Namespace for the event registration
 	 * @param {string} [options.message]

resources/src/mediawiki/mediawiki.debug.js

@@ -231,6 +231,8 @@
 
 		/**
 		 * Build the console panel
+		 *
+		 * @return {jQuery} Console panel
 		 */
 		buildConsoleTable: function () {
 			var $table, entryTypeText, i, length, entry;

resources/src/mediawiki/mediawiki.errorLogger.js

@@ -38,6 +38,12 @@
 			/**
 			 * Dumb window.onerror handler which forwards the errors via mw.track.
 			 *
+			 * @param {string} errorMessage
+			 * @param {string} url
+			 * @param {number} lineNumber
+			 * @param {number} [columnNumber]
+			 * @param {Error|Mixed} [errorObject]
+			 * @return {boolean} True to prevent the default action
 			 * @fires global_error
 			 */
 			window.onerror = function ( errorMessage, url, lineNumber, columnNumber, errorObject ) {

resources/src/mediawiki/mediawiki.inspect.js

@@ -190,6 +190,8 @@
 			/**
 			 * Generate a breakdown of all loaded modules and their size in
 			 * kilobytes. Modules are ordered from largest to smallest.
+			 *
+			 * @return {Object[]} Size reports
 			 */
 			size: function () {
 				// Map each module to a descriptor object.
@@ -215,6 +217,8 @@
 			/**
 			 * For each module with styles, count the number of selectors, and
 			 * count how many match against some element currently in the DOM.
+			 *
+			 * @return {Object[]} CSS reports
 			 */
 			css: function () {
 				var modules = [];
@@ -243,6 +247,8 @@
 			 * Report stats on mw.loader.store: the number of localStorage
 			 * cache hits and misses, the number of items purged from the
 			 * cache, and the total size of the module blob in localStorage.
+			 *
+			 * @return {Object[]} Store stats
 			 */
 			store: function () {
 				var raw, stats = { enabled: mw.loader.store.enabled };

resources/src/mediawiki/mediawiki.jqueryMsg.js

@@ -907,7 +907,8 @@
 			/**
 			 * Starts the parse
 			 *
-			 * @param {Function} rootExpression root parse function
+			 * @param {Function} rootExpression Root parse function
+			 * @return {Array|null}
 			 */
 			function start( rootExpression ) {
 				var result = nOrMore( 0, rootExpression )();
@@ -937,6 +938,9 @@
 
 	/**
 	 * htmlEmitter - object which primarily exists to emit HTML from parser ASTs
+	 *
+	 * @param {Object} language
+	 * @param {Object} magic
 	 */
 	mw.jqueryMsg.htmlEmitter = function ( language, magic ) {
 		var jmsg = this;
@@ -1050,6 +1054,7 @@
 		 * It may, though, if the wikitext appears in extension-controlled content.
 		 *
 		 * @param {string[]} nodes
+		 * @return {jQuery}
 		 */
 		wikilink: function ( nodes ) {
 			var page, anchor, url, $el;

resources/src/mediawiki/mediawiki.js

@@ -304,6 +304,7 @@
 			return mw.format.apply( null, [ this.map.get( this.key ) ].concat( this.parameters ) );
 		},
 
+		// eslint-disable-next-line valid-jsdoc
 		/**
 		 * Add (does not replace) parameters for `$N` placeholder values.
 		 *
@@ -418,6 +419,7 @@
 		}
 	};
 
+	/* eslint-disable no-console */
 	log = ( function () {
 		// Also update the restoration of methods in mediawiki.log.js
 		// when adding or removing methods here.
@@ -506,6 +508,7 @@
 
 		return log;
 	}() );
+	/* eslint-enable no-console */
 
 	/**
 	 * @class mw
@@ -1241,6 +1244,8 @@
 			 * Utility function for execute()
 			 *
 			 * @ignore
+			 * @param {string} [media] Media attribute
+			 * @param {string} url URL
 			 */
 			function addLink( media, url ) {
 				var el = document.createElement( 'link' );
@@ -1506,6 +1511,8 @@
 			 * to a query string of the form foo.bar,baz|bar.baz,quux
 			 *
 			 * @private
+			 * @param {Object} moduleMap Module map
+			 * @return {string} Module query string
 			 */
 			function buildModulesString( moduleMap ) {
 				var p, prefix,
@@ -2147,6 +2154,8 @@
 				 *
 				 * @protected
 				 * @since 1.27
+				 * @param {string} moduleName Module name
+				 * @return {Mixed} Exported value
 				 */
 				require: function ( moduleName ) {
 					var state = mw.loader.getState( moduleName );
@@ -2313,6 +2322,7 @@
 					 *
 					 * @param {string} module Module name
 					 * @param {Object} descriptor The module's descriptor as set in the registry
+					 * @return {boolean} Module was set
 					 */
 					set: function ( module, descriptor ) {
 						var args, key, src;
@@ -2357,7 +2367,7 @@
 							}
 						} catch ( e ) {
 							mw.track( 'resourceloader.exception', { exception: e, source: 'store-localstorage-json' } );
-							return;
+							return false;
 						}
 
 						src = 'mw.loader.implement(' + args.join( ',' ) + ');';
@@ -2366,11 +2376,14 @@
 						}
 						mw.loader.store.items[ key ] = src;
 						mw.loader.store.update();
+						return true;
 					},
 
 					/**
 					 * Iterate through the module store, removing any item that does not correspond
 					 * (in name and version) to an item in the module registry.
+					 *
+					 * @return {boolean} Store was pruned
 					 */
 					prune: function () {
 						var key, module;
@@ -2389,6 +2402,7 @@
 								delete mw.loader.store.items[ key ];
 							}
 						}
+						return true;
 					},
 
 					/**
@@ -2570,6 +2584,8 @@
 				 * Wrapper object for raw HTML passed to mw.html.element().
 				 *
 				 * @class mw.html.Raw
+				 * @constructor
+				 * @param {string} value
 				 */
 				Raw: function ( value ) {
 					this.value = value;
@@ -2579,6 +2595,8 @@
 				 * Wrapper object for CDATA element contents passed to mw.html.element()
 				 *
 				 * @class mw.html.Cdata
+				 * @constructor
+				 * @param {string} value
 				 */
 				Cdata: function ( value ) {
 					this.value = value;
@@ -2677,6 +2695,7 @@
 					 */
 					remove: list.remove,
 
+					// eslint-disable-next-line valid-jsdoc
 					/**
 					 * Run a hook.
 					 *
@@ -2710,6 +2729,7 @@
 	 * @param {string} [data.module] Name of module which caused the error
 	 */
 	function logError( topic, data ) {
+		/* eslint-disable no-console */
 		var msg,
 			e = data.exception,
 			source = data.source,
@@ -2731,6 +2751,7 @@
 				console.error( String( e ), e );
 			}
 		}
+		/* eslint-enable no-console */
 	}
 
 	// Subscribe to error streams

resources/src/mediawiki/mediawiki.notification.js

@@ -23,6 +23,8 @@
 	 * @alternateClassName mw.Notification
 	 * @constructor
 	 * @private
+	 * @param {mw.Message|jQuery|HTMLElement|string} message
+	 * @param {Object} options
 	 */
 	function Notification( message, options ) {
 		var $notification, $notificationContent;

resources/src/mediawiki/mediawiki.searchSuggest.js

@@ -92,13 +92,15 @@
 		}
 
 		/**
-		 * defines the location of autocomplete. Typically either
+		 * Defines the location of autocomplete. Typically either
 		 * header, which is in the top right of vector (for example)
 		 * and content which identifies the main search bar on
-		 * Special:Search.  Defaults to header for skins that don't set
+		 * Special:Search. Defaults to header for skins that don't set
 		 * explicitly.
 		 *
 		 * @ignore
+		 * @param {Object} context
+		 * @return {string}
 		 */
 		function getInputLocation( context ) {
 			return context.config.$region
@@ -112,6 +114,7 @@
 		 * 'this' is the search input box (jQuery object)
 		 *
 		 * @ignore
+		 * @param {Object} metadata
 		 */
 		function onAfterUpdate( metadata ) {
 			var context = this.data( 'suggestionsContext' );

resources/src/mediawiki/mediawiki.template.mustache.js

@@ -16,6 +16,7 @@
 				 * @param {Object} data Data to render
 				 * @param {Object} partialTemplates Map partial names to Mustache template objects
 				 *  returned by mw.template.get()
+				 * @return {jQuery} Rendered HTML
 				 */
 				render: function ( data, partialTemplates ) {
 					var partials = {};

resources/src/mediawiki/mediawiki.util.js

@@ -50,6 +50,7 @@
 		 * Encode the string like PHP's rawurlencode
 		 *
 		 * @param {string} str String to be encoded.
+		 * @return {string} Encoded string
 		 */
 		rawurlencode: function ( str ) {
 			str = String( str );
@@ -62,6 +63,7 @@
 		 * Encode the string like Sanitizer::escapeId in PHP
 		 *
 		 * @param {string} str String to be encoded.
+		 * @return {string} Encoded string
 		 */
 		escapeId: function ( str ) {
 			str = String( str );
@@ -80,6 +82,7 @@
 		 * of `wfUrlencode` in PHP.
 		 *
 		 * @param {string} str String to be encoded.
+		 * @return {string} Encoded string
 		 */
 		wikiUrlencode: function ( str ) {
 			return util.rawurlencode( str )

resources/src/mediawiki/mediawiki.viewport.js

@@ -18,6 +18,7 @@
 		 *
 		 * @ignore
 		 * @private
+		 * @return {Object} Viewport positions
 		 */
 		makeViewportFromWindow: function () {
 			var $window = $( window ),

resources/src/mediawiki/page/gallery-slideshow.js

@@ -207,6 +207,8 @@
 	/**
 	 * Gets the height of the interface elements and the
 	 * gallery's caption.
+	 *
+	 * @return {number} Height
 	 */
 	mw.GallerySlideshow.prototype.getChromeHeight = function () {
 		return this.$interface.outerHeight() + this.$galleryCaption.outerHeight();

resources/src/startup.js

@@ -46,6 +46,9 @@ mwPerformance.mark( 'mwLoadStart' );
  * - Google Glass
  *
  * Other browsers that pass the check are considered Grade X.
+ *
+ * @param {string} [str] User agent, defaults to navigator.userAgent
+ * @return {boolean} User agent is compatible with MediaWiki JS
  */
 function isCompatible( str ) {
 	var ua = str || navigator.userAgent;