Add more documentation

Signed-off-by: Eli Skeggs <eskeggs@globesherpa.com>

lib/discovery.js

@@ -33,6 +33,11 @@ var _ = require('underscore');
 
 var reservedEvents = {'promotion': true, 'demotion': true, 'added': true, 'removed': true, 'master': true, 'hello': true};
 
+/**
+ * The default options for Discovery.
+ *
+ * @type {Object<string, *>}
+ */
 var defaults = {
   helloInterval: 1000,
   checkInterval: 2000,
@@ -47,7 +52,15 @@ var defaults = {
   mastersRequired: 1
 };
 
-var Discovery = function(options) {
+/**
+ * The Discovery constructor, which enables the discovery of other Discovery
+ * network-wide, and includes advertisement and automatic master selection.
+ *
+ * @param {Object<string, *>=} options The options to construct a Discovery.
+ * @constructor
+ * @extends EventEmitter
+ */
+var Discovery = function Discovery(options) {
   if (!(this instanceof Discovery))
     return new Discovery(options);
 
@@ -182,64 +195,103 @@ var Discovery = function(options) {
   this.start();
 };
 
+// Discovery inherits from EventEmitter
 util.inherits(Discovery, EventEmitter);
 
-
+/**
+ * Promotes this Discovery instance to master.
+ */
 Discovery.prototype.promote = function() {
   this.me.isMasterEligible = true;
   this.me.isMaster = true;
   this.emit('promotion', this.me);
   this.hello();
 };
 
+/**
+ * Demotes this Discovery instance from master.
+ */
 Discovery.prototype.demote = function(permanent) {
   this.me.isMasterEligible = !permanent;
   this.me.isMaster = false;
   this.emit('demotion', this.me);
   this.hello();
 };
 
+/**
+ * Broadcasts a 'hello' message.
+ */
 Discovery.prototype.hello = function() {
   this.broadcast.send('hello', this.me);
 };
 
+/**
+ * Sets the advertisement data.
+ *
+ * @param {!Object<string, *>} obj The advertisement data.
+ */
 Discovery.prototype.advertise = function(obj) {
   this.me.info = obj;
 };
 
+/**
+ * Subscribes to the specified channel. The channel name cannot be a reserved
+ * name.
+ *
+ * This method will throw an error if the channel is reserved.
+ *
+ * @param {!string} channel The channel to subscribe to.
+ * @param {function(obj)} fn The callback function.
+ */
 Discovery.prototype.join = function(channel, fn) {
   var self = this;
 
-  if (reservedEvents[channel] || this.channels[channel])
-    return false;
+  if (reservedEvents[channel])
+    throw new TypeError('that channel is a reserved channel');
 
   if (fn)
     this.on(channel, fn);
 
-  this.broadcast.on(channel, function(obj) {
-    self.emit(channel, obj);
-  });
-
-  this.channels[channel] = true;
+  if (!this.channels[channel]) {
+    this.broadcast.on(channel, function(obj) {
+      self.emit(channel, obj);
+    });
 
-  return true;
+    this.channels[channel] = true;
+  }
 };
 
+/**
+ * Unsubscribes from the specified channel. The channel name cannot be a
+ * reserved name.
+ *
+ * This method will remove all listeners for the given channel!
+ *
+ * @param {!string} channel The channel to unsubscribe from.
+ */
 Discovery.prototype.leave = function(channel) {
-  this.broadcast.removeAllListeners(channel);
+  if (!reservedEvents[channel]) {
+    this.removeAllListeners(channel);
+    this.broadcast.removeAllListeners(channel);
 
-  delete this.channels[channel];
-
-  return true;
+    delete this.channels[channel];
+  }
 };
 
+/**
+ * Sends the object to the specified channel. The channel name cannot be a
+ * reserved name.
+ *
+ * This method will throw an error if the channel is reserved.
+ *
+ * @param {!string} channel The channel to send on.
+ * @param {!Object<string, *>} obj The object to broadcast.
+ */
 Discovery.prototype.send = function(channel, obj) {
   if (reservedEvents[channel])
-    return false;
+    throw new TypeError('that channel is a reserved channel');
 
   this.broadcast.send(channel, obj);
-
-  return true;
 };
 
 module.exports = Discovery;