Bartosz Dziewoński has uploaded a new change for review.
https://gerrit.wikimedia.org/r/98380
Change subject: JSDuck-ify /resources/mediawiki.language/*
......................................................................
JSDuck-ify /resources/mediawiki.language/*
* Removed some pieces of "documentation" I couldn't make any sense of. :)
* Marked some methods which looked internal as @private.
* Empirically tested and added some @return value types.
* Fixed format of doc comments to conform to JSDuck standards.
* Added entries to categories.json and config.json.
Change-Id: Ie60f72a5f277d846c09226d5af3da16b07f038c3
---
M maintenance/jsduck/categories.json
M maintenance/jsduck/config.json
M resources/mediawiki.language/mediawiki.cldr.js
M resources/mediawiki.language/mediawiki.language.init.js
M resources/mediawiki.language/mediawiki.language.js
M resources/mediawiki.language/mediawiki.language.months.js
M resources/mediawiki.language/mediawiki.language.numbers.js
7 files changed, 161 insertions(+), 117 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/core
refs/changes/80/98380/1
diff --git a/maintenance/jsduck/categories.json
b/maintenance/jsduck/categories.json
index c595980..fb38eab 100644
--- a/maintenance/jsduck/categories.json
+++ b/maintenance/jsduck/categories.json
@@ -36,6 +36,13 @@
{
"name": "API",
"classes": ["mw.Api*"]
+ },
+ {
+ "name": "Language",
+ "classes": [
+ "mw.language*",
+ "mw.cldr"
+ ]
}
]
},
diff --git a/maintenance/jsduck/config.json b/maintenance/jsduck/config.json
index e6e0f65..cf0190f 100644
--- a/maintenance/jsduck/config.json
+++ b/maintenance/jsduck/config.json
@@ -21,6 +21,11 @@
"../../resources/mediawiki.action/mediawiki.action.view.postEdit.js",
"../../resources/mediawiki.page/mediawiki.page.startup.js",
"../../resources/mediawiki.api",
+ "../../resources/mediawiki.language/mediawiki.cldr.js",
+ "../../resources/mediawiki.language/mediawiki.language.init.js",
+ "../../resources/mediawiki.language/mediawiki.language.js",
+
"../../resources/mediawiki.language/mediawiki.language.months.js",
+
"../../resources/mediawiki.language/mediawiki.language.numbers.js",
"../../resources/jquery/jquery.localize.js",
"../../resources/jquery/jquery.spinner.js"
]
diff --git a/resources/mediawiki.language/mediawiki.cldr.js
b/resources/mediawiki.language/mediawiki.cldr.js
index c3023cd..ecd62c5 100644
--- a/resources/mediawiki.language/mediawiki.cldr.js
+++ b/resources/mediawiki.language/mediawiki.cldr.js
@@ -1,15 +1,20 @@
-/**
- * CLDR related utility methods.
- */
( function ( mw ) {
'use strict';
- var cldr = {
+ /**
+ * Namespace for CLDR-related utility methods.
+ *
+ * @class
+ * @static
+ */
+ mw.cldr = {
/**
- * For the number, get the plural for index
- * In case none of the rules passed, we return
pluralRules.length
- * That means it is the "other" form.
- * @param number
+ * Get the plural form index for the number.
+ *
+ * In case none of the rules passed, we return
`pluralRules.length` -
+ * that means it is the "other" form.
+ *
+ * @param {number} number
* @param {Array} pluralRules
* @return {number} plural form index
*/
@@ -23,7 +28,5 @@
return i;
}
};
-
- mw.cldr = cldr;
}( mediaWiki ) );
diff --git a/resources/mediawiki.language/mediawiki.language.init.js
b/resources/mediawiki.language/mediawiki.language.init.js
index 937b89b..d88b6e2 100644
--- a/resources/mediawiki.language/mediawiki.language.init.js
+++ b/resources/mediawiki.language/mediawiki.language.init.js
@@ -1,35 +1,47 @@
-/**
- * Base language object with methods for storing and getting
- * language data.
- */
( function ( mw ) {
-
- var language = {
+ /**
+ * Base language object with methods for storing and getting
+ * language data.
+ *
+ * @class mw.language
+ */
+ var language = mw.language = {
/**
- * @var data {Object} Language related data (keyed by language,
- * contains instances of mw.Map).
- * @example Set data
- * <code>
+ * Language-related data (keyed by language, contains instances
of mw.Map). Loaded dynamically
+ * (see ResourceLoaderLanguageDataModule in PHP docs, aka
mediawiki.language.data module).
+ *
+ * To set data:
+ *
* // Override, extend or create the language data object
of 'nl'
* mw.language.setData( 'nl', 'myKey', 'My value' );
*
* // Set multiple values at once
- * mw.language.setData( 'nl', { 'foo': 'X', 'bar': 'Y' } );
- * </code>
- * @example Get GrammarForms data for language 'nl':
- * <code>
+ * mw.language.setData( 'nl', { foo: 'X', bar: 'Y' } );
+ *
+ * To get GrammarForms data for language 'nl':
+ *
* var grammarForms = mw.language.getData( 'nl',
'grammarForms' );
- * </code>
+ *
+ * Possible data keys:
+ *
+ * - `digitTransformTable`
+ * - `separatorTransformTable`
+ * - `grammarForms`
+ * - `pluralRules`
+ * - `digitGroupingPattern`
+ *
+ * @property {Object} data
*/
data: {},
/**
- * Convenience method for retreiving language data by language
code and data key,
- * covering for the potential inexistance of a data object for
this langiage.
- * @param langCode {String}
- * @param dataKey {String}
- * @return {mixed} Value stored in the mw.Map (or undefined if
there is no map for
- the specified langCode).
+ * Convenience method for retrieving language data by language
code and data key,
+ * covering for the potential inexistence of a data object for
this language.
+ *
+ * @param {string} langCode
+ * @param {string} dataKey
+ * @return Value stored in the mw.Map (or `undefined` if there
is no map for the specified
+ * langCode).
*/
getData: function ( langCode, dataKey ) {
var langData = language.data;
@@ -43,9 +55,9 @@
* Convenience method for setting language data by language
code and data key.
* Creates the data mw.Map if there isn't one for the specified
language already.
*
- * @param langCode {String}
- * @param dataKey {String|Object} Key or object of key/values.
- * @param value {mixed} Value for dataKey, ignored if dataKey
is an object.
+ * @param {string} langCode
+ * @param {string|Object} dataKey Key or object of key/values.
+ * @param value Value for dataKey, ignored if dataKey is an
object.
*/
setData: function ( langCode, dataKey, value ) {
var langData = language.data;
@@ -55,7 +67,5 @@
langData[langCode].set( dataKey, value );
}
};
-
- mw.language = language;
}( mediaWiki ) );
diff --git a/resources/mediawiki.language/mediawiki.language.js
b/resources/mediawiki.language/mediawiki.language.js
index 631d13d..971ca9e 100644
--- a/resources/mediawiki.language/mediawiki.language.js
+++ b/resources/mediawiki.language/mediawiki.language.js
@@ -1,22 +1,23 @@
+( function ( mw, $ ) {
+
/**
* Localized Language support attempts to mirror some of the functionality of
* Language.php in MediaWiki.
+ *
* This adds methods for transforming message text.
+ *
+ * @class mw.language
*/
-( function ( mw, $ ) {
-
-var language = {
+$.extend( mw.language, {
/**
* Process the PLURAL template substitution
*
- * @param {object} template Template object
- * @format template
- * {
- * 'title': [title of template],
- * 'parameters': [template parameters]
- * }
- * @example {{Template:title|params}}
+ * @param {Object} template Template object
+ * @param {string} template.title
+ * @param {Array} template.parameters
+ * @return {string}
+ * @private
*/
procPLURAL: function ( template ) {
if ( template.title && template.parameters &&
mw.language.convertPlural ) {
@@ -39,9 +40,9 @@
/**
* Plural form transformations, needed for some languages.
*
- * @param count integer Non-localized quantifier
- * @param forms array List of plural forms
- * @return string Correct form for quantifier in this language
+ * @param {number} count Non-localized quantifier
+ * @param {Array} forms List of plural forms
+ * @return {string} Correct form for quantifier in this language
*/
convertPlural: function ( count, forms ) {
var pluralRules,
@@ -86,9 +87,10 @@
/**
* Pads an array to a specific length by copying the last one element.
*
- * @param forms array Number of forms given to convertPlural
- * @param count integer Number of forms required
- * @return array Padded array of forms
+ * @param {Array} forms Number of forms given to convertPlural
+ * @param {number} count Number of forms required
+ * @return {Array} Padded array of forms
+ * @private
*/
preConvertPlural: function ( forms, count ) {
while ( forms.length < count ) {
@@ -99,14 +101,13 @@
/**
* Provides an alternative text depending on specified gender.
- * Usage {{gender:[gender|user object]|masculine|feminine|neutral}}.
+ * Usage in message text: `{{gender:[gender|user
object]|masculine|feminine|neutral}}`.
* If second or third parameter are not specified, masculine is used.
*
* These details may be overriden per language.
*
- * @param gender string male, female, or anything else for neutral.
- * @param forms array List of gender forms
- *
+ * @param {string} gender 'male', 'female', or anything else for
neutral.
+ * @param {Array} forms List of gender forms
* @return string
*/
gender: function ( gender, forms ) {
@@ -125,13 +126,14 @@
/**
* Grammatical transformations, needed for inflected languages.
- * Invoked by putting {{grammar:form|word}} in a message.
- * The rules can be defined in $wgGrammarForms global or grammar
- * forms can be computed dynamically by overriding this method per
language
+ * Invoked by putting `{{grammar:form|word}}` in a message.
*
- * @param word {String}
- * @param form {String}
- * @return {String}
+ * The rules can be defined in $wgGrammarForms global or computed
+ * dynamically by overriding this method per language.
+ *
+ * @param {string} word
+ * @param {string} form
+ * @return {string}
*/
convertGrammar: function ( word, form ) {
var grammarForms = mw.language.getData( mw.config.get(
'wgUserLanguage' ), 'grammarForms' );
@@ -141,8 +143,6 @@
return word;
}
-};
-
-$.extend( mw.language, language );
+} );
}( mediaWiki, jQuery ) );
diff --git a/resources/mediawiki.language/mediawiki.language.months.js
b/resources/mediawiki.language/mediawiki.language.months.js
index 3d4b7ee..bdeebc5 100644
--- a/resources/mediawiki.language/mediawiki.language.months.js
+++ b/resources/mediawiki.language/mediawiki.language.months.js
@@ -1,8 +1,3 @@
-/**
- * Transfer of month names from messages into mw.language.
- *
- * Loading this module also ensures the availability of appropriate messages
via mw.msg.
- */
( function ( mw, $ ) {
var
monthMessages = [
@@ -28,27 +23,37 @@
}
/**
- * Information about month names in current UI language.
+ * Transfer of month names from messages into mw.language.
*
- * Object keys:
- * - `names`: array of month names (in nominative case in languages
which have the distinction),
- * zero-indexed
- * - `genitive`: array of month names in genitive case, zero-indexed
- * - `abbrev`: array of three-letter-long abbreviated month names,
zero-indexed
- * - `keys`: object with three keys like the above, containing
zero-indexed arrays of message keys
- * for appropriate messages which can be passed to mw.msg.
+ * Loading this module also ensures the availability of appropriate
messages via mw.msg.
*
- * @property
+ * @class mw.language
*/
- mw.language.months = {
- keys: {
- names: monthMessages,
- genitive: monthGenMessages,
- abbrev: monthAbbrevMessages
- },
- names: $.map( monthMessages, mwMsgMapper ),
- genitive: $.map( monthGenMessages, mwMsgMapper ),
- abbrev: $.map( monthAbbrevMessages, mwMsgMapper )
- };
+ $.extend( mw.language, {
+ /**
+ * Information about month names in current UI language.
+ *
+ * Object keys:
+ *
+ * - `names`: array of month names (in nominative case in
languages which have the distinction),
+ * zero-indexed
+ * - `genitive`: array of month names in genitive case,
zero-indexed
+ * - `abbrev`: array of three-letter-long abbreviated month
names, zero-indexed
+ * - `keys`: object with three keys like the above, containing
zero-indexed arrays of message keys
+ * for appropriate messages which can be passed to mw.msg.
+ *
+ * @property
+ */
+ months: {
+ keys: {
+ names: monthMessages,
+ genitive: monthGenMessages,
+ abbrev: monthAbbrevMessages
+ },
+ names: $.map( monthMessages, mwMsgMapper ),
+ genitive: $.map( monthGenMessages, mwMsgMapper ),
+ abbrev: $.map( monthAbbrevMessages, mwMsgMapper )
+ }
+ } );
}( mediaWiki, jQuery ) );
diff --git a/resources/mediawiki.language/mediawiki.language.numbers.js
b/resources/mediawiki.language/mediawiki.language.numbers.js
index fada6ce..62fab34 100644
--- a/resources/mediawiki.language/mediawiki.language.numbers.js
+++ b/resources/mediawiki.language/mediawiki.language.numbers.js
@@ -1,23 +1,22 @@
-/*
- * Number related utilities for mediawiki.language
- */
( function ( mw, $ ) {
- /**
+ /*
* Pad a string to guarantee that it is at least `size` length by
* filling with the character `ch` at either the start or end of the
* string. Pads at the start, by default.
- * example:
- * Fill the string to length 10 with '+' characters on the right.
Yields 'blah++++++'.
- * pad('blah', 10, '+', true);
+ *
+ * Example: Fill the string to length 10 with '+' characters on the
right.
+ *
+ * pad('blah', 10, '+', true); // => 'blah++++++'
*
* @param {string} text The string to pad
- * @param {Number} size To provide padding
- * @param {string} ch Character to pad, defaults to '0'
- * @param {Boolean} end Adds padding at the end if true, otherwise pads
at start
+ * @param {number} size The length to pad to
+ * @param {string} [ch='0'] Character to pad with
+ * @param {boolean} [end=false] Adds padding at the end if true,
otherwise pads at start
* @return {string}
+ * @private
*/
- function pad ( text, size, ch, end ) {
+ function pad( text, size, ch, end ) {
if ( !ch ) {
ch = '0';
}
@@ -28,14 +27,15 @@
return end ? out + padStr : padStr + out;
}
- /**
- * Efficiently replicate a string n times.
+ /*
+ * Efficiently replicate a string `n` times.
*
* @param {string} str The string to replicate
- * @param {Number} num Number of times to replicate the string
+ * @param {number} num Number of times to replicate the string
* @return {string}
+ * @private
*/
- function replicate ( str, num ) {
+ function replicate( str, num ) {
if ( num <= 0 || !str ) {
return '';
}
@@ -48,19 +48,20 @@
return buf.join( '' );
}
- /**
+ /*
* Apply numeric pattern to absolute value using options. Gives no
* consideration to local customs.
*
* Adapted from dojo/number library with thanks
* http://dojotoolkit.org/reference-guide/1.8/dojo/number.html
*
- * @param {Number} value the number to be formatted, ignores sign
+ * @param {number} value the number to be formatted, ignores sign
* @param {string} pattern the number portion of a pattern (e.g.
`#,##0.00`)
- * @param {string} options.decimalThe decimal separator
+ * @param {Object} [options]
+ * @param {string} options.decimal The decimal separator
* @param {string} options.group The group separator
- *
* @return {string}
+ * @private
*/
function commafyNumber( value, pattern, options ) {
options = options || {
@@ -149,14 +150,19 @@
return valueParts.join( options.decimal );
}
+ /**
+ * Number-related utilities for mediawiki.language.
+ *
+ * @class mw.language
+ */
$.extend( mw.language, {
/**
- * Converts a number using digitTransformTable.
+ * Converts a number using #getDigitTransformTable.
*
- * @param {Number} num Value to be converted
- * @param {boolean} integer Convert the return value to an
integer
- * @return {Number|string} Formatted number
+ * @param {number} num Value to be converted
+ * @param {boolean} [integer=false] Whether to convert the
return value to an integer
+ * @return {number|string} Formatted number
*/
convertNumber: function ( num, integer ) {
var i, tmp, transformTable, numberString,
convertedNumber, pattern;
@@ -197,24 +203,32 @@
return integer ? parseInt( convertedNumber, 10 ) :
convertedNumber;
},
+ /**
+ * Returns a digit transform table for current UI language.
+ * @return {Object|Array|undefined}
+ */
getDigitTransformTable: function () {
return mw.language.getData( mw.config.get(
'wgUserLanguage' ),
'digitTransformTable' ) || [];
},
+ /**
+ * Returns a separator transform table for current UI language.
+ * @return {Object|Array|undefined}
+ */
getSeparatorTransformTable: function () {
return mw.language.getData( mw.config.get(
'wgUserLanguage' ),
'separatorTransformTable' ) || [];
},
/**
- * Apply pattern to format value as a string using as per
- * unicode.org TR35 -
http://www.unicode.org/reports/tr35/#Number_Format_Patterns.
+ * Apply pattern to format value as a string using as per
Unicode TR35
+ *
(http://www.unicode.org/reports/tr35/#Number_Format_Patterns).
*
- * @param {Number} value
+ * @param {number} value
* @param {string} pattern Pattern string as described by
Unicode TR35
- * @throws Error
- * @returns {String}
+ * @throws {Error}
+ * @return {string}
*/
commafy: function ( value, pattern ) {
var numberPattern,
--
To view, visit https://gerrit.wikimedia.org/r/98380
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ie60f72a5f277d846c09226d5af3da16b07f038c3
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/core
Gerrit-Branch: master
Gerrit-Owner: Bartosz Dziewoński <matma....@gmail.com>
_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
