From f341e3601111c12ab7fe55634864611f7f3fa22c Mon Sep 17 00:00:00 2001
From: Timo Tijhof <krinklemail@gmail.com>
Date: Mon, 24 Jun 2013 16:35:29 -0700
Subject: [PATCH] doc: Improve documentation for mw.Map and mw#config

* Link to the list on mediawiki.org
* Document it as type mw.Map instead of implied from code (= null)
  the fact that the literal code in mediawiki.js is a placeholder
  is an implementation detail that shouldn't be in the API docs.
* Add example for mw.Map.

Change-Id: I5c3ff272e605ee3825320f27aec32a4b4bf18ee2
---
 resources/mediawiki/mediawiki.js | 44 +++++++++++++++++++++++++++-----
 1 file changed, 38 insertions(+), 6 deletions(-)

diff --git a/resources/mediawiki/mediawiki.js b/resources/mediawiki/mediawiki.js
index 8409d456c4..51a4be50c6 100644
--- a/resources/mediawiki/mediawiki.js
+++ b/resources/mediawiki/mediawiki.js
@@ -15,10 +15,38 @@ var mw = ( function ( $, undefined ) {
 	/**
 	 * Creates an object that can be read from or written to from prototype functions
 	 * that allow both single and multiple variables at once.
+	 *
+	 *     @example
+	 *
+	 *     var addies, wanted, results;
+	 *
+	 *     // Create your address book
+	 *     addies = new mw.Map();
+	 *
+	 *     // This data could be coming from an external source (eg. API/AJAX)
+	 *     addies.set( {
+	 *         'John Doe' : '10 Wall Street, New York, USA',
+	 *         'Jane Jackson' : '21 Oxford St, London, UK',
+	 *         'Dominique van Halen' : 'Kalverstraat 7, Amsterdam, NL'
+	 *     } );
+	 *
+	 *     wanted = ['Dominique van Halen', 'George Johnson', 'Jane Jackson'];
+	 *
+	 *     // You can detect missing keys first
+	 *     if ( !addies.exists( wanted ) ) {
+	 *         // One ore more are missing (e.g. George Johson)
+	 *         mw.log( 'One or more names do not have a known address' );
+	 *     }
+	 *
+	 *     // Or just let it give you what it can
+	 *     results = addies.get( wanted, 'Middle of Nowhere, Alaska, US' );
+	 *     mw.log( results['Jane Jackson'] ); // "21 Oxford St, London, UK"
+	 *     mw.log( results['George Johnson'] ); // "Middle of Nowhere, Alaska, US"
+	 *
 	 * @class mw.Map
 	 *
 	 * @constructor
-	 * @param {boolean} global Whether to store the values in the global window
+	 * @param {boolean} [global=false] Whether to store the values in the global window
 	 *  object or a exclusively in the object property 'values'.
 	 */
 	function Map( global ) {
@@ -288,13 +316,17 @@ var mw = ( function ( $, undefined ) {
 		Message: Message,
 
 		/**
-		 * List of configuration values
+		 * Map of configuration values
 		 *
-		 * Dummy placeholder. Initiated in startUp module as a new instance of mw.Map().
-		 * If `$wgLegacyJavaScriptGlobals` is true, this Map will have its values
-		 * in the global window object.
-		 * @property
+		 * Check out [the complete list of configuration values](https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#mw.config)
+		 * on MediaWiki.org.
+		 *
+		 * If `$wgLegacyJavaScriptGlobals` is true, this Map will put its values in the
+		 * global window object.
+		 *
+		 * @property {mw.Map} config
 		 */
+		// Dummy placeholder. Re-assigned in ResourceLoaderStartupModule with an instance of `mw.Map`.
 		config: null,
 
 		/**
-- 
2.20.1