diff options
Diffstat (limited to 'resources/mediawiki.api/mediawiki.api.js')
| -rw-r--r-- | resources/mediawiki.api/mediawiki.api.js | 73 |
1 files changed, 35 insertions, 38 deletions
diff --git a/resources/mediawiki.api/mediawiki.api.js b/resources/mediawiki.api/mediawiki.api.js index a184e3ca..cf7443f3 100644 --- a/resources/mediawiki.api/mediawiki.api.js +++ b/resources/mediawiki.api/mediawiki.api.js @@ -1,15 +1,9 @@ -/** - * mw.Api objects represent the API of a particular MediaWiki server. - */ ( function ( mw, $ ) { - /** - * @var defaultOptions {Object} - * 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? - */ + // 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? var defaultOptions = { // Query parameters for API requests @@ -30,22 +24,23 @@ /** * 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. * - * @todo Share API objects with exact same config. - * @example - * <code> - * var api = new mw.Api(); - * api.get( { - * action: 'query', - * meta: 'userinfo' - * }, { - * ok: function () { console.log( arguments ); } - * } ); - * </code> + * var api = new mw.Api(); + * api.get( { + * action: 'query', + * meta: 'userinfo' + * } ).done ( function ( data ) { + * console.log( data ); + * } ); + * + * @class * * @constructor - * @param options {Object} See defaultOptions documentation above. Ajax options can also be - * overridden for each individual request to jQuery.ajax() later on. + * @param {Object} options See defaultOptions documentation above. Ajax options can also be + * overridden for each individual request to {@link jQuery#ajax} later on. */ mw.Api = function ( options ) { @@ -69,13 +64,12 @@ /** * Normalize the ajax options for compatibility and/or convenience methods. * - * @param {undefined|Object|Function} An object contaning one or more of options.ajax, - * or just a success function (options.ajax.ok). + * @param {Object} [arg] An object contaning one or more of options.ajax. * @return {Object} Normalized ajax options. */ normalizeAjaxOptions: function ( arg ) { // Arg argument is usually empty - // (before MW 1.20 it was often used to pass ok/err callbacks) + // (before MW 1.20 it was used to pass ok callbacks) var opts = arg || {}; // Options can also be a success callback handler if ( typeof arg === 'function' ) { @@ -87,8 +81,8 @@ /** * Perform API get request * - * @param {Object} request parameters - * @param {Object|Function} [optional] ajax options + * @param {Object} parameters + * @param {Object|Function} [ajaxOptions] * @return {jQuery.Promise} */ get: function ( parameters, ajaxOptions ) { @@ -99,10 +93,11 @@ /** * Perform API post request - * @todo Post actions for nonlocal will need proxy * - * @param {Object} request parameters - * @param {Object|Function} [optional] ajax options + * TODO: Post actions for non-local hostnames will need proxy. + * + * @param {Object} parameters + * @param {Object|Function} [ajaxOptions] * @return {jQuery.Promise} */ post: function ( parameters, ajaxOptions ) { @@ -114,11 +109,9 @@ /** * Perform the API call. * - * @param {Object} request parameters - * @param {Object} ajax options - * @return {jQuery.Promise} - * - done: API response data as first argument - * - fail: errorcode as first arg, details (string or object) as second arg. + * @param {Object} parameters + * @param {Object} [ajaxOptions] + * @return {jQuery.Promise} Done: API response data. Fail: Error code */ ajax: function ( parameters, ajaxOptions ) { var token, @@ -187,7 +180,9 @@ }; /** - * @var {Array} List of errors we might receive from the API. + * @static + * @property {Array} + * List of errors we might receive from the API. * For now, this just documents our expectation that there should be similar messages * available. */ @@ -237,7 +232,9 @@ ]; /** - * @var {Array} List of warnings we might receive from the API. + * @static + * @property {Array} + * List of warnings we might receive from the API. * For now, this just documents our expectation that there should be similar messages * available. */ |