From: Bartosz Dziewoński <matma.rex@gmail.com>
Date: Fri, 14 Aug 2015 23:35:08 +0000 (+0200)
Subject: mediawiki.api: Small code quality and documentation tweaks
X-Git-Tag: 1.31.0-rc.0~10392^2
X-Git-Url: http://git.cyclocoop.org/%24action?a=commitdiff_plain;h=20e5346194ada7c2d2bc4c219eafac6823689e96;p=lhc%2Fweb%2Fwiklou.git

mediawiki.api: Small code quality and documentation tweaks

Change-Id: I70380e8f821c66ad08bfe12e242b204ffed9071d
---

diff --git a/resources/src/mediawiki.api/mediawiki.api.js b/resources/src/mediawiki.api/mediawiki.api.js
index 0b57907120..5e3a96225d 100644
--- a/resources/src/mediawiki.api/mediawiki.api.js
+++ b/resources/src/mediawiki.api/mediawiki.api.js
@@ -1,22 +1,24 @@
 ( function ( mw, $ ) {
 
-	// We allow people to omit these default parameters from API requests
-	// there is very customizable error handling here, on a per-call basis
-	// wondering, would it be simpler to make it easy to clone the api object,
-	// change error handling, and use that instead?
+	/**
+	 * @class mw.Api
+	 */
+
+	/**
+	 * @property {Object} defaultOptions Default options for #ajax calls. Can be overridden by passing
+	 *     `options` to mw.Api constructor.
+	 * @property {Object} defaultOptions.parameters Default query parameters for API requests.
+	 * @property {Object} defaultOptions.ajax Default options for jQuery#ajax.
+	 * @private
+	 */
 	var defaultOptions = {
-			// Query parameters for API requests
 			parameters: {
 				action: 'query',
 				format: 'json'
 			},
-
-			// Ajax options for jQuery.ajax()
 			ajax: {
 				url: mw.util.wikiScript( 'api' ),
-
 				timeout: 30 * 1000, // 30 seconds
-
 				dataType: 'json'
 			}
 		},
@@ -39,13 +41,11 @@
 	 * Constructor to create an object to interact with the API of a particular MediaWiki server.
 	 * mw.Api objects represent the API of a particular MediaWiki server.
 	 *
-	 * TODO: Share API objects with exact same config.
-	 *
 	 *     var api = new mw.Api();
 	 *     api.get( {
 	 *         action: 'query',
 	 *         meta: 'userinfo'
-	 *     } ).done ( function ( data ) {
+	 *     } ).done( function ( data ) {
 	 *         console.log( data );
 	 *     } );
 	 *
@@ -55,21 +55,17 @@
 	 *     api.get( {
 	 *         action: 'query',
 	 *         meta: [ 'userinfo', 'siteinfo' ] // same effect as 'userinfo|siteinfo'
-	 *     } ).done ( function ( data ) {
+	 *     } ).done( function ( data ) {
 	 *         console.log( data );
 	 *     } );
 	 *
-	 * @class
-	 *
 	 * @constructor
-	 * @param {Object} options See defaultOptions documentation above. Ajax options can also be
-	 *  overridden for each individual request to {@link jQuery#ajax} later on.
+	 * @param {Object} [options] See #defaultOptions documentation above. Can also be overridden for
+	 *  each individual request by passing them to #get or #post (or directly #ajax) later on.
 	 */
 	mw.Api = function ( options ) {
-
-		if ( options === undefined ) {
-			options = {};
-		}
+		// TODO: Share API objects with exact same config.
+		options = options || {};
 
 		// Force a string if we got a mw.Uri object
 		if ( options.ajax && options.ajax.url !== undefined ) {