Ori.livneh has uploaded a new change for review.
https://gerrit.wikimedia.org/r/50705
Change subject: jsduck-ify comments in ext.eventLogging.core.js
......................................................................
jsduck-ify comments in ext.eventLogging.core.js
I don't love jsduck, but using a syntax that *can* compile into documentation
beats a purely formal syntactic convention with no application. So, ok.
Also renames 'isInstance' to 'isInstanceOf' and renames its first argument from
'instance' to 'value'.
Change-Id: I265d3962155b89d6890b7aedf749983ba124fa79
---
M modules/ext.eventLogging.core.js
1 file changed, 31 insertions(+), 27 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/EventLogging
refs/changes/05/50705/1
diff --git a/modules/ext.eventLogging.core.js b/modules/ext.eventLogging.core.js
index d255c6b..6673e85 100644
--- a/modules/ext.eventLogging.core.js
+++ b/modules/ext.eventLogging.core.js
@@ -1,4 +1,6 @@
/**
+ * ext.eventLogging.core.js
+ * ------------------------
* Logs arbitrary events from client-side code to server. Each event
* must validate against a predeclared data model, specified as JSON
* Schema (version 3 of the draft).
@@ -11,6 +13,7 @@
/**
* @constructor
+ * Error thrown on JSON Schema validation failures.
* @extends Error
**/
function ValidationError( message ) {
@@ -40,8 +43,10 @@
/**
* Declares event schema.
- * @param {Object} schemas Schema specified as JSON Schema
- * @param integer revision
+ * @param {String} schemaName Name of schema.
+ * @param {Object} meta An object describing a schema:
+ * @param {Number} [meta.revision] Revision ID.
+ * @param {Object} [meta.schema] The schema itself.
* @return {Object}
*/
setSchema: function ( schemaName, meta ) {
@@ -59,28 +64,28 @@
/**
* @param {Object} instance Object to test.
- * @param {string} type JSON Schema type specifier.
- * @return {boolean}
+ * @param {String} type JSON Schema type.
+ * @return {Boolean}
*/
- isInstance: function ( instance, type ) {
+ isInstanceOf: function ( value, type ) {
// undefined and null are invalid values for any type.
- if ( instance === undefined || instance === null ) {
+ if ( value === undefined || value === null ) {
return false;
}
switch ( type ) {
case 'string':
- return typeof instance === 'string';
+ return typeof value === 'string';
case 'timestamp':
- return instance instanceof Date || (
- typeof instance === 'number' &&
- instance >= 0 &&
- instance % 1 === 0 );
+ return value instanceof Date || (
+ typeof value === 'number' &&
+ value >= 0 &&
+ value % 1 === 0 );
case 'boolean':
- return typeof instance === 'boolean';
+ return typeof value === 'boolean';
case 'integer':
- return typeof instance === 'number' && instance
% 1 === 0;
+ return typeof value === 'number' && value % 1
=== 0;
case 'number':
- return typeof instance === 'number' &&
isFinite( instance );
+ return typeof value === 'number' && isFinite(
instance );
default:
return false;
}
@@ -89,8 +94,8 @@
/**
* @param {Object} event Event to test for validity.
- * @param {Object} schemaName Name of schema.
- * @returns {boolean}
+ * @param {String} schemaName Name of schema.
+ * @return {Boolean}
*/
isValid: function ( event, schemaName ) {
try {
@@ -135,7 +140,7 @@
return true;
}
- if ( !( self.isInstance( val, desc.type ) ) ) {
+ if ( !( self.isInstanceOf( val, desc.type ) ) )
{
throw new ValidationError( 'Wrong type
for property: ' + prop + ' ' + val );
}
@@ -154,9 +159,9 @@
* complete event object (including defaults) is validated
prior to
* dispatch.
*
- * @param {string} schemaName Canonical schema name.
+ * @param {String} schemaName Canonical schema name.
* @param {Object|null} schemaDefaults Defaults, or null to
clear.
- * @returns {Object} Updated defaults for schema.
+ * @return {Object} Updated defaults for schema.
*/
setDefaults: function ( schemaName, schemaDefaults ) {
var schema = self.getSchema( schemaName );
@@ -169,9 +174,11 @@
/**
- * @param {string} schemaName Canonical schema name.
+ * Takes an event object and puts it inside a generic wrapper
+ * object that contains generic metadata about the event.
+ * @param {String} schemaName Canonical schema name.
* @param {Object} event Event instance.
- * @returns {Object} Encapsulated event.
+ * @return {Object} Encapsulated event.
*/
encapsulate: function ( schemaName, event ) {
var schema = self.getSchema( schemaName );
@@ -197,7 +204,7 @@
/**
* Pushes data to server as URL-encoded JSON.
* @param {Object} data Payload to send.
- * @returns {jQuery.Deferred} Promise object.
+ * @return {jQuery.Deferred} Promise object.
*/
dispatch: function ( data ) {
var beacon = document.createElement( 'img' ),
@@ -205,9 +212,6 @@
dfd = $.Deferred();
if ( !baseUri ) {
- // We already logged the fact of
wgEventLoggingBaseUri being
- // empty, so respect the caller's expectation
and return a
- // rejected promise.
dfd.rejectWith( data, [ data ] );
return dfd.promise();
}
@@ -225,9 +229,9 @@
/**
- * @param {string} schemaName Canonical schema name.
+ * @param {String} schemaName Canonical schema name.
* @param {Object} eventInstance Event instance.
- * @returns {jQuery.Deferred} Promise object.
+ * @return {jQuery.Deferred} Promise object.
*/
logEvent: function ( schemaName, eventInstance ) {
return self.dispatch( self.encapsulate( schemaName,
eventInstance ) );
--
To view, visit https://gerrit.wikimedia.org/r/50705
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I265d3962155b89d6890b7aedf749983ba124fa79
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/extensions/EventLogging
Gerrit-Branch: master
Gerrit-Owner: Ori.livneh <o...@wikimedia.org>
_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
