From 6cccc41aff034c3bb2f160d1207079b13d3e3ffb Mon Sep 17 00:00:00 2001 From: Andrew Stewart Date: Mon, 8 Jun 2015 22:57:49 -0700 Subject: [PATCH] Begin JSDoc-ing core --- lib/robot.js | 158 ++++++++++++++++++++++++++++++++------------------- 1 file changed, 98 insertions(+), 60 deletions(-) diff --git a/lib/robot.js b/lib/robot.js index bafb75d..4b7ce8b 100644 --- a/lib/robot.js +++ b/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 + "']"; };