Thiemo Mättig (WMDE) has submitted this change and it was merged.
Change subject: Updated code documentation
......................................................................
Updated code documentation
Updated code documentation to be able to generate documentation using JSDuck.
Includes resetting @since tags to 1.0.
Change-Id: I8d08e17970faec48565b1af6683594301725d41f
---
M .jshintrc
M README.md
M WikibaseJavaScriptApi.php
M src/FormatValueCaller.js
M src/ParseValueCaller.js
M src/RepoApi.js
M src/RepoApiError.js
M src/getLocationAgnosticMwApi.js
M src/namespace.js
9 files changed, 463 insertions(+), 300 deletions(-)
Approvals:
Thiemo Mättig (WMDE): Verified; Looks good to me, approved
diff --git a/.jshintrc b/.jshintrc
index a5afa4d..832d316 100644
--- a/.jshintrc
+++ b/.jshintrc
@@ -48,7 +48,6 @@
"browser" : true, // Standard browser globals e.g. `window`,
`document`.
- "indent": 4,
"quotmark": false,
"maxlen": 100,
"maxparams": 7,
diff --git a/README.md b/README.md
index eb9ac81..8c60801 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,11 @@
## Release notes
+### 1.0.2 (dev)
+
+#### Enhancements
+* Updated code documentation to be able to generate documentation using JSDuck.
+
### 1.0.1 (2014-11-28)
* Bump the data-values/javascript dependency to 0.6.0 so that it matches
Wikibase.git's.
diff --git a/WikibaseJavaScriptApi.php b/WikibaseJavaScriptApi.php
index 25a9fa4..301bd19 100644
--- a/WikibaseJavaScriptApi.php
+++ b/WikibaseJavaScriptApi.php
@@ -1,6 +1,6 @@
<?php
-define( 'WIKIBASE_JAVASCRIPT_API_VERSION', '1.0.1' );
+define( 'WIKIBASE_JAVASCRIPT_API_VERSION', '1.0.2-dev' );
if ( defined( 'MEDIAWIKI' ) ) {
call_user_func( function() {
diff --git a/src/FormatValueCaller.js b/src/FormatValueCaller.js
index 0f44558..21060ac 100644
--- a/src/FormatValueCaller.js
+++ b/src/FormatValueCaller.js
@@ -1,13 +1,14 @@
-/**
- * @licence GNU GPL v2+
- * @author H. Snater < mediaw...@snater.com >
- */
( function( wb, $ ) {
'use strict';
var MODULE = wb.api;
/**
+ * @class wikibase.api.FormatValueCaller
+ * @since 1.0
+ * @licence GNU GPL v2+
+ * @author H. Snater < mediaw...@snater.com >
+ *
* @constructor
*
* @param {wikibase.api.RepoApi} api
@@ -21,30 +22,36 @@
$.extend( SELF.prototype, {
/**
- * @type {wikibase.api.RepoApi}
+ * @property {wikibase.api.RepoApi}
+ * @private
*/
_api: null,
/**
- * @type {dataTypes.DataTypeStore}
+ * @property {dataTypes.DataTypeStore}
+ * @private
*/
_dataTypeStore: null,
/**
* Makes a request to the API to format values on the server
side. Will return a
- * jQuery.Promise which will be resolved if formatting is
successful or rejected if it fails
- * or the API cannot be reached.
- * @since 0.5
+ * `jQuery.Promise` which will be resolved if formatting is
successful or rejected if it
+ * fails or the API cannot be reached.
*
* @param {dataValues.DataValue} dataValue
- * @param {string} [dataType]
- * @param {string} [outputFormat]
+ * @param {string|Object} [dataType] `DataType` id.
+ * Assumed to be `outputFormat` if the `dataTypeStore`
the `FormatValueCaller` has
+ * been initialized with, does not contain a data type
whose id matches the string
+ * supplied via this argument.
+ * Assumed to be `options` if {Object} and no additional
arguments are provided.
+ * @param {string|Object} [outputFormat]
+ * Assumed to be `options` if {Object} and no additional
arguments are provided.
* @param {Object} [options]
- * @return {jQuery.Promise}
- * Resolved parameters:
- * - {string} Formatted DataValue.
- * Rejected parameters:
- * - {wikibase.api.RepoApiError}
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {string} return.done.formattedValue Formatted
`DataValue`.
+ * @return {Function} return.fail
+ * @return {wikibase.api.RepoApiError} error
*/
formatValue: function( dataValue, dataType, outputFormat,
options ) {
diff --git a/src/ParseValueCaller.js b/src/ParseValueCaller.js
index 01f06b4..aa26af2 100644
--- a/src/ParseValueCaller.js
+++ b/src/ParseValueCaller.js
@@ -1,8 +1,3 @@
-/**
- * @licence GNU GPL v2+
- * @author Jeroen De Dauw < jeroended...@gmail.com >
- * @author H. Snater < mediaw...@snater.com >
- */
( function( wb, $ ) {
'use strict';
@@ -10,8 +5,13 @@
/**
* Provides functionality to parse a value using the API.
+ * @class wikibase.api.ParseValueCaller
+ * @since 1.0
+ * @licence GNU GPL v2+
+ * @author Jeroen De Dauw < jeroended...@gmail.com >
+ * @author H. Snater < mediaw...@snater.com >
+ *
* @constructor
- * @since 0.5
*
* @param {wikibase.api.RepoApi} api
*/
@@ -22,7 +22,8 @@
$.extend( SELF.prototype, {
/**
- * @type {wikibase.api.RepoApi}
+ * @property {wikibase.api.RepoApi}
+ * @private
*/
_api: null,
@@ -30,16 +31,15 @@
* Makes a request to the API to parse values on the server side. Will
return a jQuery.Promise
* which will be resolved if the call is successful or rejected if the
API fails or can't be
* reached.
- * @since 0.5
*
- * @param {string} parser
- * @param {string[]} values
- * @param {Object} options
+ * @param {string} parser Parser id.
+ * @param {string[]} values `DataValue` serializations.
+ * @param {Object} [options={}]
* @return {Object} jQuery.Promise
- * Resolved parameters:
- * - {Object[]}
- * Rejected parameters:
- * - {wikibase.api.RepoApiError}
+ * @return {Function} return.done
+ * @return {Object[]} return.done.serializations `DataValue`
serializations.
+ * @return {Function} return.fail
+ * @return {wikibase.api.RepoApiError} return.fail.error
*/
parseValues: function( parser, values, options ) {
var deferred = $.Deferred();
diff --git a/src/RepoApi.js b/src/RepoApi.js
index 4baf3f8..f90a70c 100644
--- a/src/RepoApi.js
+++ b/src/RepoApi.js
@@ -1,10 +1,3 @@
-/**
- * @licence GNU GPL v2+
- * @author Daniel Werner < daniel.wer...@wikimedia.de >
- * @author Tobias Gritschacher
- * @author H. Snater < mediaw...@snater.com >
- * @author Marius Hoch < h...@online.de >
- */
( function( wb, $ ) {
'use strict';
@@ -12,17 +5,29 @@
/**
* Constructor to create an API object for interaction with the repo Wikibase
API.
+ * Functions of `wikibase.api.RepoApi` act on serializations. Before passing
native
+ * `wikibase.datamodel` objects to a function, such objects need to be
serialized, just like return
+ * values of `wikibase.api.RepoApi` may be used to construct
`wikibase.datamodel` objects.
+ * @see wikibase.datamodel
+ * @see wikibase.serialization
+ *
+ * @class wikibase.api.RepoApi
+ * @since 1.0
+ * @licence GNU GPL v2+
+ * @author Daniel Werner < daniel.wer...@wikimedia.de >
+ * @author Tobias Gritschacher
+ * @author H. Snater < mediaw...@snater.com >
+ * @author Marius Hoch < h...@online.de >
+ *
* @constructor
- * @since 0.5 (in 0.4 without constructor parameters, in 0.3 as wikibase.Api
- * without support for client usage)
*
* @param {mediaWiki.Api} api
*
- * @throws {Error} if parameters are not specified properly.
+ * @throws {Error} if no `mediaWiki.Api` instance is provided.
*/
var SELF = MODULE.RepoApi = function wbRepoApi( api ) {
if( api === undefined ) {
- throw new Error( 'Required parameters not specified properly' );
+ throw new Error( 'mediaWiki.Api instance needs to be provided'
);
}
this._api = api;
@@ -30,16 +35,24 @@
$.extend( SELF.prototype, {
/**
- * @type mediaWiki.Api
+ * @property {mediaWiki.Api}
+ * @private
*/
_api: null,
/**
* Creates a new entity with the given type and data.
+ * @see wikibase.api.RepoApi._post
*
- * @param {String} type The type of the entity that should be created.
- * @param {Object} [data] The entity data (may be omitted to create an
empty entity)
- * @return {jQuery.Promise}
+ * @param {string} type The type of the `Entity` that should be created.
+ * @param {Object} [data] The `Entity` data (may be omitted to create
an empty `Entity`).
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error
*/
createEntity: function( type, data ) {
var params = {
@@ -51,13 +64,20 @@
},
/**
- * Edits an entity.
+ * Edits an `Entity`.
+ * @see wikibase.api.RepoApi._post
*
- * @param {String} id Entity id
- * @param {Number} baseRevId Revision id the edit shall be performed on
- * @param {Object} data The entity's structure
- * @param {Boolean} [clear] Whether to clear whole entity before
editing (default: false)
- * @return {jQuery.Promise}
+ * @param {String} id `Entity` id.
+ * @param {Number} baseRevId Revision id the edit shall be performed on.
+ * @param {Object} data The `Entity`'s structure.
+ * @param {Boolean} [clear=false] Whether to clear whole entity before
editing.
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error
*/
editEntity: function( id, baseRevId, data, clear ) {
var params = {
@@ -75,13 +95,20 @@
},
/**
- * Formats values.
+ * Formats values (`dataValues.DataValue`s).
+ * @see wikibase.api.RepoApi._post
*
- * @param {Object} dataValue
- * @param {Object} [options]
- * @param {string} [dataType]
+ * @param {Object} dataValue `DataValue` serialization.
+ * @param {Object} [options={}]
+ * @param {string} [dataType] `dataTypes.DataType` id.
* @param {string} [outputFormat]
- * @return {jQuery.Promise}
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error
*/
formatValue: function( dataValue, options, dataType, outputFormat ) {
var params = {
@@ -102,18 +129,25 @@
},
/**
- * Gets one or more Entities.
+ * Gets one or more `Entity`s.
+ * @see wikibase.api.RepoApi._post
*
- * @param {String[]|String} ids
- * @param {String[]|String} [props] Key(s) of property/ies to retrieve
from the API
- * default: null (will return all properties)
- * @param {String[]} [languages]
- * default: null (will return results in all
languages)
- * @param {String[]|String} [sort] Key(s) of property/ies to sort on
- * default: null (unsorted)
- * @param {String} [dir] Sort direction may be 'ascending' or
'descending'
- * default: null (ascending)
- * @return {jQuery.Promise}
+ * @param {string|string[]} ids `Entity` id(s).
+ * @param {string|string[]|null} [props=null] Key(s) of property/ies to
retrieve from the API.
+ * `null` will return all properties.
+ * @param {string|string[]|null} [languages=null] Language code(s) of
the languages the
+ * property/ies values should be retrieved in. `null` returns
values in all languages.
+ * @param {string|string[]|null} [sort=null] Key(s) of property/ies to
sort on. `null` will
+ * result in unsorted output.
+ * @param {string|null} [dir=null] Sort direction, may be 'ascending'
or 'descending'.
+ * `null` resolves to 'ascending'.
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error
*/
getEntities: function( ids, props, languages, sort, dir ) {
var params = {
@@ -129,20 +163,29 @@
},
/**
- * Gets an Entity which is linked with a given page.
+ * Gets an `Entity` which is linked with on or more specific
sites/pages.
+ * @see wikibase.api.RepoApi._post
*
- * @param {String[]|String} [sites] Site(s) the given page is linked on
- * @param {String[]|String} [titles] Linked page(s)
- * @param {String[]|String} [props] Key(s) of property/ies to retrieve
from the API
- * default: null (will return all properties)
- * @param {String[]} [languages]
- * default: null (will return results in all
languages)
- * @param {String[]|String} [sort] Key(s) of property/ies to sort on
- * default: null (unsorted)
- * @param {String} [dir] Sort direction may be 'ascending' or
'descending'
- * default: null (ascending)
+ * @param {string|string[]} [sites] `Site`(s). May be used with
`titles`. May not be a list when
+ * `titles` is a list.
+ * @param {string|string[]} [titles] Linked page(s). May be used with
`sites`. May not be a list
+ * when `sites` is a list.
+ * @param {string|string[]|null} [props=null] Key(s) of property/ies to
retrieve from the API.
+ * `null` returns all properties.
+ * @param {string|string[]|null} [languages=null] Language code(s) of
the languages the
+ * property/ies values should be retrieved in. `null` returns
values in all languages.
+ * @param {string|string[]|null} [sort=null] Key(s) of property/ies to
sort on. `null` will
+ * result in unsorted output.
+ * @param {string|null} [dir=null] Sort direction, may be 'ascending'
or 'descending'.
+ * `null` resolves to 'ascending'.
* @param {boolean} [normalize] Whether to normalize titles server side
- * @return {jQuery.Promise}
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error
*/
getEntitiesByPage: function( sites, titles, props, languages, sort,
dir, normalize ) {
var params = {
@@ -160,12 +203,19 @@
},
/**
- * Parses values.
+ * Parses values (`dataValues.DataValue`s).
+ * @see wikibase.api.RepoApi._post
*
- * @param {string} parser
- * @param {string[]} values
- * @param {Object} options
- * @return {jQuery.Promise}
+ * @param {string} parser Parser id.
+ * @param {string[]} values `DataValue` serializations.
+ * @param {Object} [options]
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error
*/
parseValue: function( parser, values, options ) {
var params = {
@@ -178,14 +228,21 @@
},
/**
- * Searches for entities containing the given text.
+ * Searches for `Entity`s containing the given text.
+ * @see wikibase.api.RepoApi._post
*
- * @param {String} search search for this text
- * @param {String} language search in this language
- * @param {String} type search for this entity type
- * @param {Number} limit maximum number of results to return
- * @param {Number} offset offset where to continue the search
- * @return {jQuery.Promise}
+ * @param {string} search Text to search for.
+ * @param {string} language Language code of the language to search in.
+ * @param {string} type `Entity` type to search for.
+ * @param {number} limit Maximum number of results to return.
+ * @param {number} offset Offset where to continue returning the search
results.
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error
*/
searchEntities: function( search, language, type, limit, offset ) {
var params = {
@@ -201,13 +258,20 @@
},
/**
- * Sets the label of an entity via the API.
+ * Sets the label of an `Entity`.
+ * @see wikibase.api.RepoApi._post
*
- * @param {String} id entity id
- * @param {Number} baseRevId revision id
- * @param {String} label the label to set
- * @param {String} language the language in which the label should be
set
- * @return {jQuery.Promise}
+ * @param {string} id `Entity` id.
+ * @param {number} baseRevId Revision id the edit shall be performed on.
+ * @param {string} label New label text.
+ * @param {string} language Language code of the language the new label
should be set in.
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error
*/
setLabel: function( id, baseRevId, label, language ) {
var params = {
@@ -221,13 +285,20 @@
},
/**
- * Sets the description of an entity via the API.
+ * Sets the description of an `Entity`.
+ * @see wikibase.api.RepoApi._post
*
- * @param {String} id entity id
- * @param {Number} baseRevId revision id
- * @param {String} description the description to set
- * @param {String} language the language in which the description
should be set
- * @return {jQuery.Promise}
+ * @param {string} id `Entity` id.
+ * @param {number} baseRevId Revision id the edit shall be performed on.
+ * @param {string} description New description text.
+ * @param {string} language Language code of the language the new
description should be set in.
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error
*/
setDescription: function( id, baseRevId, description, language ) {
var params = {
@@ -241,14 +312,22 @@
},
/**
- * Adds and/or remove a number of aliases of an item via the API.
+ * Adds and/or remove a number of aliases of an `Entity`.
+ * @see wikibase.api.RepoApi._post
*
- * @param {String} id entity id
- * @param {Number} baseRevId revision id
- * @param {String[]|String} add Alias(es) to add
- * @param {String[]|String} remove Alias(es) to remove
- * @param {String} language the language in which the aliases should be
added/removed
- * @return {jQuery.Promise}
+ * @param {string} id `Entity` id.
+ * @param {number} baseRevId Revision id the edit shall be performed on.
+ * @param {string|string[]} add Alias(es) to add.
+ * @param {string|string[]} remove Alias(es) to remove.
+ * @param {string} language Language code of the language the aliases
should be added/removed
+ * in.
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error
*/
setAliases: function( id, baseRevId, add, remove, language ) {
add = this._normalizeParam( add );
@@ -265,13 +344,20 @@
},
/**
- * Creates/Updates an entire claim.
+ * Creates/Updates an entire `Claim`.
+ * @see wikibase.api.RepoApi._post
*
- * @param {object} claim
- * @param {number} baseRevId
- * @param {number} [index] The claim index. Only needs to be specified
if the claim's index
- * within the list of all claims of the parent entity shall be
changed.
- * @return {jQuery.Promise}
+ * @param {Object} claim `Claim` serialization.
+ * @param {number} baseRevId Revision id the edit shall be performed on.
+ * @param {number} [index] The `Claim`'s index. Only needs to be
specified if the `Claim`'s
+ * index within the list of all `Claim`s of the parent `Entity`
shall be changed.
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error
*/
setClaim: function( claim, baseRevId, index ) {
var params = {
@@ -288,14 +374,22 @@
},
/**
- * Creates a claim.
+ * Creates a `Claim`.
+ * @see wikibase.api.RepoApi._post
*
- * @param {string} entityId Entity id
- * @param {number} baseRevId revision id
- * @param {string} snakType The type of the snak
- * @param {string} property Id of the snak's property
- * @param {Object|string} value The value to set the datavalue of the
claim's main snak to
- * @return {jQuery.Promise}
+ * @param {string} entityId `Entity` id.
+ * @param {number} baseRevId Revision id the edit shall be performed on.
+ * @param {string} snakType The type of the `Snak` (see
`wikibase.datamodel.Snak.TYPE`).
+ * @param {string} property Id of the `Snak`'s `Property`.
+ * @param {Object|string} [value] `DataValue` serialization that needs
to be provided when the
+ * specified `Snak` type requires a value.
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error
*/
createClaim: function( entityId, baseRevId, snakType, property, value )
{
var params = {
@@ -314,11 +408,18 @@
},
/**
- * Removes an existing claim.
+ * Removes a `Claim`.
+ * @see wikibase.api.RepoApi._post
*
- * @param {String} claimGuid The GUID of the Claim to be removed
- * @param {Number} [claimRevisionId]
- * @return {jQuery.Promise}
+ * @param {string} claimGuid The GUID of the `Claim` to be removed.
+ * @param {number} [claimRevisionId] Revision id the edit shall be
performed on.
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error
*/
removeClaim: function( claimGuid, claimRevisionId ) {
return this._post( {
@@ -329,16 +430,23 @@
},
/**
- * Returns claims of a specific entity by providing an entity id or a
specific claim by
- * providing a claim GUID.
+ * Returns `Claim`s of a specific `Entity` by providing an `Entity` id
or a specific `Claim` by
+ * providing a `Claim` GUID.
+ * @see wikibase.api.RepoApi._post
*
- * @param {string} entityId Entity id
- * @param {string} [propertyId] Only return claims featuring this
property
- * @param {string} claimGuid GUID of the claim to return. Either
claimGuid or entityID has to be
- * provided.
- * @param {string} [rank] Only return claims of this rank
- * @param {string} [props] Optional parts of the claims to return
- * @return {jQuery.Promise}
+ * @param {string|null} entityId `Entity` id.
+ * @param {string} [propertyId] Only return `Claim`s featuring this
`Property`.
+ * @param {string} [claimGuid] GUID of the `Claim` to return. Either
`claimGuid` or `entityID`
+ * has to be provided.
+ * @param {string} [rank] Only return `Claim`s of this `rank`.
+ * @param {string} [props] Specific parts of the `Claim`s to include in
the response.
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error
*/
getClaims: function( entityId, propertyId, claimGuid, rank, props ) {
var params = {
@@ -354,14 +462,22 @@
},
/**
- * Changes the Main Snak of an existing claim.
+ * Changes the main `Snak` of an existing `Claim`.
+ * @see wikibase.api.RepoApi._post
*
- * @param {string} claimGuid The GUID of the Claim to be changed
- * @param {number} baseRevId
- * @param {string} snakType The type of the snak
- * @param {string} property Id of the snak's property
- * @param {object} value The value to set the datavalue of the the main
snak of the claim to
- * @return {jQuery.Promise}
+ * @param {string} claimGuid The GUID of the `Claim` to be changed.
+ * @param {number} baseRevId Revision id the edit shall be performed on.
+ * @param {string} snakType The type of the `Snak` (see
`wikibase.datamodel.Snak.TYPE`).
+ * @param {string} property Id of the `Snak`'s `Property`.
+ * @param {Object|string} [value] `DataValue` serialization that needs
to be provided when the
+ * specified `Snak` type requires a value.
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error
*/
setClaimValue: function( claimGuid, baseRevId, snakType, property,
value ) {
var params = {
@@ -382,19 +498,25 @@
},
/**
- * Adds a new or updates an existing Reference of a Statement.
+ * Adds a new or updates an existing `Reference` of a `Statement`.
+ * @see wikibase.api.RepoApi._post
*
- * @since 0.4
- *
- * @param {string} statementGuid
- * @param {object} snaks
- * @param {number} baseRevId
+ * @param {string} statementGuid `GUID` of the `Statement` which a
`Reference`.
+ * should be added to or changed of.
+ * @param {Object} snaks `snak` portion of a serialized `Reference`.
+ * @param {number} baseRevId Revision id the edit shall be performed on.
* @param {string} [referenceHash] A hash of the reference that should
be updated.
* If not provided, a new reference is created.
- * @param {number} [index] The reference index. Only needs to be
specified if the reference's
- * index within the list of all references of the parent
statement shall be changed or
- * when the reference should be inserted at a specific position.
- * @return {jQuery.Promise}
+ * @param {number} [index] The `Reference` index. Only needs to be
specified if the
+ * `Reference`'s index within the list of all `Reference`s of
the parent `Statement`
+ * shall be changed or when the `Reference` should be inserted
at a specific position.
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error
*/
setReference: function( statementGuid, snaks, baseRevId, referenceHash,
index ) {
var params = {
@@ -421,14 +543,21 @@
},
/**
- * Will remove one or more existing References of a Statement.
+ * Removes one or more `Reference`s of a `Statement`.
+ * @see wikibase.api.RepoApi._post
*
- * @since 0.4
- *
- * @param {string} statementGuid
- * @param {string|string[]} referenceHashes One or more hashes of the
References to be removed.
- * @param {number} baseRevId
- * @return {jQuery.Promise}
+ * @param {string} statementGuid `GUID` of the `Statement` which
`Reference`s should be removed
+ * of.
+ * @param {string|string[]} referenceHashes One or more hashes of the
`Reference`s to be
+ * removed.
+ * @param {number} baseRevId Revision id the edit shall be performed on.
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error
*/
removeReferences: function( statementGuid, referenceHashes, baseRevId )
{
var params = {
@@ -442,14 +571,21 @@
},
/**
- * Sets a site link for an item via the API.
+ * Sets a `SiteLink` for an item via the API.
+ * @see wikibase.api.RepoApi._post
*
- * @param {String} id entity id
- * @param {Number} baseRevId revision id
- * @param {String} site the site of the link
- * @param {String} title the title to link to
- * @param {String[]|String} [badges] the list of badges
- * @return {jQuery.Promise}
+ * @param {string} id `Entity` id.
+ * @param {number} baseRevId Revision id the edit shall be performed on.
+ * @param {string} site Site of the link.
+ * @param {string} title Title to link to.
+ * @param {string[]|string} [badges] List of `Entity` ids to be
assigned as badges.
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error
*/
setSitelink: function( id, baseRevId, site, title, badges ) {
var params = {
@@ -469,13 +605,19 @@
/**
* Sets a site link for an item via the API.
+ * @see wikibase.api.RepoApi._post
*
- * @param {string} [fromId] The id to merge from
- * @param {string} [toId] The id to merge to
- * @param {string[]|string} [ignoreConflicts] Elements of the item to
ignore conflicts for
- * @param {string} [summary] Summary for the edit
- *
- * @return {jQuery.Promise}
+ * @param {string} [fromId] `Entity` id to merge from.
+ * @param {string} [toId] `Entity` id to merge to.
+ * @param {string[]|string} [ignoreConflicts] Elements of the `Item` to
ignore conflicts for.
+ * @param {string} [summary] Summary for the edit.
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error
*/
mergeItems: function( fromId, toId, ignoreConflicts, summary ) {
var params = {
@@ -496,11 +638,10 @@
},
/**
- * Converts the given value into a string usable by the API
+ * Converts the given value into a string usable by the API.
+ * @private
*
- * @since 0.4
- *
- * @param {string[]|string} [value]
+ * @param {string[]|string|null} [value]
* @return {string|undefined}
*/
_normalizeParam: function( value ) {
@@ -512,16 +653,21 @@
* automatically add the required 'token' information for editing into
the given parameters
* sent to the API.
* @see mediaWiki.Api.post
+ * @see mediaWiki.Api.ajax
+ * @private
*
- * @param {Object} params parameters for the API call
- * @return {jQuery.Promise}
- * Resolved parameters:
- * - {*}
- * Rejected parameters:
- * - {string}
- * - {*}
+ * @param {Object} params parameters for the API call.
+ * @return {Object} jQuery.Promise
+ * @return {Function} return.done
+ * @return {*} return.done.result
+ * @return {jqXHR} return.done.jqXHR
+ * @return {Function} return.fail
+ * @return {string} return.fail.code
+ * @return {*} return.fail.error A plain object with information about
the error if `code` is
+ * "http", a string, if the call was successful but the
response is empty or the result
+ * result if it contains an `error` field.
*
- * @throws {Error} If a parameter is not specified properly
+ * @throws {Error} if a parameter is not specified properly.
*/
_post: function( params ) {
// Unconditionally set the bot parameter to match the UI
behaviour of core
diff --git a/src/RepoApiError.js b/src/RepoApiError.js
index 36a34ce..1a73e5e 100644
--- a/src/RepoApiError.js
+++ b/src/RepoApiError.js
@@ -1,26 +1,26 @@
-/**
- * @licence GNU GPL v2+
- * @author H. Snater < mediaw...@snater.com >
- */
( function( mw, wb, util ) {
'use strict';
- var MODULE = wb.api;
- var PARENT = Error;
+var MODULE = wb.api;
+var PARENT = Error;
- /**
- * Wikibase Repo API Error.
- *
- * @constructor
- * @extends Error
- * @since 0.4
- *
- * @param {string} code Error code (used to determine the actual error
message)
- * @param {string} detailedMessage Detailed error information
- * @param {string} [action] Generic API action (e.g. "save" or
"cancel") used to determine a
- * specific message
- */
- var constructor = function( code, detailedMessage, action ) {
+/**
+ * Wikibase Repo API Error.
+ * @class wikibase.api.RepoApiError
+ * @extends Error
+ * @since 1.0
+ * @licence GNU GPL v2+
+ * @author H. Snater < mediaw...@snater.com >
+ *
+ * @constructor
+ *
+ * @param {string} code Error code (used to determine the actual error
message).
+ * @param {string} detailedMessage Detailed error information.
+ * @param {string} [action] Generic API action (e.g. "save" or "cancel") used
to determine a
+ * specific message.
+ */
+var SELF = MODULE.RepoApiError
+ = util.inherit( 'WbRepoApiError', PARENT, function( code,
detailedMessage, action ) {
this.code = code;
this.detailedMessage = detailedMessage;
this.action = action;
@@ -28,101 +28,100 @@
// native Error attributes
this.name = 'Wikibase Repo API Error';
this.message = this.getMessage();
- };
-
- var SELF = MODULE.RepoApiError = util.inherit( 'WbRepoApiError',
PARENT, constructor,
- {
- /**
- * Message keys of API related error messages.
- * @type {Object}
- * @constant
- */
- API_ERROR_MESSAGE: {
- GENERIC: {
- DEFAULT: 'wikibase-error-unexpected',
- save: 'wikibase-error-save-generic',
- remove: 'wikibase-error-remove-generic'
- },
- timeout: {
- save: 'wikibase-error-save-timeout',
- remove: 'wikibase-error-remove-timeout'
- },
- 'no-external-page':
'wikibase-error-ui-no-external-page',
- 'edit-conflict':
'wikibase-error-ui-edit-conflict'
- },
-
- /**
- * Gets a short message string.
- * @since 0.4
- *
- * @return {string}
- */
- getMessage: function() {
- var msgKey = this.API_ERROR_MESSAGE[this.code];
-
- if ( !msgKey || typeof msgKey !== 'string' ) {
- if ( msgKey && this.action &&
msgKey[this.action] ) {
- msgKey = msgKey[this.action];
- } else if ( this.action &&
this.API_ERROR_MESSAGE.GENERIC[this.action] ) {
- msgKey =
this.API_ERROR_MESSAGE.GENERIC[this.action];
- } else {
- msgKey =
this.API_ERROR_MESSAGE.GENERIC.DEFAULT;
- }
- }
-
- return mw.msg( msgKey );
- }
-
- }
- );
+ },
+{
+ /**
+ * Message keys of API related error messages.
+ * @property {Object}
+ * @private
+ * @readonly
+ */
+ API_ERROR_MESSAGE: {
+ GENERIC: {
+ DEFAULT: 'wikibase-error-unexpected',
+ save: 'wikibase-error-save-generic',
+ remove: 'wikibase-error-remove-generic'
+ },
+ timeout: {
+ save: 'wikibase-error-save-timeout',
+ remove: 'wikibase-error-remove-timeout'
+ },
+ 'no-external-page': 'wikibase-error-ui-no-external-page',
+ 'edit-conflict': 'wikibase-error-ui-edit-conflict'
+ },
/**
- * Creates a new RepoApiError out of the values returned from the API.
- * @since 0.4
+ * Returns a short message string.
*
- * @param {Object} details Object returned from the API containing
detailed information
- * @param {string} [apiAction] API action (e.g. 'save', 'remove') that
may be passed to
- * determine a specific message
- * @return {wikibase.api.RepoApiError}
+ * @return {string}
*/
- SELF.newFromApiResponse = function( details, apiAction ) {
- var errorCode = '',
- detailedMessage = '';
+ getMessage: function() {
+ var msgKey = this.API_ERROR_MESSAGE[this.code];
- if ( details.error ) {
- errorCode = details.error.code;
- if( details.error.messages ) {
- // HTML message from Wikibase API.
- detailedMessage = messagesObjectToHtml(
details.error.messages );
+ if ( !msgKey || typeof msgKey !== 'string' ) {
+ if ( msgKey && this.action && msgKey[this.action] ) {
+ msgKey = msgKey[this.action];
+ } else if ( this.action &&
this.API_ERROR_MESSAGE.GENERIC[this.action] ) {
+ msgKey =
this.API_ERROR_MESSAGE.GENERIC[this.action];
} else {
- // Wikibase API no-HTML error message fall-back.
- detailedMessage = details.error.info;
+ msgKey = this.API_ERROR_MESSAGE.GENERIC.DEFAULT;
}
- } else if ( details.exception ) {
- // Failed MediaWiki API call.
- errorCode = details.textStatus;
- detailedMessage = details.exception;
}
- return new SELF( errorCode, detailedMessage, apiAction );
- };
-
- /**
- * @param {Object} messages Object returned from the API
- * @return {string|undefined} HTML list, single message or undefined if
no HTML could be found
- */
- function messagesObjectToHtml( messages ) {
- // Can't use length, it's not an array!
- if ( messages[1] && messages[1].html ) {
- var html = '<ul>';
- for ( var i = 0; messages[i]; i++ ) {
- html += '<li>' + messages[i].html['*'] +
'</li>';
- }
- return html + '</ul>';
- }
-
- return messages[0] && messages[0].html && messages[0].html['*']
- || messages.html && messages.html['*'];
+ return mw.msg( msgKey );
}
+} );
+
+/**
+ * Creates a new RepoApiError out of the values returned from the API.
+ * @static
+ *
+ * @param {Object} details Object returned from the API containing detailed
information.
+ * @param {string} [apiAction] API action (e.g. 'save', 'remove') that may be
passed to
+ * determine a specific message.
+ * @return {wikibase.api.RepoApiError}
+ */
+SELF.newFromApiResponse = function( details, apiAction ) {
+ var errorCode = '',
+ detailedMessage = '';
+
+ if ( details.error ) {
+ errorCode = details.error.code;
+ if( details.error.messages ) {
+ // HTML message from Wikibase API.
+ detailedMessage = messagesObjectToHtml(
details.error.messages );
+ } else {
+ // Wikibase API no-HTML error message fall-back.
+ detailedMessage = details.error.info;
+ }
+ } else if ( details.exception ) {
+ // Failed MediaWiki API call.
+ errorCode = details.textStatus;
+ detailedMessage = details.exception;
+ }
+
+ return new SELF( errorCode, detailedMessage, apiAction );
+};
+
+/**
+ * @ignore
+ *
+ * @param {Object} messages Object returned from the API.
+ * @return {string|undefined} HTML list, single message or undefined if no
HTML could be found.
+ */
+function messagesObjectToHtml( messages ) {
+ // Can't use length, it's not an array!
+ if ( messages[1] && messages[1].html ) {
+ var html = '<ul>';
+ for ( var i = 0; messages[i]; i++ ) {
+ html += '<li>' + messages[i].html['*'] + '</li>';
+ }
+ return html + '</ul>';
+ }
+
+ return messages[0] && messages[0].html && messages[0].html['*']
+ || messages.html && messages.html['*'];
+}
+
}( mediaWiki, wikibase, util ) );
diff --git a/src/getLocationAgnosticMwApi.js b/src/getLocationAgnosticMwApi.js
index dc2cbd9..7e2172f 100644
--- a/src/getLocationAgnosticMwApi.js
+++ b/src/getLocationAgnosticMwApi.js
@@ -1,11 +1,9 @@
-/**
- * @licence GNU GPL v2+
- * @author Adrian Lang < adrian.l...@wikimedia.de >
- */
( function( mw, wb ) {
'use strict';
/**
+ * @ignore
+ *
* @param {string} url
* @return {string}
*/
@@ -13,10 +11,14 @@
return url.replace( /.*\/\//, '' ).replace( /\/.*/, '' );
}
+// TODO: Merge this into mw.Api
/**
- * Returns a mediaWiki.Api instance which can transparently interact with
remote APIs.
- * @since 0.5
- * @todo Merge this into mw.Api
+ * Returns a `mediaWiki.Api` instance which can transparently interact with
remote APIs.
+ * @member wikibase.api
+ * @method getLocationAgnosticMwApi
+ * @since 1.0
+ * @licence GNU GPL v2+
+ * @author Adrian Lang < adrian.l...@wikimedia.de >
*
* @param {string} apiEndpoint
* @return {mediaWiki.Api}
diff --git a/src/namespace.js b/src/namespace.js
index bf080a4..6d9acac 100644
--- a/src/namespace.js
+++ b/src/namespace.js
@@ -2,5 +2,10 @@
'use strict';
global.wikibase = global.wikibase || {};
+
+ /**
+ * @class wikibase.api
+ * @singleton
+ */
global.wikibase.api = global.wikibase.api || {};
}( this ) );
--
To view, visit https://gerrit.wikimedia.org/r/176337
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: I8d08e17970faec48565b1af6683594301725d41f
Gerrit-PatchSet: 6
Gerrit-Project: mediawiki/extensions/WikibaseJavaScriptApi
Gerrit-Branch: master
Gerrit-Owner: Henning Snater <henning.sna...@wikimedia.de>
Gerrit-Reviewer: Thiemo Mättig (WMDE) <thiemo.maet...@wikimedia.de>
_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
