Add TomDoc to Cylon

src/cylon.coffee

@@ -17,27 +17,59 @@ require('./api/api')
 
 Logger.setup()
 
+# Cylon is the global namespace for the project, and also in charge of
+# maintaining the Master singleton that controls all the robots.
 class Cylon
   instance = null
 
+  # Public: Fetches singleton instance of Master, or creates a new one if it
+  # doesn't already exist
+  #
+  # Returns a Master instance
   @getInstance: (args...) ->
     instance ?= new Master(args...)
 
+  # The Master class is our puppeteer that manages all the robots, as well as
+  # starting them and the API.
   class Master
     robots = []
     api = null
 
+    # Public: Creates a new Master
+    #
+    # Returns a Master instance
     constructor: ->
       @self = this
 
+    # Public: Creates a new Robot
+    #
+    # opts - hash of Robot attributes
+    #
+    # Returns a shiny new Robot
+    # Examples:
+    #   Cylon.robot
+    #     connection: { name: 'arduino', adaptor: 'firmata' }
+    #     device: { name: 'led', driver: 'led', pin: 13 }
+    #
+    #     work: (me) ->
+    #       me.led.toggle()
     robot: (opts) =>
       opts.master = this
       robot = new Robot(opts)
       robots.push robot
       robot
 
+    # Public: Returns all Robots the Master knows about
+    #
+    # Returns an array of all Robot instances
     robots: -> robots
 
+    # Public: Finds a particular robot by name
+    #
+    # name - name of the robot to find
+    # callback - optional callback to be executed
+    #
+    # Returns the found Robot or result of the callback if it's supplied
     findRobot: (name, callback) ->
       robot = null
       for bot in robots
@@ -47,6 +79,13 @@ class Cylon
 
       if callback then callback(error, robot) else robot
 
+    # Public: Finds a particular Robot's device by name
+    #
+    # robotid - name of the robot to find
+    # deviceid - name of the device to find
+    # callback - optional callback to be executed
+    #
+    # Returns the found Device or result of the callback if it's supplied
     findRobotDevice: (robotid, deviceid, callback) ->
       @findRobot robotid, (err, robot) ->
         callback(err, robot) if err
@@ -57,6 +96,13 @@ class Cylon
 
         if callback then callback(error, device) else device
 
+    # Public: Finds a particular Robot's connection by name
+    #
+    # robotid - name of the robot to find
+    # connid - name of the device to find
+    # callback - optional callback to be executed
+    #
+    # Returns the found Connection or result of the callback if it's supplied
     findRobotConnection: (robotid, connid, callback) ->
       @findRobot robotid, (err, robot) ->
         callback(err, robot) if err
@@ -67,10 +113,17 @@ class Cylon
 
         if callback then callback(error, connection) else connection
 
+    # Public: Starts up the API and the robots
+    #
+    # Returns nothing
     start: ->
       do @startAPI
       robot.start() for robot in robots
 
+    # Creates a new instance of the Cylon API server, or returns the
+    # already-existing one.
+    #
+    # Returns an Api.Server instance
     startAPI: ->
       api ?= new Api.Server(master: @self)