Updated code documentation

README.md

@@ -9,6 +9,11 @@ https://commons.wikimedia.org/wiki/File:Wikibase_JavaScript_Data_Model_1.0.svg
 
 ## Release notes
 
+### 1.0.2 (dev)
+
+#### Enhancements
+* Updated code documentation for being able to automatically generate a proper documentation using JSDuck.
+
 ### 1.0.1 (2014-11-05)
 * Using DataValues JavaScript 0.6.x.
 

init.php

@@ -1,6 +1,6 @@
 <?php
 
-define( 'WIKIBASE_DATAMODEL_JAVASCRIPT_VERSION', '1.0' );
+define( 'WIKIBASE_DATAMODEL_JAVASCRIPT_VERSION', '1.0.2-dev' );
 
 if ( defined( 'MEDIAWIKI' ) ) {
 	call_user_func( function() {

src/Claim.js

@@ -1,18 +1,19 @@
-/**
- * @licence GNU GPL v2+
- * @author Daniel Werner < daniel.werner@wikimedia.de >
- */
 ( function( wb, $ ) {
 'use strict';
 
 /**
- * @constructor
+ * Object featuring a main snak and a list of qualifiers.
+ * @class wikibase.datamodel.Claim
  * @since 0.3
+ * @licence GNU GPL v2+
+ * @author Daniel Werner < daniel.werner@wikimedia.de >
+ *
+ * @constructor
  *
  * @param {wikibase.datamodel.Snak} mainSnak
- * @param {wikibase.datamodel.SnakList|null} [qualifiers]
- * @param {string|null} [guid] The Global Unique Identifier of this Claim. Can be omitted or null
- *        if this is a new Claim, not yet stored in the database and associated with some entity.
+ * @param {wikibase.datamodel.SnakList|null} [qualifiers=new wikibase.datamodel.SnakList()]
+ * @param {string|null} [guid=null] The Global Unique Identifier of this Claim. Can be null if this
+ *        is a new Claim, not yet stored in the database and associated with some entity.
  */
 var SELF = wb.datamodel.Claim = function WbDataModelClaim( mainSnak, qualifiers, guid ) {
 	this.setMainSnak( mainSnak );
@@ -22,17 +23,20 @@ var SELF = wb.datamodel.Claim = function WbDataModelClaim( mainSnak, qualifiers,
 
 $.extend( SELF.prototype, {
 	/**
-	 * @type {wikibase.datamodel.Snak}
+	 * @property {wikibase.datamodel.Snak}
+	 * @private
 	 */
 	_mainSnak: null,
 
 	/**
-	 * @type {wikibase.datamodel.SnakList}
+	 * @property {wikibase.datamodel.SnakList}
+	 * @private
 	 */
 	_qualifiers: null,
 
 	/**
-	 * @type {string|null}
+	 * @property {string|null}
+	 * @private
 	 */
 	_guid: null,
 
@@ -59,6 +63,8 @@ $.extend( SELF.prototype, {
 	 * Overwrites the current main Snak.
 	 *
 	 * @param {wikibase.datamodel.Snak} mainSnak
+	 *
+	 * @throws {Error} if parameter is not a Snak instance.
 	 */
 	setMainSnak: function( mainSnak ) {
 		if( !( mainSnak instanceof wb.datamodel.Snak ) ) {
@@ -88,6 +94,8 @@ $.extend( SELF.prototype, {
 
 	/**
 	 * @param {wikibase.datamodel.SnakList} qualifiers
+	 *
+	 * @throws {Error} if parameter is not a SnakList instance.
 	 */
 	setQualifiers: function( qualifiers ) {
 		if( !( qualifiers instanceof wb.datamodel.SnakList ) ) {

src/ClaimGroup.js

@@ -1,18 +1,19 @@
-/**
- * @licence GNU GPL v2+
- * @author H. Snater < mediawiki@snater.com >
- */
 ( function( wb ) {
 'use strict';
 
 var PARENT = wb.datamodel.Group;
 
 /**
- * Ordered list of Claim objects, each featuring the same property id.
- * @constructor
+ * List of Claim objects, constrained to a single property id.
+ * @class wikibase.datamodel.ClaimGroup
+ * @extends wikibase.datamodel.Group
  * @since 1.0
+ * @licence GNU GPL v2+
+ * @author H. Snater < mediawiki@snater.com >
+ *
+ * @constructor
  *
- * @param {wikibase.datamodel.ClaimList} [claimList]
+ * @param {wikibase.datamodel.ClaimList} [claimList=new wikibase.datamodel.ClaimList()]
  */
 wb.datamodel.ClaimGroup = util.inherit( 'wbClaimGroup', PARENT, function( propertyId, claimList ) {
 	PARENT.call( this, propertyId, wb.datamodel.ClaimList, 'getPropertyIds', claimList );

src/ClaimGroupSet.js

@@ -1,17 +1,19 @@
-/**
- * @licence GNU GPL v2+
- * @author H. Snater < mediawiki@snater.com >
- */
 ( function( wb ) {
 'use strict';
 
 var PARENT = wb.datamodel.Set;
 
 /**
- * @constructor
+ * Set of ClaimGroup objects.
+ * @class wikibase.datamodel.ClaimGroupSet
+ * @extends wikibase.datamodel.Set
  * @since 1.0
+ * @licence GNU GPL v2+
+ * @author H. Snater < mediawiki@snater.com >
+ *
+ * @constructor
  *
- * @param {wikibase.datamodel.ClaimGroup[]} [claimGroups]
+ * @param {wikibase.datamodel.ClaimGroup[]} [claimGroups=new wikibase.datamodel.ClaimGroup]
  */
 wb.datamodel.ClaimGroupSet = util.inherit( 'WbDataModelClaimGroupSet',
 	PARENT,

src/ClaimList.js

@@ -1,17 +1,18 @@
-/**
- * @licence GNU GPL v2+
- * @author H. Snater < mediawiki@snater.com >
- */
 ( function( wb, $ ) {
 'use strict';
 
 var PARENT = wb.datamodel.List;
 
 /**
- * @constructor
+ * List of Claim objects.
+ * @class wikibase.datamodel.ClaimList
  * @since 1.0
+ * @licence GNU GPL v2+
+ * @author H. Snater < mediawiki@snater.com >
+ *
+ * @constructor
  *
- * @param {wikibase.datamodel.Claim[]} [claims]
+ * @param {wikibase.datamodel.Claim[]} [claims=[]]
  */
 wb.datamodel.ClaimList = util.inherit( 'WbDataModelClaimList', PARENT, function( claims ) {
 	PARENT.call( this, wikibase.datamodel.Claim, claims );

src/Entity.js

@@ -1,33 +1,39 @@
-/**
- * @licence GNU GPL v2+
- * @author H. Snater < mediawiki@snater.com >
- */
 ( function( wb, $ ) {
 	'use strict';
 
 /**
- * @constructor
+ * Abstract Entity base class featuring an id and a fingerprint.
+ * @class wikibase.datamodel.Entity
  * @abstract
  * @since 0.3
+ * @licence GNU GPL v2+
+ * @author H. Snater < mediawiki@snater.com >
+ *
+ * @constructor
+ *
+ * @throws {Error} when trying to instantiate since Entity is abstract.
  */
 var SELF = wb.datamodel.Entity = function WbDataModelEntity() {
 	throw new Error( 'Cannot construct abstract Entity object' );
 };
 
 /**
  * String to identify this type of Entity.
- * @type {string}
+ * @property {string} [TYPE=null]
+ * @static
  */
 SELF.TYPE = null;
 
 $.extend( SELF.prototype, {
 	/**
-	 * @type {string}
+	 * @property {string}
+	 * @private
 	 */
 	_id: null,
 
 	/**
-	 * @type {wikibase.datamodel.Fingerprint}
+	 * @property {wikibase.datamodel.Fingerprint}
+	 * @private
 	 */
 	_fingerprint: null,
 
@@ -62,12 +68,16 @@ $.extend( SELF.prototype, {
 	},
 
 	/**
+	 * @abstract
+	 *
 	 * @return {boolean}
 	 */
 	isEmpty: util.abstractMember,
 
 	/**
-	 * @param {*}
+	 * @abstract
+	 *
+	 * @param {*} entity
 	 * @return {boolean}
 	 */
 	equals: util.abstractMember

src/EntityId.js

@@ -1,18 +1,22 @@
-/**
- * @licence GNU GPL v2+
- * @author Jeroen De Dauw < jeroendedauw@gmail.com >
- */
 ( function( wb, dv, util ) {
 	'use strict';
 
 var PARENT = dv.DataValue;
 
 /**
- * @constructor
+ * EntityId data value.
+ * @class wikibase.datamodel.EntityId
+ * @extends dataValues.DataValue
  * @since 0.3
+ * @licence GNU GPL v2+
+ * @author Jeroen De Dauw < jeroendedauw@gmail.com >
+ *
+ * @constructor
  *
  * @param {string} entityType
  * @param {number} numericId
+ *
+ * @throws {Error} if a required parameter is not specified properly.
  */
 wb.datamodel.EntityId = util.inherit(
 	'WbDataModelEntityId',
@@ -32,12 +36,14 @@ wb.datamodel.EntityId = util.inherit(
 	},
 {
 	/**
-	 * @type {string}
+	 * @property {string}
+	 * @private
 	 */
 	_entityType: null,
 
 	/**
-	 * @type {number}
+	 * @property {number}
+	 * @private
 	 */
 	_numericId: null,
 
@@ -60,6 +66,9 @@ wb.datamodel.EntityId = util.inherit(
 	 *        If the same entity type appears multiple times with different prefixes, the prefix
 	 *        found first will be applied.
 	 * @return {string}
+	 *
+	 * @throws {Error} when the prefix map does not contain a prefix for the entity type set on the
+	 *         object.
 	 */
 	getPrefixedId: function( prefixMap ) {
 		var entityType = this._entityType;
@@ -76,7 +85,7 @@ wb.datamodel.EntityId = util.inherit(
 	},
 
 	/**
-	 * @see dataValues.DataValue.equals
+	 * @inheritdoc
 	 */
 	equals: function( entityId ) {
 		return entityId === this
@@ -86,7 +95,7 @@ wb.datamodel.EntityId = util.inherit(
 	},
 
 	/**
-	 * @see dataValues.DataValue.getValue
+	 * @inheritdoc
 	 *
 	 * @return {wikibase.datamodel.EntityId}
 	 */
@@ -95,14 +104,14 @@ wb.datamodel.EntityId = util.inherit(
 	},
 
 	/**
-	 * @see dataValues.DataValue.getSortKey
+	 * @inheritdoc
 	 */
 	getSortKey: function() {
 		return this._entityType + this._numericId;
 	},
 
 	/**
-	 * @see dataValues.DataValue.toJSON
+	 * @inheritdoc
 	 */
 	toJSON: function() {
 		return {
@@ -113,12 +122,19 @@ wb.datamodel.EntityId = util.inherit(
 } );
 
 /**
- * @see dataValues.DataValue.newFromJSON
+ * @inheritdoc
+ * @static
+ *
+ * @return {wikibase.datamodel.EntityId}
  */
 wb.datamodel.EntityId.newFromJSON = function( json ) {
 	return new wb.datamodel.EntityId( json['entity-type'], json['numeric-id'] );
 };
 
+/**
+ * @inheritdoc
+ * @property {string} [TYPE='wikibase-entityid']
+ */
 wb.datamodel.EntityId.TYPE = 'wikibase-entityid';
 
 dv.registerDataValue( wb.datamodel.EntityId );