Bmansurov has uploaded a new change for review.
https://gerrit.wikimedia.org/r/180661
Change subject: Update documentation
......................................................................
Update documentation
Change-Id: Id86740b89cd18c87d017653b8599b4e753eff110
---
M javascripts/Overlay.js
M javascripts/OverlayManager.js
M javascripts/PageApi.js
M javascripts/Router.js
M javascripts/icons.js
M javascripts/settings.js
M javascripts/specials/mobileoptions.js
M javascripts/specials/notifications.js
M javascripts/specials/uploads/PhotoList.js
M javascripts/toast.js
10 files changed, 142 insertions(+), 65 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/MobileFrontend
refs/changes/61/180661/1
diff --git a/javascripts/Overlay.js b/javascripts/Overlay.js
index 7279fd7..eddb943 100644
--- a/javascripts/Overlay.js
+++ b/javascripts/Overlay.js
@@ -133,6 +133,10 @@
},
// FIXME: remove when OverlayManager used everywhere
+ /**
+ * Hide self when the route is visited
+ * @private
+ */
_hideOnRoute: function () {
var self = this;
M.router.once( 'route', function ( ev ) {
@@ -185,7 +189,7 @@
* Detach the overlay from the current view
*
* @method
- * @param {boolean} force: Whether the overlay should be closed
regardless of state (see PhotoUploadProgress)
+ * @param {boolean} force Whether the overlay should be closed
regardless of state (see PhotoUploadProgress)
* @return {boolean}: Whether the overlay was successfully
hidden or not
*/
hide: function ( force ) {
@@ -209,6 +213,12 @@
return true;
},
+ /**
+ * Fit the overlay content height to the window taking overlay
header and footer heights
+ * into consideration.
+ * @param {Number} windowHeight
+ * @private
+ */
_resizeContent: function ( windowHeight ) {
this.$overlayContent.height( windowHeight - this.$(
'.overlay-header-container' ).outerHeight() - this.$(
'.overlay-footer-container' ).outerHeight() );
},
@@ -224,6 +234,7 @@
* is open).
*
* @method
+ * @private
* @param {string} el CSS selector for elements that may
trigger virtual
* keyboard (usually inputs, textareas, contenteditables).
*/
@@ -256,9 +267,15 @@
}
},
+ /**
+ * Show elements that are selected by the className.
+ * Also hide .hideable elemetns
+ * Can't use jQuery's hide() and show() because show() sets
display: block.
+ * And we want display: table for headers.
+ * @param {String} className CSS selector to show
+ * @private
+ */
_showHidden: function ( className ) {
- // can't use jQuery's hide() and show() beause show()
sets display: block
- // and we want display: table for headers
this.$( '.hideable' ).addClass( 'hidden' );
this.$( className ).removeClass( 'hidden' );
}
diff --git a/javascripts/OverlayManager.js b/javascripts/OverlayManager.js
index a4aa688..2797d5d 100644
--- a/javascripts/OverlayManager.js
+++ b/javascripts/OverlayManager.js
@@ -27,6 +27,9 @@
this.hideCurrent = true;
},
+ /**
+ * @private
+ */
_onHideOverlay: function () {
// don't try to hide the active overlay on a route
change event triggered
// by hiding another overlay
@@ -35,6 +38,10 @@
this.router.back();
},
+ /**
+ * @param {Overlay} overlay to show
+ * @private
+ */
_showOverlay: function ( overlay ) {
// if hidden using overlay (not hardware) button,
update the state
overlay.once( 'hide', $.proxy( this, '_onHideOverlay' )
);
@@ -42,6 +49,11 @@
overlay.show();
},
+ /**
+ * @param {Overlay} overlay to hide
+ * @returns {boolean} Whether the overlay has been hidden
+ * @private
+ */
_hideOverlay: function ( overlay ) {
var result;
@@ -59,6 +71,10 @@
return result;
},
+ /**
+ * @param {Object|null} match Object with factory function's
result. null if no match.
+ * @private
+ */
_processMatch: function ( match ) {
var factoryResult,
self = this;
@@ -89,6 +105,7 @@
* A callback for Router's `route` event.
*
* @param {jQuery.Event} ev Event object.
+ * @private
*/
_checkRoute: function ( ev ) {
var
@@ -123,10 +140,11 @@
/**
* Check if a given path matches one of the entries.
*
- * @param {string} path Path (hash) to check.
+ * @param {String} path Path (hash) to check.
* @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.
+ * @private
*/
_matchRoute: function ( path, entry ) {
var
diff --git a/javascripts/PageApi.js b/javascripts/PageApi.js
index 7644984..71e2016 100644
--- a/javascripts/PageApi.js
+++ b/javascripts/PageApi.js
@@ -197,6 +197,7 @@
* Gets language list for a page; helper function for
getPageLanguages()
*
* @method
+ * @private
* @param {Object} data Data from API
* @return {Array} List of language objects
*/
@@ -226,6 +227,7 @@
* Gets language variant list for a page; helper function for
getPageLanguages()
*
* @method
+ * @private
* @param {string} title Name of the page to obtain variants
for
* @param {Object} data Data from API
* @return {Array} List of language variant objects
@@ -290,6 +292,13 @@
},
// FIXME: Where's a better place for these two functions to
live?
+ /**
+ * Extract sections from headings in $el
+ * @method
+ * @private
+ * @param {jQuery.Object} $el object from which sections are
extracted
+ * @returns {Array} Array of section objects created from
response HTML
+ */
_getAPIResponseFromHTML: function ( $el ) {
var $headings = $el.find( 'h1,h2,h3,h4,h5,h6' ),
sections = [];
@@ -308,6 +317,12 @@
return sections;
},
+ /**
+ * Order sections hierarchically
+ * @method
+ * @param {jQuery.Object} $el object from which sectiosn are
extracted
+ * @returns {Array}
+ */
getSectionsFromHTML: function ( $el ) {
return transformSections( this._getAPIResponseFromHTML(
$el ) );
}
diff --git a/javascripts/Router.js b/javascripts/Router.js
index 6b18a7a..fc1e581 100644
--- a/javascripts/Router.js
+++ b/javascripts/Router.js
@@ -4,6 +4,13 @@
EventEmitter = M.require( 'eventemitter' );
// FIXME: remove when OverlayManager used everywhere
+ /**
+ *
+ * @param {String} hash String to match
+ * @param {Object} entry Entry object
+ * @returns {boolean} Whether hash matches entry.path
+ * @ignore
+ */
function matchRoute( hash, entry ) {
var match = hash.match( entry.path );
if ( match ) {
diff --git a/javascripts/icons.js b/javascripts/icons.js
index 1b38104..fb784df 100644
--- a/javascripts/icons.js
+++ b/javascripts/icons.js
@@ -11,6 +11,7 @@
*
* @class icons
* @singleton
+ * @uses Icon
*/
M.define( 'icons', {
diff --git a/javascripts/settings.js b/javascripts/settings.js
index 4243e40..2679788 100644
--- a/javascripts/settings.js
+++ b/javascripts/settings.js
@@ -9,68 +9,71 @@
var browser = M.require( 'browser' ),
supportsLocalStorage = browser.supportsLocalStorage(),
settings = ( function () {
-
- function cookiesEnabled() {
- // If session cookie already set, return true
- if ( $.cookie( 'mf_testcookie' ) === 'test_value' ) {
- return true;
- // Otherwise try to set mf_testcookie and return true
if it was set
- } else {
- $.cookie( 'mf_testcookie', 'test_value', {
- path: '/'
- } );
- return $.cookie( 'mf_testcookie' ) ===
'test_value';
+ /**
+ * Checks whether cookies are enabled
+ * @returns {boolean}
+ */
+ function cookiesEnabled() {
+ // If session cookie already set, return true
+ if ( $.cookie( 'mf_testcookie' ) ===
'test_value' ) {
+ return true;
+ // Otherwise try to set mf_testcookie and
return true if it was set
+ } else {
+ $.cookie( 'mf_testcookie',
'test_value', {
+ path: '/'
+ } );
+ return $.cookie( 'mf_testcookie' ) ===
'test_value';
+ }
}
- }
- /**
- * Saves a user setting for a later browser settings via
localStorage
- *
- * @param {String} name The key to refer to this value
- * @param {String} value The value to store alongside the key
- * @param {Boolean} useCookieFallback Optional: When set this
will use cookies when local storage not available.
- * @returns {Boolean} Whether the save was successful or not
- */
- function save( name, value, useCookieFallback ) {
- var cookieOptions = {
- expires: 1
+ /**
+ * Saves a user setting for a later browser settings
via localStorage
+ *
+ * @param {String} name The key to refer to this value
+ * @param {String} value The value to store alongside
the key
+ * @param {Boolean} useCookieFallback Optional: When
set this will use cookies when local storage not available.
+ * @returns {Boolean} Whether the save was successful
or not
+ */
+ function save( name, value, useCookieFallback ) {
+ var cookieOptions = {
+ expires: 1
+ };
+ return supportsLocalStorage ?
+ localStorage.setItem( name, value ) :
+ ( useCookieFallback ? $.cookie(
name, value, cookieOptions ) : false );
+ }
+
+ /**
+ * Retrieves a user setting from a previous browser
setting
+ *
+ * @param {String} name The key to refer to this value
+ * @param {Boolean} useCookieFallback Optional: When
set this will use cookies when local storage not available.
+ * @returns {String|Boolean} Returns the associated
value or False if nothing is found
+ */
+ function get( name, useCookieFallback ) {
+ return supportsLocalStorage ?
localStorage.getItem( name ) :
+ ( useCookieFallback ? $.cookie( name )
: false );
+ }
+
+ /**
+ * Deletes a user setting from a previous browser
setting
+ *
+ * @param {String} name The key to refer to this value
+ * @param {Boolean} useCookieFallback Optional: When
set this will use cookies when local storage not available.
+ * @returns {Boolean} Whether the delete was successful
or not
+ */
+ function remove( name, useCookieFallback ) {
+ return supportsLocalStorage ?
localStorage.removeItem( name ) :
+ ( useCookieFallback ? $.removeCookie(
name ) : false );
+ }
+
+ return {
+ get: get,
+ save: save,
+ remove: remove,
+ cookiesEnabled: cookiesEnabled
};
- return supportsLocalStorage ?
- localStorage.setItem( name, value ) :
- ( useCookieFallback ? $.cookie( name,
value, cookieOptions ) : false );
- }
-
- /**
- * Retrieves a user setting from a previous browser setting
- *
- * @param {String} name The key to refer to this value
- * @param {Boolean} useCookieFallback Optional: When set this
will use cookies when local storage not available.
- * @returns {String|Boolean} Returns the associated value or
False if nothing is found
- */
- function get( name, useCookieFallback ) {
- return supportsLocalStorage ? localStorage.getItem(
name ) :
- ( useCookieFallback ? $.cookie( name ) : false
);
- }
-
- /**
- * Deletes a user setting from a previous browser setting
- *
- * @param {String} name The key to refer to this value
- * @param {Boolean} useCookieFallback Optional: When set this
will use cookies when local storage not available.
- * @returns {Boolean} Whether the delete was successful or not
- */
- function remove( name, useCookieFallback ) {
- return supportsLocalStorage ? localStorage.removeItem(
name ) :
- ( useCookieFallback ? $.removeCookie( name ) :
false );
- }
-
- return {
- get: get,
- save: save,
- remove: remove,
- cookiesEnabled: cookiesEnabled
- };
- }() );
+ }() );
M.define( 'settings', settings );
diff --git a/javascripts/specials/mobileoptions.js
b/javascripts/specials/mobileoptions.js
index 154e684..c09f0f5 100644
--- a/javascripts/specials/mobileoptions.js
+++ b/javascripts/specials/mobileoptions.js
@@ -22,6 +22,9 @@
}
} );
+ /**
+ * @method
+ */
function initLocalStorageCheckboxes() {
var cb,
saveLI = $( '#mw-mf-settings-save' );
diff --git a/javascripts/specials/notifications.js
b/javascripts/specials/notifications.js
index 9de685e..4b951bd 100644
--- a/javascripts/specials/notifications.js
+++ b/javascripts/specials/notifications.js
@@ -104,6 +104,12 @@
} ).fail( onError );
}
+ /**
+ * onSuccess callback
+ * @method
+ * @ignore
+ * @private
+ */
function onSuccess() {
if ( !notContinue ) {
$( '#mw-echo-more' ).hide();
@@ -111,6 +117,12 @@
processing = false;
}
+ /**
+ * onError callback
+ * @method
+ * @ignore
+ * @private
+ */
function onError() {
// TODO: Show detail error message based on error code
$( '#mw-echo-more' ).text( mw.msg( 'echo-load-more-error' ) );
diff --git a/javascripts/specials/uploads/PhotoList.js
b/javascripts/specials/uploads/PhotoList.js
index 85b350a..a8c8462 100644
--- a/javascripts/specials/uploads/PhotoList.js
+++ b/javascripts/specials/uploads/PhotoList.js
@@ -100,7 +100,8 @@
},
/**
* Load photos into the view using {{UserGalleryApi}} when the
end is near
- * and no current API requests are underway.
+ * and no current API requests are underway.
+ * @private
*/
_loadPhotos: function () {
var self = this;
diff --git a/javascripts/toast.js b/javascripts/toast.js
index 16a89d8..6ba1674 100644
--- a/javascripts/toast.js
+++ b/javascripts/toast.js
@@ -14,7 +14,7 @@
* Show the toast message with a given class and content
* @method
* @param {String} content Content to be placed in element
- * @param {String} className class to add to elemenet
+ * @param {String} className class to add to element
*/
show: function ( content, className ) {
this.$el
--
To view, visit https://gerrit.wikimedia.org/r/180661
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Id86740b89cd18c87d017653b8599b4e753eff110
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/extensions/MobileFrontend
Gerrit-Branch: master
Gerrit-Owner: Bmansurov <[email protected]>
_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
