jquery.client: Add jsduck documentation

Change-Id: Idd78fa72dcff46341cd55ba128ef24107d240c6b

diff --git a/maintenance/jsduck/categories.json b/maintenance/jsduck/categories.json
index eaf0a38..b1cefa3 100644 (file)
--- a/maintenance/jsduck/categories.json
+++ b/maintenance/jsduck/categories.json
@@ -73,7 +73,10 @@
                "groups": [
                        {
                                "name": "Plugins",
-                               "classes": ["jQuery.plugin.*"]
+                               "classes": [
+                                       "jQuery.client",
+                                       "jQuery.plugin.*"
+                               ]
                        }
                ]
        },

diff --git a/maintenance/jsduck/config.json b/maintenance/jsduck/config.json
index c473772..d0b3b3d 100644 (file)
--- a/maintenance/jsduck/config.json
+++ b/maintenance/jsduck/config.json
@@ -20,6 +20,7 @@
                "../../resources/src/jquery/jquery.autoEllipsis.js",
                "../../resources/src/jquery/jquery.badge.js",
                "../../resources/src/jquery/jquery.byteLimit.js",
+               "../../resources/src/jquery/jquery.client.js",
                "../../resources/src/jquery/jquery.localize.js",
                "../../resources/src/jquery/jquery.spinner.js",
                "../../resources/lib/oojs",

diff --git a/resources/src/jquery/jquery.client.js b/resources/src/jquery/jquery.client.js
index 6689b7c..662a688 100644 (file)
--- a/resources/src/jquery/jquery.client.js
+++ b/resources/src/jquery/jquery.client.js
@@ -1,35 +1,36 @@
 /**
  * User-agent detection
+ *
+ * @class jQuery.client
+ * @singleton
  */
 ( function ( $ ) {
 
-       /* Private Members */
-
        /**
-        * @var {Object} profileCache Keyed by userAgent string,
+        * @private
+        * @property {Object} profileCache Keyed by userAgent string,
         * value is the parsed $.client.profile object for that user agent.
         */
        var profileCache = {};
 
-       /* Public Methods */
-
        $.client = {
 
                /**
                 * Get an object containing information about the client.
                 *
-                * @param {Object} nav An object with atleast a 'userAgent' and 'platform' key.
-                * Defaults to the global Navigator object.
+                * @param {Object} [nav] An object with a 'userAgent' and 'platform' property.
+                *  Defaults to the global `navigator` object.
                 * @return {Object} The resulting client object will be in the following format:
-                *  {
-                *   'name': 'firefox',
-                *   'layout': 'gecko',
-                *   'layoutVersion': 20101026,
-                *   'platform': 'linux'
-                *   'version': '3.5.1',
-                *   'versionBase': '3',
-                *   'versionNumber': 3.5,
-                *  }
+                *
+                *     {
+                *         'name': 'firefox',
+                *         'layout': 'gecko',
+                *         'layoutVersion': 20101026,
+                *         'platform': 'linux'
+                *         'version': '3.5.1',
+                *         'versionBase': '3',
+                *         'versionNumber': 3.5,
+                *     }
                 */
                profile: function ( nav ) {
                        /*jshint boss: true */
@@ -47,7 +48,7 @@
                                versionNumber,
                                key = nav.userAgent + '|' + nav.platform,
 
-                               /* Configuration */
+                               // Configuration
 
                                // Name of browsers or layout engines we don't recognize
                                uk = 'unknown',
@@ -96,10 +97,9 @@
                                // Translations for conforming operating system names
                                platformTranslations = [ ['sunos', 'solaris'], ['wow64', 'win'] ],
 
-                               /* Methods */
-
                                /**
                                 * Performs multiple replacements on a string
+                                * @ignore
                                 */
                                translate = function ( source, translations ) {
                                        var i;
@@ -109,7 +109,7 @@
                                        return source;
                                },
 
-                               /* Pre-processing */
+                               // Pre-processing
 
                                ua = nav.userAgent,
                                match,
@@ -126,7 +126,7 @@
                        // Everything will be in lowercase from now on
                        ua = ua.toLowerCase();
 
-                       /* Extraction */
+                       // Extraction
 
                        if ( match = new RegExp( '(' + names.join( '|' ) + ')' ).exec( ua ) ) {
                                name = translate( match[1], nameTranslations );
@@ -144,7 +144,7 @@
                                version = match[3];
                        }
 
-                       /* Edge Cases -- did I mention about how user agent string lie? */
+                       // Edge Cases -- did I mention about how user agent string lie?
 
                        // Decode Safari's crazy 400+ version numbers
                        if ( name === 'safari' && version > 400 ) {
@@ -183,7 +183,7 @@
 
                        versionNumber = parseFloat( version, 10 ) || 0.0;
 
-                       /* Caching */
+                       // Caching
 
                        return profileCache[ key  ] = {
                                name: name,
@@ -204,27 +204,29 @@
                 * algorithm, similar to PHP's version_compare ('1.2' < '1.11').
                 *
                 * A browser map is in the following format:
-                * {
-                *   // Multiple rules with configurable operators
-                *   'msie': [['>=', 7], ['!=', 9]],
-                *    // Match no versions
-                *   'iphone': false,
-                *    // Match any version
-                *   'android': null
-                * }
+                *
+                *     {
+                *         // Multiple rules with configurable operators
+                *         'msie': [['>=', 7], ['!=', 9]],
+                *         // Match no versions
+                *         'iphone': false,
+                *         // Match any version
+                *         'android': null
+                *     }
                 *
                 * It can optionally be split into ltr/rtl sections:
-                * {
-                *   'ltr': {
-                *     'android': null,
-                *     'iphone': false
-                *   },
-                *   'rtl': {
-                *     'android': false,
-                *     // rules are not inherited from ltr
-                *     'iphone': false
-                *   }
-                * }
+                *
+                *     {
+                *         'ltr': {
+                *             'android': null,
+                *             'iphone': false
+                *         },
+                *         'rtl': {
+                *             'android': false,
+                *             // rules are not inherited from ltr
+                *             'iphone': false
+                *         }
+                *     }
                 *
                 * @param {Object} map Browser support map
                 * @param {Object} [profile] A client-profile object