Begin JSDoc-ing core

lib/robot.js

@@ -17,15 +17,17 @@ var initializer = require("./initializer"),
 var Async = require("async"),
     EventEmitter = require("events").EventEmitter;
 
-// Public: Creates a new Robot
-//
-// opts - object containing Robot options
-//   name - optional, string name of the robot
-//   connection/connections - object connections to connect to
-//   device/devices - object devices to connect to
-//   work - work to be performed when the Robot is started
-//
-// Returns a new Robot
+/**
+ * Creates a new Robot instance based on provided options
+ *
+ * @constructor
+ * @param {Object} opts object with Robot options
+ * @param {String} [name] the name the robot should have
+ * @param {Object} [connections] object containing connection info for the Robot
+ * @param {Object} [devices] object containing device information for the Robot
+ * @param {Function} [work] a function the Robot will run when started
+ * @returns {Robot} new Robot instance
+ */
 var Robot = module.exports = function Robot(opts) {
   Utils.classCallCheck(this, Robot);
 
@@ -98,9 +100,12 @@ var Robot = module.exports = function Robot(opts) {
 
 Utils.subclass(Robot, EventEmitter);
 
-// Public: Generates a random name for a Robot.
-//
-// Returns a string name
+/**
+ * Generates a random name for a Robot.
+ *
+ * @todo should perhaps just increment a counter as a global value?
+ * @returns {String} a robot name
+ */
 Robot.randomName = function() {
   return "Robot " + (Math.floor(Math.random() * 100000));
 };
@@ -108,6 +113,12 @@ Robot.randomName = function() {
 // Public: Expresses the Robot in a JSON-serializable format
 //
 // Returns an Object containing Robot data
+
+/**
+ * Condenses information on a Robot to a JSON-serializable format
+ *
+ * @return {Object} serializable information on the Robot
+ */
 Robot.prototype.toJSON = function() {
   return {
     name: this.name,
@@ -118,6 +129,13 @@ Robot.prototype.toJSON = function() {
   };
 };
 
+/**
+ * Adds a new Connection to the Robot with the provided name and details.
+ *
+ * @param {String} name string name for the Connection to use
+ * @param {Object} conn options for the Connection initializer
+ * @return {Object} the robot
+ */
 Robot.prototype.connection = function(name, conn) {
   conn.robot = this;
   conn.name = name;
@@ -138,11 +156,12 @@ Robot.prototype.connection = function(name, conn) {
   return this;
 };
 
-// Public: Initializes all vars for robot
-//
-// opts - options array passed to constructor
-//
-// Returns null
+/**
+ * Initializes all values for a new Robot.
+ *
+ * @param {Object} opts object passed to Robot constructor
+ * @return {void}
+ */
 Robot.prototype.initRobot = function(opts) {
   this.name = opts.name || Robot.randomName();
   this.connections = {};
@@ -158,9 +177,12 @@ Robot.prototype.initRobot = function(opts) {
   }
 };
 
-// Public: Checks options for bad Cylon syntax
-//
-// Returns nothing
+/**
+ * Checks provided options object for invalid Robot details
+ *
+ * @param {Object} opts options object to check for errors
+ * @return {void}
+ */
 Robot.prototype.checkForBadSyntax = function(opts) {
   var self = this;
 
@@ -186,11 +208,12 @@ Robot.prototype.checkForBadSyntax = function(opts) {
   ["connection", "device"].forEach(checkForSingleObjectSyntax);
 };
 
-// Public: Initializes all connections for the robot
-//
-// opts - options array passed to constructor
-//
-// Returns initialized connections
+/**
+ * Initializes a Robot's connections
+ *
+ * @param {Object} opts object passed to constructor
+ * @return {Array} the Robot's connections
+ */
 Robot.prototype.initConnections = function(opts) {
   this.log("info", "Initializing connections.");
 
@@ -218,6 +241,13 @@ Robot.prototype.initConnections = function(opts) {
   return this.connections;
 };
 
+/**
+ * Adds a new Device to the Robot with the provided name and details.
+ *
+ * @param {String} name string name for the Device to use
+ * @param {Object} device options for the Device initializer
+ * @return {Object} the robot
+ */
 Robot.prototype.device = function(name, device) {
   var str;
 
@@ -253,11 +283,12 @@ Robot.prototype.device = function(name, device) {
   return this;
 };
 
-// Public: Initializes all devices for the robot
-//
-// opts - options array passed to constructor
-//
-// Returns initialized devices
+/**
+ * Initializes a Robot's devices
+ *
+ * @param {Object} opts object passed to constructor
+ * @return {Array} the Robot's devices
+ */
 Robot.prototype.initDevices = function(opts) {
   this.log("info", "Initializing devices.");
 
@@ -278,11 +309,13 @@ Robot.prototype.initDevices = function(opts) {
   return this.devices;
 };
 
-// Public: Starts the Robot working.
-//
-// Starts the connections, devices, and work.
-//
-// Returns the result of the work
+/**
+ * Starts the Robot's connections, then devices, then work.
+ *
+ * @param {Function} callback function to be triggered when the Robot has
+ * started working
+ * @return {Object} the Robot
+ */
 Robot.prototype.start = function(callback) {
   if (this.running) {
     return this;
@@ -324,11 +357,11 @@ Robot.prototype.start = function(callback) {
   return this;
 };
 
-// Public: Starts the Robot"s work and triggers a callback
-//
-// callback - callback function to be triggered
-//
-// Returns nothing
+/**
+ * Starts the Robot's work function
+ *
+ * @return {void}
+ */
 Robot.prototype.startWork = function() {
   this.log("info", "Working.");
 
@@ -337,11 +370,13 @@ Robot.prototype.startWork = function() {
   this.running = true;
 };
 
-// Public: Starts the Robot"s connections and triggers a callback
-//
-// callback - callback function to be triggered
-//
-// Returns nothing
+/**
+ * Starts the Robot's connections
+ *
+ * @param {Function} callback function to be triggered after the connections are
+ * started
+ * @return {void}
+ */
 Robot.prototype.startConnections = function(callback) {
   this.log("info", "Starting connections.");
 
@@ -365,11 +400,13 @@ Robot.prototype.startConnections = function(callback) {
   return Async.parallel(starters, callback);
 };
 
-// Public: Starts the Robot"s devices and triggers a callback
-//
-// callback - callback function to be triggered
-//
-// Returns nothing
+/**
+ * Starts the Robot's devices
+ *
+ * @param {Function} callback function to be triggered after the devices are
+ * started
+ * @return {void}
+ */
 Robot.prototype.startDevices = function(callback) {
   var log = this.log;
 
@@ -393,13 +430,12 @@ Robot.prototype.startDevices = function(callback) {
   return Async.parallel(starters, callback);
 };
 
-// Public: Halts the Robot.
-//
-// Halts the devices, disconnects the connections.
-//
-// callback - callback to be triggered when the Robot is stopped
-//
-// Returns nothing
+/**
+ * Halts the Robot, attempting to gracefully stop devices and connections.
+ *
+ * @param {Function} callback to be triggered when the Robot has stopped
+ * @return {void}
+ */
 Robot.prototype.halt = function(callback) {
   callback = callback || function() {};
 
@@ -423,9 +459,11 @@ Robot.prototype.halt = function(callback) {
   this.running = false;
 };
 
-// Public: Returns basic info about the robot as a String
-//
-// Returns a String
+/**
+ * Generates a String representation of a Robot
+ *
+ * @return {String} representation of a Robot
+ */
 Robot.prototype.toString = function() {
   return "[Robot name='" + this.name + "']";
 };