From 874d9c9e3b961184944fa08346145fe19192aa8b Mon Sep 17 00:00:00 2001 From: Stephen Niedzielski Date: Tue, 3 Jul 2018 09:50:09 -0500 Subject: [PATCH] Hygiene: update JSDoc boxed and JQuery types MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From TypeScript's do's and don'ts:[0] Don’t ever use the types Number, String, Boolean, or Object. These types refer to non-primitive boxed objects that are almost never used appropriately in JavaScript code. Although Minerva only uses JSDocs at this time which seemingly doesn't care about casing[1], we should endeavor to use the proper return types. This patch lowercases typing to indicate primitive / boxed type as appropriate.[2] As a special case, function types are uppercased for compatibility with TypeScript type checking. Also, JQuery types are of type "JQuery". The global JQuery object's identifier is "jQuery". This patch uppercases J's where appropriate. Lastly, replace unsupported type "Integer" with "number" and a comment. [0] https://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html#general-types [1] https://github.com/jsdoc3/jsdoc/issues/1046#issuecomment-126477791 [2] find resources tests -iname \*.js| xargs -rd\\n sed -ri ' s%\{\s*(number|string|boolean|object|null|undefined)%{\L\1%gi; s%\{\s*function%{Function%g; s%\{\s*jquery%{JQuery%gi; s%\{\s*integer\s*\}%{number} An integer.%gi ' Change-Id: I6cbac15940e4501aee7ede8f421b77ffd027170d --- resources/skins.minerva.editor/init.js | 4 ++-- resources/skins.minerva.mainMenu/MainMenu.js | 4 ++-- .../skins.minerva.newusers/PointerOverlay.js | 6 ++--- .../NotificationBadge.js | 22 +++++++++---------- .../skins.minerva.scripts/DownloadIcon.js | 12 +++++----- .../skins.minerva.scripts/cleanuptemplates.js | 6 ++--- resources/skins.minerva.scripts/init.js | 6 ++--- resources/skins.minerva.scripts/preInit.js | 2 +- resources/skins.minerva.scripts/references.js | 4 ++-- resources/skins.minerva.scripts/utils.js | 2 +- resources/skins.minerva.toggling/init.js | 2 +- 11 files changed, 35 insertions(+), 35 deletions(-) diff --git a/resources/skins.minerva.editor/init.js b/resources/skins.minerva.editor/init.js index 904795d..94dc56b 100644 --- a/resources/skins.minerva.editor/init.js +++ b/resources/skins.minerva.editor/init.js @@ -62,7 +62,7 @@ * @ignore * @param {number} section number * @param {string} container CSS selector of the container - * @return {jQuery.Object} newly created edit page button + * @return {JQuery.Object} newly created edit page button */ function addEditButton( section, container ) { $( container ).find( 'a' ).remove(); @@ -91,7 +91,7 @@ * Make an element render a CTA when clicked * @method * @ignore - * @param {jQuery.Object} $el Element which will render a drawer on click + * @param {JQuery.Object} $el Element which will render a drawer on click * @param {number} section number representing the section */ function makeCta( $el, section ) { diff --git a/resources/skins.minerva.mainMenu/MainMenu.js b/resources/skins.minerva.mainMenu/MainMenu.js index cc4e6cc..d8d5b8b 100644 --- a/resources/skins.minerva.mainMenu/MainMenu.js +++ b/resources/skins.minerva.mainMenu/MainMenu.js @@ -8,7 +8,7 @@ * @class MainMenu * @extends View * @constructor - * @param {Object} options Configuration options + * @param {object} options Configuration options * @module skins.minerva.mainMenu/MainMenu */ function MainMenu( options ) { @@ -24,7 +24,7 @@ }, /** - * @cfg {Object} defaults Default options hash. + * @cfg {object} defaults Default options hash. * @cfg {string} defaults.activator selector for element that when clicked can open or close the menu */ defaults: { diff --git a/resources/skins.minerva.newusers/PointerOverlay.js b/resources/skins.minerva.newusers/PointerOverlay.js index bfdf9db..8f7b794 100644 --- a/resources/skins.minerva.newusers/PointerOverlay.js +++ b/resources/skins.minerva.newusers/PointerOverlay.js @@ -19,7 +19,7 @@ closeOnContentTap: true, template: template.get( 'skins.minerva.newusers', 'PointerOverlay.hogan' ), /** - * @cfg {Object} defaults Default options hash. + * @cfg {object} defaults Default options hash. * @cfg {string} defaults.isCompact whether the pointer overlay should be compact * @cfg {number} defaults.timeout in milliseconds. If not zero the pointer overlay will * hide after this duration of time. @@ -82,7 +82,7 @@ /** * Position the overlay under a specified element * @private - * @param {jQuery.Object} $pa An element that should be pointed at by the overlay + * @param {JQuery.Object} $pa An element that should be pointed at by the overlay */ _position: function ( $pa ) { var left, @@ -99,7 +99,7 @@ /** * Position overlay and add pointer arrow that points at specified element * @method - * @param {jQuery.Object} $pa An element that should be pointed at by the overlay + * @param {JQuery.Object} $pa An element that should be pointed at by the overlay */ addPointerArrow: function ( $pa ) { var left, diff --git a/resources/skins.minerva.notifications.badge/NotificationBadge.js b/resources/skins.minerva.notifications.badge/NotificationBadge.js index 3957a79..f3a101b 100644 --- a/resources/skins.minerva.notifications.badge/NotificationBadge.js +++ b/resources/skins.minerva.notifications.badge/NotificationBadge.js @@ -13,7 +13,7 @@ * @extends View * * @constructor - * @param {Object} options Configuration options + * @param {object} options Configuration options * @module skins.minerva.notifications/NotificationBadge */ function NotificationBadge( options ) { @@ -41,11 +41,11 @@ OO.mfExtend( NotificationBadge, View, { /** - * @cfg {Object} defaults Default options hash. - * @cfg {String} defaults.notificationIconClass e.g. mw-ui-icon for icon - * @cfg {String} defaults.loadingIconHtml for spinner - * @cfg {Boolean} defaults.hasUnseenNotifications whether the user has unseen notifications - * @cfg {Number} defaults.notificationCountRaw number of unread notifications + * @cfg {object} defaults Default options hash. + * @cfg {string} defaults.notificationIconClass e.g. mw-ui-icon for icon + * @cfg {string} defaults.loadingIconHtml for spinner + * @cfg {boolean} defaults.hasUnseenNotifications whether the user has unseen notifications + * @cfg {number} defaults.notificationCountRaw number of unread notifications */ defaults: { notificationIconClass: notificationIcon.getClassName(), @@ -60,7 +60,7 @@ * @method * @private * @param {string} moduleName Name of a module to fetch - * @return {jQuery.Deferred} + * @return {JQuery.Deferred} */ _loadModuleScript: function ( moduleName ) { var self = this; @@ -76,7 +76,7 @@ * @method * @private * @uses NotificationsOverlay - * @return {jQuery.Deferred} with an instance of NotificationsOverlay + * @return {JQuery.Deferred} with an instance of NotificationsOverlay */ _loadNotificationOverlay: function () { var self = this; @@ -116,7 +116,7 @@ template: mw.template.get( 'skins.minerva.notifications.badge', 'badge.hogan' ), /** * Click handler for clicking on the badge - * @return {Boolean} + * @return {boolean} */ onClickBadge: function () { this.options.router.navigate( '#/notifications' ); @@ -126,14 +126,14 @@ }, /** * Return the URL for the full non-overlay notification view - * @return {String} url + * @return {string} url */ getNotificationURL: function () { return this.options.url; }, /** * Update the notification count - * @param {Number} count + * @param {number} count */ setCount: function ( count ) { if ( count > 100 ) { diff --git a/resources/skins.minerva.scripts/DownloadIcon.js b/resources/skins.minerva.scripts/DownloadIcon.js index 9c90672..cad6ca2 100644 --- a/resources/skins.minerva.scripts/DownloadIcon.js +++ b/resources/skins.minerva.scripts/DownloadIcon.js @@ -8,8 +8,8 @@ /** * Helper function to retreive the Android version * @ignore - * @param {String} userAgent User Agent - * @return {Integer} + * @param {string} userAgent User Agent + * @return {number} An integer. */ function getAndroidVersion( userAgent ) { var match = userAgent.toLowerCase().match( /android\s(\d\.]*)/ ); @@ -19,8 +19,8 @@ /** * Helper function to retrieve the Chrome/Chromium version * @ignore - * @param {String} userAgent User Agent - * @return {Integer} + * @param {string} userAgent User Agent + * @return {number} An integer. */ function getChromeVersion( userAgent ) { var match = userAgent.toLowerCase().match( /chrom(e|ium)\/(\d+)\./ ); @@ -33,7 +33,7 @@ * @extends Icon * * @param {Skin} skin - * @param {Number[]} [supportedNamespaces] + * @param {number[]} [supportedNamespaces] * @param {Window} [windowObj] window object * @constructor * @module skins.minerva.scripts/DownloadIcon @@ -54,7 +54,7 @@ /** * Checks whether DownloadIcon is available for given user agent * @param {string} userAgent User agent - * @return {Boolean} + * @return {boolean} */ isAvailable: function ( userAgent ) { var androidVersion = getAndroidVersion( userAgent ), diff --git a/resources/skins.minerva.scripts/cleanuptemplates.js b/resources/skins.minerva.scripts/cleanuptemplates.js index a1bd37a..89541ce 100644 --- a/resources/skins.minerva.scripts/cleanuptemplates.js +++ b/resources/skins.minerva.scripts/cleanuptemplates.js @@ -18,7 +18,7 @@ /** * Extract a summary message from a cleanup template generated element that is * friendly for mobile display. - * @param {Object} $box element to extract the message from + * @param {object} $box element to extract the message from * @ignore * @typedef {object} IssueSummary * @prop {string} icon HTML string. @@ -52,7 +52,7 @@ * @ignore * * @param {string} labelText The text value of the element - * @return {jQuery} + * @return {JQuery} */ function createLinkElement( labelText ) { return $( '' ) @@ -61,7 +61,7 @@ /** * Render a banner in a containing element. - * @param {jQuery.Object} $container to render the page issues banner inside. + * @param {JQuery.Object} $container to render the page issues banner inside. * @param {string} labelText what the label of the page issues banner should say * @param {string} headingText the heading of the overlay that is created when the page issues banner is clicked * @ignore diff --git a/resources/skins.minerva.scripts/init.js b/resources/skins.minerva.scripts/init.js index 42249db..e588b5e 100644 --- a/resources/skins.minerva.scripts/init.js +++ b/resources/skins.minerva.scripts/init.js @@ -14,7 +14,7 @@ /** * Event handler for clicking on an image thumbnail - * @param {jQuery.Event} ev + * @param {JQuery.Event} ev * @ignore */ function onClickImage( ev ) { @@ -23,7 +23,7 @@ } /** - * @param {jQuery.Element} thumbnail + * @param {JQuery.Element} thumbnail * @ignore */ function routeThumbnail( thumbnail ) { @@ -97,7 +97,7 @@ * @ignore * @uses ImageOverlay * @param {string} title Url of image - * @return {jQuery.Deferred} + * @return {JQuery.Deferred} */ function loadImageOverlay( title ) { if ( mw.loader.getState( 'mmv.bootstrap' ) === 'ready' ) { diff --git a/resources/skins.minerva.scripts/preInit.js b/resources/skins.minerva.scripts/preInit.js index 56a503c..3c037df 100644 --- a/resources/skins.minerva.scripts/preInit.js +++ b/resources/skins.minerva.scripts/preInit.js @@ -15,7 +15,7 @@ /** * Close navigation if skin is tapped - * @param {jQuery.Event} ev + * @param {JQuery.Event} ev * @private */ function onSkinClick( ev ) { diff --git a/resources/skins.minerva.scripts/references.js b/resources/skins.minerva.scripts/references.js index 0f520d8..447ce8d 100644 --- a/resources/skins.minerva.scripts/references.js +++ b/resources/skins.minerva.scripts/references.js @@ -38,7 +38,7 @@ /** * Event handler to show reference when a reference link is clicked * @ignore - * @param {jQuery.Event} ev Click event of the reference element + * @param {JQuery.Event} ev Click event of the reference element * @param {ReferencesDrawer} drawer to show the reference in * @param {Page} page */ @@ -83,7 +83,7 @@ * Delegates to `showReference` once the references drawer is ready. * * @ignore - * @param {jQuery.Event} ev Click event of the reference element + * @param {JQuery.Event} ev Click event of the reference element */ function onClickReference( ev ) { if ( !drawer ) { diff --git a/resources/skins.minerva.scripts/utils.js b/resources/skins.minerva.scripts/utils.js index 834649a..7483b0e 100644 --- a/resources/skins.minerva.scripts/utils.js +++ b/resources/skins.minerva.scripts/utils.js @@ -35,7 +35,7 @@ M.define( 'skins.minerva.scripts/utils', { /** * Extract an icon for use with the issue. - * @param {jQuery.Object} $box element to extract the icon from + * @param {JQuery.Object} $box element to extract the icon from * @return {Icon} representing the icon */ getIconFromAmbox: getIconFromAmbox diff --git a/resources/skins.minerva.toggling/init.js b/resources/skins.minerva.toggling/init.js index ee77610..9f67db9 100644 --- a/resources/skins.minerva.toggling/init.js +++ b/resources/skins.minerva.toggling/init.js @@ -16,7 +16,7 @@ * Initialises toggling code. * * @method - * @param {jQuery.Object} $container to enable toggling on + * @param {JQuery.Object} $container to enable toggling on * @param {string} prefix a prefix to use for the id. * @param {Page} page The current page * @ignore