Add Client and ClientBatch API docs.

lib/client.js

@@ -1,3 +1,8 @@
+/**
+ * Yeti Hub Client.
+ * @module client
+ */
+
 "use strict";
 
 var fs = require("graceful-fs");
@@ -6,6 +11,14 @@ var EventEmitter2 = require("eventemitter2").EventEmitter2;
 
 var Blizzard = require("./blizzard");
 
+/**
+ * The Client submits test batches to a Yeti Hub and tracks their progress.
+ *
+ * @class Client
+ * @constructor
+ * @extends EventEmitter2
+ * @param {String} url Yeti Hub HTTP URL.
+ */
 function Client(url) {
     EventEmitter2.call(this);
 
@@ -20,6 +33,30 @@ function Client(url) {
 
 util.inherits(Client, EventEmitter2);
 
+/**
+ * Something went wrong.
+ * @event error
+ * @param {Error} error The error object.
+ */
+
+/**
+ * An agent connected to the Hub.
+ * @event agentConnect
+ * @param {String} agent Agent name.
+ */
+
+/**
+ * An agent disconnected from the Hub.
+ * @event agentDisconnect
+ * @param {String} agent Agent name.
+ */
+
+/**
+ * Connect to the Yeti Hub.
+ *
+ * @method connect
+ * @param {Function} cb Callback function.
+ */
 Client.prototype.connect = function (cb) {
     var self = this;
     self.blizzard.connect(self.url, function (err, session) {
@@ -37,7 +74,10 @@ Client.prototype.connect = function (cb) {
     });
 };
 
-
+/**
+ * @method handleBlizzardError
+ * @protected
+ */
 Client.prototype.handleBlizzardError = function (err) {
     if (err.code === "ECONNRESET") {
         this.emit("error", new Error("Server does not speak Yeti's protocol. Version mismatch?"));
@@ -46,6 +86,13 @@ Client.prototype.handleBlizzardError = function (err) {
     this.emit("error", err);
 };
 
+/**
+ * Create and submit a batch of tests to the Hub.
+ *
+ * @method createBatch
+ * @param {Object} config Batch information. Must contain basedir (String) and tests (Array) properties.
+ * @return {ClientBatch} batch The new ClientBatch object.
+ */
 Client.prototype.createBatch = function (config) {
     // TODO check if connection happened!
     // this.session may not yet exist
@@ -56,6 +103,16 @@ Client.prototype.createBatch = function (config) {
     return new ClientBatch(this.session, config.basedir, config.tests);
 };
 
+/**
+ * The ClientBatch represents a batch on the Hub.
+ *
+ * @class ClientBatch
+ * @constructor
+ * @extends EventEmitter2
+ * @param {BlizzardSession} session Connected Blizzard session to the Hub.
+ * @param {String} basedir The base path to serve tests from.
+ * @param {Array} tests An array of string paths of test files.
+ */
 function ClientBatch(session, basedir, tests) {
     if (!basedir) {
         throw new Error("Basedir required.");
@@ -82,6 +139,47 @@ function ClientBatch(session, basedir, tests) {
 
 util.inherits(ClientBatch, EventEmitter2);
 
+/**
+ * Something went wrong.
+ * @event error
+ * @param {Error} error The error object.
+ */
+
+/**
+ * The batch is complete. No more events will be fired.
+ * @event complete
+ * @param {BlizzardNamespace} session Blizzard session namespace for the batch.
+ */
+
+/**
+ * The agent given has completed testing.
+ * @event agentComplete
+ * @param {BlizzardNamespace} session Blizzard session namespace for the batch.
+ * @param {String} agent Agent name.
+ */
+
+/**
+ * Test result from an agent.
+ * @event agentResult
+ * @param {BlizzardNamespace} session Blizzard session namespace for the batch.
+ * @param {String} agent Agent name.
+ * @param {Object} details Test result details, in YUI Test JSON format.
+ */
+
+/**
+ * Uncaught JavaScript error from an agent.
+ * @event agentScriptError
+ * @param {BlizzardNamespace} session Blizzard session namespace for the batch.
+ * @param {String} agent Agent name.
+ * @param {Object} details Exception details. Contains url, line and message properties.
+ */
+
+/**
+ * @method onAck
+ * @protected
+ * @param {Error} err
+ * @param {Number} id
+ */
 ClientBatch.prototype.onAck = function (err, id) {
     var self = this;
 
@@ -105,6 +203,13 @@ ClientBatch.prototype.onAck = function (err, id) {
     self.provideTests();
 };
 
+/**
+ * Setup BlizzardNamespace event listener that will
+ * serve local test files under this.basedir.
+ *
+ * @method provideTests
+ * @protected
+ */
 ClientBatch.prototype.provideTests = function () {
     var self = this;
 
@@ -115,8 +220,19 @@ ClientBatch.prototype.provideTests = function () {
 
 };
 
+/**
+ * @class exports
+ * @static
+ */
 exports.Client = Client;
 
+/**
+ * Create a new Yeti Client instance.
+ *
+ * @method createClient
+ * @param {String} url Yeti Hub HTTP URL.
+ * @return {Client} client Yeti Client instance.
+ */
 exports.createClient = function (url) {
     return new Client(url);
 };