From: Timo Tijhof <krinklemail@gmail.com>
Date: Sun, 27 Apr 2014 13:37:28 +0000 (+0200)
Subject: jquery.client: Add jsduck documentation
X-Git-Tag: 1.31.0-rc.0~15988
X-Git-Url: http://git.cyclocoop.org/%24image?a=commitdiff_plain;h=686739bc9340dd50949da560c08b739d9d42ec04;p=lhc%2Fweb%2Fwiklou.git

jquery.client: Add jsduck documentation

Change-Id: Idd78fa72dcff46341cd55ba128ef24107d240c6b
---

diff --git a/maintenance/jsduck/categories.json b/maintenance/jsduck/categories.json
index eaf0a38530..b1cefa3142 100644
--- 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 c47377266d..d0b3b3d9da 100644
--- 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 6689b7cb3c..662a688755 100644
--- 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