Jdlrobson has uploaded a new change for review.
https://gerrit.wikimedia.org/r/167998
Change subject: Hygiene: Documentation cleanup
......................................................................
Hygiene: Documentation cleanup
Use /* for code which shouldn't be documented in the js documentation
rather than /**
Update a few incorrect tests.
jsduck now runs without errors.
Change-Id: I3345d505b5aa2b0d6082c1a414d7ea2d0add4a7d
---
M Makefile
M javascripts/OverlayManager.js
M javascripts/mainmenu.js
M javascripts/modules/editor/editor.js
M javascripts/modules/languages/languages.js
M javascripts/modules/lastEdited/lastEdited.js
M javascripts/modules/mainmenutweaks.js
M javascripts/modules/mediaViewer/ImageApi.js
M javascripts/modules/mf-stop-mobile-redirect.js
M javascripts/modules/notifications/notifications.js
M javascripts/modules/toggling/toggle.js
M javascripts/modules/uploads/PhotoApi.js
M javascripts/modules/watchstar/WatchstarApi.js
M javascripts/modules/watchstar/init.js
M javascripts/modules/wikigrok/WikiDataApi.js
M javascripts/modules/wikigrok/WikiGrokApi.js
M javascripts/modules/wikigrok/WikiGrokDialogB.js
M javascripts/specials/notifications.js
M javascripts/specials/uploads.js
19 files changed, 35 insertions(+), 33 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/MobileFrontend
refs/changes/98/167998/1
diff --git a/Makefile b/Makefile
index 263df88..0101b43 100644
--- a/Makefile
+++ b/Makefile
@@ -32,7 +32,7 @@
jsduck: gems ## Build the JavaScript documentation
rm -rf docs/js
mkdir -p docs
- jsduck ${MW_INSTALL_PATH}/extensions/Mantle/javascripts/ javascripts/
--output docs/js/
--external=OO.EventEmitter,jQuery.Object,Hogan.Template,HandleBars.Template,jQuery.Deferred,mw.user
--exclude=javascripts/external --ignore-global
+ jsduck ${MW_INSTALL_PATH}/extensions/Mantle/javascripts/ javascripts/
--output docs/js/
--external=OO.EventEmitter,jQuery.Object,Hogan.Template,HandleBars.Template,jQuery.Deferred,jQuery.Event,mw.user
--exclude=javascripts/external --ignore-global
phpdoc: nodecheck ## Build the PHP documentation
mkdir -p docs
diff --git a/javascripts/OverlayManager.js b/javascripts/OverlayManager.js
index 03a6e0a..6266808 100644
--- a/javascripts/OverlayManager.js
+++ b/javascripts/OverlayManager.js
@@ -86,7 +86,7 @@
/**
* A callback for Router's `route` event.
*
- * @param {$.Event} ev Event object.
+ * @param {jQuery.Event} ev Event object.
*/
_checkRoute: function( ev ) {
var
@@ -122,8 +122,8 @@
* Check if a given path matches one of the entries.
*
* @param {string} path Path (hash) to check.
- * @param {object} entry Entry object created in
OverlayManager#add.
- * @return {object|null} Match object with factory function's
result
+ * @param {Object} entry Entry object created in
OverlayManager#add.
+ * @return {Object} Match object with factory function's
result. Returns null if no match.
* or null if no match.
*/
_matchRoute: function( path, entry ) {
@@ -155,7 +155,7 @@
* Add an overlay that should be shown for a specific fragment
identifier.
*
* The following code will display an overlay whenever a user
visits a URL that
- * end with '#/hi/<name>'. The value of <name> will be passed
to the overlay.
+ * end with '#/hi/name'. The value of `name` will be passed to
the overlay.
*
* @example
* overlayManager.add( /\/hi\/(.*)/, function( name ) {
diff --git a/javascripts/mainmenu.js b/javascripts/mainmenu.js
index 52c8167..7010f10 100644
--- a/javascripts/mainmenu.js
+++ b/javascripts/mainmenu.js
@@ -4,7 +4,7 @@
return $( 'body' ).hasClass( 'navigation-enabled' );
}
- /**
+ /*
* Closes all open navigation drawers
*/
function closeNavigationDrawers() {
@@ -13,7 +13,7 @@
removeClass( 'primary-navigation-enabled' );
}
- /**
+ /*
* @param {String} drawerType A name that identifies the navigation
drawer that should be toggled open
*/
function openNavigationDrawer( drawerType ) {
diff --git a/javascripts/modules/editor/editor.js
b/javascripts/modules/editor/editor.js
index 0dafde8..ee4b99a 100644
--- a/javascripts/modules/editor/editor.js
+++ b/javascripts/modules/editor/editor.js
@@ -60,7 +60,7 @@
on( 'click', false );
}
- /**
+ /*
* Retrieve the user's preferred editor setting. If none is set, return
the default
* editor for this wiki.
*
@@ -80,7 +80,7 @@
}
}
- /**
+ /*
* Initialize the edit button so that it launches the editor interface
when clicked.
*
* @param {Page} page The page to edit.
@@ -176,7 +176,7 @@
} );
}
- /**
+ /*
* Initialize the edit button so that it launches a login
call-to-action when clicked.
* @param {boolean} allowAnonymous Whether the drawer has to include an
edit anonymously link
*/
@@ -204,7 +204,7 @@
} );
}
- /**
+ /*
* Show a toast message with sincere condolences.
*
* @param {string} msg Message key for sorry message
diff --git a/javascripts/modules/languages/languages.js
b/javascripts/modules/languages/languages.js
index 49e1951..291305f 100644
--- a/javascripts/modules/languages/languages.js
+++ b/javascripts/modules/languages/languages.js
@@ -21,7 +21,7 @@
return result;
} );
- /**
+ /*
* Hijack the Special:Languages link and replace it with a trigger to a
LanguageOverlay
* that displays the same data
*/
diff --git a/javascripts/modules/lastEdited/lastEdited.js
b/javascripts/modules/lastEdited/lastEdited.js
index 850acc0..b23fe10 100644
--- a/javascripts/modules/lastEdited/lastEdited.js
+++ b/javascripts/modules/lastEdited/lastEdited.js
@@ -2,7 +2,7 @@
var time = M.require( 'modules/lastEdited/time' );
- /**
+ /*
* Initialisation function for last modified module.
*
* Enhances #mw-mf-last-modified element
diff --git a/javascripts/modules/mainmenutweaks.js
b/javascripts/modules/mainmenutweaks.js
index 86edfa5..518ec01 100644
--- a/javascripts/modules/mainmenutweaks.js
+++ b/javascripts/modules/mainmenutweaks.js
@@ -1,4 +1,4 @@
-/**
+/*
* Disables functionality that is not supported by the app
*/
( function( M, $ ) {
diff --git a/javascripts/modules/mediaViewer/ImageApi.js
b/javascripts/modules/mediaViewer/ImageApi.js
index 4284938..40bb294 100644
--- a/javascripts/modules/mediaViewer/ImageApi.js
+++ b/javascripts/modules/mediaViewer/ImageApi.js
@@ -3,7 +3,7 @@
ImageApi,
Api = M.require( 'api' ).Api;
- /**
+ /*
* Gets the first size larger than or equal to the provided size.
*/
function findSizeBucket( size ) {
diff --git a/javascripts/modules/mf-stop-mobile-redirect.js
b/javascripts/modules/mf-stop-mobile-redirect.js
index c7c0b78..2df7f0f 100644
--- a/javascripts/modules/mf-stop-mobile-redirect.js
+++ b/javascripts/modules/mf-stop-mobile-redirect.js
@@ -1,4 +1,4 @@
-/**
+/*
* Warn people if they're trying to switch to desktop but have cookies
disabled.
*/
diff --git a/javascripts/modules/notifications/notifications.js
b/javascripts/modules/notifications/notifications.js
index 8243518..895e85a 100644
--- a/javascripts/modules/notifications/notifications.js
+++ b/javascripts/modules/notifications/notifications.js
@@ -1,4 +1,4 @@
-/**
+/*
* This code loads the necessary modules for the notifications overlay, not to
be confused
* with the Toast notifications defined by common/toast.js.
*/
@@ -7,7 +7,7 @@
mainmenu = M.require( 'mainmenu' ),
$btn = $( '#secondary-button.user-button' );
- /**
+ /*
* Loads a ResourceLoader module script. Shows ajax loader whilst
loading.
*
* FIXME: Upstream to mw.mobileFrontend and reuse elsewhere
diff --git a/javascripts/modules/toggling/toggle.js
b/javascripts/modules/toggling/toggle.js
index 7d40b72..1a9995c 100644
--- a/javascripts/modules/toggling/toggle.js
+++ b/javascripts/modules/toggling/toggle.js
@@ -9,7 +9,7 @@
return expandedSections;
}
- /**
+ /*
* Save expandedSections to localStorage
*/
function saveExpandedSections( expandedSections ) {
@@ -18,7 +18,7 @@
);
}
- /**
+ /*
* Given an expanded heading, store it to localStorage.
* If the heading is collapsed, remove it from localStorage.
*
@@ -40,7 +40,7 @@
}
}
- /**
+ /*
* Expand sections that were previously expanded before leaving this
page.
*/
function expandStoredSections( $container ) {
@@ -82,7 +82,7 @@
saveExpandedSections( expandedSections );
}
- /**
+ /*
* Given a heading, toggle it and any of its children
*
* @param {jQuery.Object} $heading A heading belonging to a section
@@ -108,7 +108,7 @@
}
}
- /**
+ /*
* Enables toggling via enter and space keys
*
* @param {jQuery.Object} $heading
@@ -124,7 +124,7 @@
} );
}
- /**
+ /*
* Reveals an element and its parent section as identified by it's id
*
* @param {String} selector A css selector that identifies a single
element
diff --git a/javascripts/modules/uploads/PhotoApi.js
b/javascripts/modules/uploads/PhotoApi.js
index 7469420..0c92edd 100644
--- a/javascripts/modules/uploads/PhotoApi.js
+++ b/javascripts/modules/uploads/PhotoApi.js
@@ -45,7 +45,7 @@
return str;
}
- /**
+ /*
* Generates a file name from a description and a date
* Removes illegal characters
* Respects maximum file name length (240 bytes)
diff --git a/javascripts/modules/watchstar/WatchstarApi.js
b/javascripts/modules/watchstar/WatchstarApi.js
index 62a2780..a5b399a 100644
--- a/javascripts/modules/watchstar/WatchstarApi.js
+++ b/javascripts/modules/watchstar/WatchstarApi.js
@@ -21,7 +21,7 @@
/**
* Loads the watch status for a given list of page ids in bulk
* @method
- * @param {array} ids A list of page ids
+ * @param {Array} ids A list of page ids
* @param {boolean} markAsAllWatched When true will assume all
given ids are watched without a lookup.
* @return {jQuery.Deferred}
*/
diff --git a/javascripts/modules/watchstar/init.js
b/javascripts/modules/watchstar/init.js
index 36b7840..56e4a1d 100644
--- a/javascripts/modules/watchstar/init.js
+++ b/javascripts/modules/watchstar/init.js
@@ -3,7 +3,7 @@
var Watchstar = M.require( 'modules/watchstar/Watchstar' ),
user = M.require( 'user' );
- /**
+ /*
* Toggle the watch status of a known page
* @method
* @param {Page} page
diff --git a/javascripts/modules/wikigrok/WikiDataApi.js
b/javascripts/modules/wikigrok/WikiDataApi.js
index 20c362f..e79bfab 100644
--- a/javascripts/modules/wikigrok/WikiDataApi.js
+++ b/javascripts/modules/wikigrok/WikiDataApi.js
@@ -46,7 +46,7 @@
* Get labels for an item from Wikidata
* See: https://www.wikidata.org/wiki/Help:Label
*
- * @param {array} itemIds for items in Wikidata
+ * @param {Array} itemIds for items in Wikidata
* @return {jQuery.Deferred} Object returned by ajax call
*/
getLabels: function( itemIds ) {
diff --git a/javascripts/modules/wikigrok/WikiGrokApi.js
b/javascripts/modules/wikigrok/WikiGrokApi.js
index d10eebd..43151e7 100644
--- a/javascripts/modules/wikigrok/WikiGrokApi.js
+++ b/javascripts/modules/wikigrok/WikiGrokApi.js
@@ -17,7 +17,7 @@
/**
* Saves claims to the wikigrok api server
* @method
- * @param {array} claims a list of claims. Each claim must have
correct, prop, propid, value and valueid set
+ * @param {Array} claims a list of claims. Each claim must have
correct, prop, propid, value and valueid set
* @return {jQuery.Deferred}
*/
recordClaims: function( claims ) {
diff --git a/javascripts/modules/wikigrok/WikiGrokDialogB.js
b/javascripts/modules/wikigrok/WikiGrokDialogB.js
index 12fa366..7990fa0 100644
--- a/javascripts/modules/wikigrok/WikiGrokDialogB.js
+++ b/javascripts/modules/wikigrok/WikiGrokDialogB.js
@@ -23,7 +23,7 @@
* Renders a set of checkbox buttons to the panel
* Shows panel to user when there are suggestions.
* @method
- * @param {array} suggestions as returned by
WikiGrokApi.getSuggestions
+ * @param {Array} suggestions as returned by
WikiGrokApi.getSuggestions
*/
_renderSuggestions: function( suggestions ) {
var
diff --git a/javascripts/specials/notifications.js
b/javascripts/specials/notifications.js
index 7b7c18f..4bfcdb9 100644
--- a/javascripts/specials/notifications.js
+++ b/javascripts/specials/notifications.js
@@ -25,8 +25,9 @@
} );
}
- /**
+ /*
* Load more notification records.
+ * @method
*/
function loadMore() {
var notifications, data, container, $li, unread = [];
@@ -82,8 +83,9 @@
} );
}
- /**
+ /*
* Mark notifications as read.
+ * @method
*/
function markAsRead( unread ) {
api.getTokenWithEndpoint( 'edit' ).done( function( token ) {
diff --git a/javascripts/specials/uploads.js b/javascripts/specials/uploads.js
index da49307..2a3b758 100644
--- a/javascripts/specials/uploads.js
+++ b/javascripts/specials/uploads.js
@@ -142,7 +142,7 @@
}
} );
- /**
+ /*
* Returns a description based on the file name using
* a regular expression that strips the file type suffix,
* namespace prefix and any
--
To view, visit https://gerrit.wikimedia.org/r/167998
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I3345d505b5aa2b0d6082c1a414d7ea2d0add4a7d
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/extensions/MobileFrontend
Gerrit-Branch: master
Gerrit-Owner: Jdlrobson <[email protected]>
_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
