From 1af99f624d53b2a6bf5215da3e478372e02e8460 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Bartosz=20Dziewo=C5=84ski?= Date: Sun, 22 Dec 2013 01:38:19 +0100 Subject: [PATCH] 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. Also fixed jqueryMsg tests which depended on implementation details and overwriting singleton classes and thus started failing now. I have no idea what these hacks were for since the tests pass after just removing them. Change-Id: Ie60f72a5f277d846c09226d5af3da16b07f038c3 --- maintenance/jsduck/categories.json | 7 ++ maintenance/jsduck/config.json | 1 + resources/mediawiki.language/languages/bs.js | 2 +- resources/mediawiki.language/languages/dsb.js | 2 +- resources/mediawiki.language/languages/fi.js | 6 +- resources/mediawiki.language/languages/ga.js | 2 +- resources/mediawiki.language/languages/he.js | 2 +- resources/mediawiki.language/languages/hsb.js | 2 +- resources/mediawiki.language/languages/hu.js | 6 +- resources/mediawiki.language/languages/hy.js | 2 +- resources/mediawiki.language/languages/la.js | 2 +- resources/mediawiki.language/languages/os.js | 3 +- resources/mediawiki.language/languages/ru.js | 2 +- resources/mediawiki.language/languages/sl.js | 2 +- resources/mediawiki.language/languages/uk.js | 2 +- .../mediawiki.language/mediawiki.cldr.js | 23 +++--- .../mediawiki.language.init.js | 76 ++++++++++++------- .../mediawiki.language/mediawiki.language.js | 61 ++++++++------- .../mediawiki.language.months.js | 4 +- .../mediawiki.language.numbers.js | 64 ++++++++++------ .../mediawiki/mediawiki.jqueryMsg.test.js | 5 +- 21 files changed, 160 insertions(+), 116 deletions(-) diff --git a/maintenance/jsduck/categories.json b/maintenance/jsduck/categories.json index c595980515..fb38eab037 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 e6e0f65875..d65d5e731d 100644 --- a/maintenance/jsduck/config.json +++ b/maintenance/jsduck/config.json @@ -21,6 +21,7 @@ "../../resources/mediawiki.action/mediawiki.action.view.postEdit.js", "../../resources/mediawiki.page/mediawiki.page.startup.js", "../../resources/mediawiki.api", + "../../resources/mediawiki.language", "../../resources/jquery/jquery.localize.js", "../../resources/jquery/jquery.spinner.js" ] diff --git a/resources/mediawiki.language/languages/bs.js b/resources/mediawiki.language/languages/bs.js index 65eb5a6da7..b56e4b29fd 100644 --- a/resources/mediawiki.language/languages/bs.js +++ b/resources/mediawiki.language/languages/bs.js @@ -1,4 +1,4 @@ -/** +/*! * Bosnian (bosanski) language functions */ diff --git a/resources/mediawiki.language/languages/dsb.js b/resources/mediawiki.language/languages/dsb.js index b2c9c081f3..69c36cc02f 100644 --- a/resources/mediawiki.language/languages/dsb.js +++ b/resources/mediawiki.language/languages/dsb.js @@ -1,4 +1,4 @@ -/** +/*! * Lower Sorbian (Dolnoserbski) language functions */ diff --git a/resources/mediawiki.language/languages/fi.js b/resources/mediawiki.language/languages/fi.js index 61c6c104e1..2410091bf1 100644 --- a/resources/mediawiki.language/languages/fi.js +++ b/resources/mediawiki.language/languages/fi.js @@ -1,6 +1,6 @@ -/** - * Finnish (Suomi) language functions - * @author Santhosh Thottingal +/*! + * Finnish (Suomi) language functions + * @author Santhosh Thottingal */ mediaWiki.language.convertGrammar = function ( word, form ) { diff --git a/resources/mediawiki.language/languages/ga.js b/resources/mediawiki.language/languages/ga.js index c13e8321c4..fb4e939655 100644 --- a/resources/mediawiki.language/languages/ga.js +++ b/resources/mediawiki.language/languages/ga.js @@ -1,4 +1,4 @@ -/** +/*! * Irish (Gaeilge) language functions */ diff --git a/resources/mediawiki.language/languages/he.js b/resources/mediawiki.language/languages/he.js index 13d457b26e..c7e9bd93f8 100644 --- a/resources/mediawiki.language/languages/he.js +++ b/resources/mediawiki.language/languages/he.js @@ -1,4 +1,4 @@ -/** +/*! * Hebrew (עברית) language functions */ diff --git a/resources/mediawiki.language/languages/hsb.js b/resources/mediawiki.language/languages/hsb.js index 77dca75e28..2d6b733ebd 100644 --- a/resources/mediawiki.language/languages/hsb.js +++ b/resources/mediawiki.language/languages/hsb.js @@ -1,4 +1,4 @@ -/** +/*! * Upper Sorbian (Hornjoserbsce) language functions */ diff --git a/resources/mediawiki.language/languages/hu.js b/resources/mediawiki.language/languages/hu.js index 23b0c12553..d72a1c05b4 100644 --- a/resources/mediawiki.language/languages/hu.js +++ b/resources/mediawiki.language/languages/hu.js @@ -1,6 +1,6 @@ -/** - * Hungarian language functions - * @author Santhosh Thottingal +/*! + * Hungarian language functions + * @author Santhosh Thottingal */ mediaWiki.language.convertGrammar = function ( word, form ) { diff --git a/resources/mediawiki.language/languages/hy.js b/resources/mediawiki.language/languages/hy.js index 65081bdde1..d1ed041bd1 100644 --- a/resources/mediawiki.language/languages/hy.js +++ b/resources/mediawiki.language/languages/hy.js @@ -1,4 +1,4 @@ -/** +/*! * Armenian (Հայերեն) language functions */ diff --git a/resources/mediawiki.language/languages/la.js b/resources/mediawiki.language/languages/la.js index 27110241f7..7fc171df9f 100644 --- a/resources/mediawiki.language/languages/la.js +++ b/resources/mediawiki.language/languages/la.js @@ -1,4 +1,4 @@ -/** +/*! * Latin (lingua Latina) language functions * @author Santhosh Thottingal */ diff --git a/resources/mediawiki.language/languages/os.js b/resources/mediawiki.language/languages/os.js index 682b390311..4b508346c4 100644 --- a/resources/mediawiki.language/languages/os.js +++ b/resources/mediawiki.language/languages/os.js @@ -1,9 +1,8 @@ -/** +/*! * Ossetian (Ирон) language functions * @author Santhosh Thottingal */ - mediaWiki.language.convertGrammar = function ( word, form ) { var grammarForms = mediaWiki.language.getData( 'os', 'grammarForms' ), // Ending for allative case diff --git a/resources/mediawiki.language/languages/ru.js b/resources/mediawiki.language/languages/ru.js index 1bc063262a..e66b9cdeec 100644 --- a/resources/mediawiki.language/languages/ru.js +++ b/resources/mediawiki.language/languages/ru.js @@ -1,4 +1,4 @@ -/** +/*! * Russian (Русский) language functions */ diff --git a/resources/mediawiki.language/languages/sl.js b/resources/mediawiki.language/languages/sl.js index fb335b6a70..d20d0b3418 100644 --- a/resources/mediawiki.language/languages/sl.js +++ b/resources/mediawiki.language/languages/sl.js @@ -1,4 +1,4 @@ -/** +/*! * Slovenian (Slovenščina) language functions */ diff --git a/resources/mediawiki.language/languages/uk.js b/resources/mediawiki.language/languages/uk.js index 5e56b66f31..9b63382138 100644 --- a/resources/mediawiki.language/languages/uk.js +++ b/resources/mediawiki.language/languages/uk.js @@ -1,4 +1,4 @@ -/** +/*! * Ukrainian (Українська) language functions */ diff --git a/resources/mediawiki.language/mediawiki.cldr.js b/resources/mediawiki.language/mediawiki.cldr.js index c3023cd5a0..f6fb8f1079 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 + * @singleton + */ + 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 */ @@ -24,6 +29,4 @@ } }; - mw.cldr = cldr; - }( mediaWiki ) ); diff --git a/resources/mediawiki.language/mediawiki.language.init.js b/resources/mediawiki.language/mediawiki.language.init.js index 937b89bb17..fd77025b07 100644 --- a/resources/mediawiki.language/mediawiki.language.init.js +++ b/resources/mediawiki.language/mediawiki.language.init.js @@ -1,38 +1,57 @@ -/** - * Base language object with methods for storing and getting - * language data. - */ ( function ( mw ) { - - var language = { + /** + * Base language object with methods related to language support, attempting to mirror some of the + * functionality of the Language class in MediaWiki: + * + * - storing and retrieving language data + * - transforming message syntax (`{{PLURAL:}}`, `{{GRAMMAR:}}`, `{{GENDER:}}`) + * - formatting numbers + * + * @class + * @singleton + */ + mw.language = { /** - * @var data {Object} Language related data (keyed by language, - * contains instances of mw.Map). - * @example Set data - * + * 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' } ); - * - * @example Get GrammarForms data for language 'nl': - * + * mw.language.setData( 'nl', { foo: 'X', bar: 'Y' } ); + * + * To get GrammarForms data for language 'nl': + * * var grammarForms = mw.language.getData( 'nl', 'grammarForms' ); - * + * + * Possible data keys: + * + * - `digitTransformTable` + * - `separatorTransformTable` + * - `grammarForms` + * - `pluralRules` + * - `digitGroupingPattern` + * + * @property */ 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. + * + * Structured 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 {Mixed} 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; + var langData = mw.language.data; if ( langData && langData[langCode] instanceof mw.Map ) { return langData[langCode].get( dataKey ); } @@ -40,15 +59,16 @@ }, /** - * Convenience method for setting language data by language code and data key. + * Convenience method for setting language data. + * * 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 {Mixed} value Value for dataKey, ignored if dataKey is an object. */ setData: function ( langCode, dataKey, value ) { - var langData = language.data; + var langData = mw.language.data; if ( !( langData[langCode] instanceof mw.Map ) ) { langData[langCode] = new mw.Map(); } @@ -56,6 +76,4 @@ } }; - mw.language = language; - }( mediaWiki ) ); diff --git a/resources/mediawiki.language/mediawiki.language.js b/resources/mediawiki.language/mediawiki.language.js index 3927f00fca..87018f6d60 100644 --- a/resources/mediawiki.language/mediawiki.language.js +++ b/resources/mediawiki.language/mediawiki.language.js @@ -1,22 +1,21 @@ -/** - * Localized Language support attempts to mirror some of the functionality of - * Language.php in MediaWiki. - * This adds methods for transforming message text. +/* + * Methods for transforming message syntax. */ ( function ( mw, $ ) { -var language = { +/** + * @class mw.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}} + * @private + * @param {Object} template Template object + * @param {string} template.title + * @param {Array} template.parameters + * @return {string} */ procPLURAL: function ( template ) { if ( template.title && template.parameters && mw.language.convertPlural ) { @@ -39,9 +38,9 @@ var language = { /** * 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, @@ -90,9 +89,10 @@ var language = { /** * 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 + * @private + * @param {Array} forms Number of forms given to convertPlural + * @param {number} count Number of forms required + * @return {Array} Padded array of forms */ preConvertPlural: function ( forms, count ) { while ( forms.length < count ) { @@ -103,14 +103,14 @@ var language = { /** * 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 ) { @@ -129,13 +129,14 @@ var language = { /** * 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. + * + * The rules can be defined in $wgGrammarForms global or computed + * dynamically by overriding this method per language. * - * @param word {String} - * @param form {String} - * @return {String} + * @param {string} word + * @param {string} form + * @return {string} */ convertGrammar: function ( word, form ) { var grammarForms = mw.language.getData( mw.config.get( 'wgUserLanguage' ), 'grammarForms' ); @@ -145,8 +146,6 @@ var language = { 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 3d4b7ee783..5a1a5cb64a 100644 --- a/resources/mediawiki.language/mediawiki.language.months.js +++ b/resources/mediawiki.language/mediawiki.language.months.js @@ -1,4 +1,4 @@ -/** +/* * Transfer of month names from messages into mw.language. * * Loading this module also ensures the availability of appropriate messages via mw.msg. @@ -31,6 +31,7 @@ * 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 @@ -39,6 +40,7 @@ * for appropriate messages which can be passed to mw.msg. * * @property + * @member mw.language */ mw.language.months = { keys: { diff --git a/resources/mediawiki.language/mediawiki.language.numbers.js b/resources/mediawiki.language/mediawiki.language.numbers.js index fada6ce159..4282a3ddb1 100644 --- a/resources/mediawiki.language/mediawiki.language.numbers.js +++ b/resources/mediawiki.language/mediawiki.language.numbers.js @@ -1,23 +1,28 @@ /* - * Number related utilities for mediawiki.language + * Number-related utilities for mediawiki.language. */ ( function ( mw, $ ) { + /** + * @class mw.language + */ /** * 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++++++' + * + * @private * @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} */ - function pad ( text, size, ch, end ) { + function pad( text, size, ch, end ) { if ( !ch ) { ch = '0'; } @@ -29,13 +34,14 @@ } /** - * Efficiently replicate a string n times. + * Efficiently replicate a string `n` times. * + * @private * @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} */ - function replicate ( str, num ) { + function replicate( str, num ) { if ( num <= 0 || !str ) { return ''; } @@ -55,11 +61,12 @@ * 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 + * @private + * @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 {string} options.group The group separator - * + * @param {Object} [options] If provided, both option keys must be present: + * @param {string} options.decimal The decimal separator. Defaults to: `'.'`. + * @param {string} options.group The group separator. Defaults to: `','`. * @return {string} */ function commafyNumber( value, pattern, options ) { @@ -152,11 +159,11 @@ $.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 +204,33 @@ return integer ? parseInt( convertedNumber, 10 ) : convertedNumber; }, + /** + * Get the digit transform table for current UI language. + * @return {Object|Array} + */ getDigitTransformTable: function () { return mw.language.getData( mw.config.get( 'wgUserLanguage' ), 'digitTransformTable' ) || []; }, + /** + * Get the separator transform table for current UI language. + * @return {Object|Array} + */ 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 patterns from [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} If unable to find a number expression in `pattern`. + * @return {string} */ commafy: function ( value, pattern ) { var numberPattern, diff --git a/tests/qunit/suites/resources/mediawiki/mediawiki.jqueryMsg.test.js b/tests/qunit/suites/resources/mediawiki/mediawiki.jqueryMsg.test.js index 90cd546425..6e13e13601 100644 --- a/tests/qunit/suites/resources/mediawiki/mediawiki.jqueryMsg.test.js +++ b/tests/qunit/suites/resources/mediawiki/mediawiki.jqueryMsg.test.js @@ -10,8 +10,7 @@ QUnit.module( 'mediawiki.jqueryMsg', QUnit.newMwEnvironment( { setup: function () { - this.orgMwLangauge = mw.language; - mw.language = $.extend( true, {}, this.orgMwLangauge ); + this.originalMwLanguage = mw.language; // Messages that are reused in multiple tests mw.messages.set( { @@ -55,7 +54,7 @@ } ); }, teardown: function () { - mw.language = this.orgMwLangauge; + mw.language = this.originalMwLanguage; } } ) ); -- 2.20.1