Update gobot package docs

adaptor.go

@@ -23,7 +23,11 @@ type AdaptorInterface interface {
 	ToJSON() *JSONConnection
 }
 
-// NewAdaptor returns a new Gobot Adaptor
+// NewAdaptor returns a new Adaptor given a name, adaptorType and optionally accepts:
+//
+//	string: Port the adaptor connects to
+//
+// adaptorType is a label used for identification in the api
 func NewAdaptor(name string, adaptorType string, v ...interface{}) *Adaptor {
 	if name == "" {
 		name = fmt.Sprintf("%X", Rand(int(^uint(0)>>1)))
@@ -70,7 +74,7 @@ func (a *Adaptor) Type() string {
 	return a.adaptorType
 }
 
-// Connected returns true if adaptor is connected
+// Connected returns true if the adaptor is connected
 func (a *Adaptor) Connected() bool {
 	return a.connected
 }
@@ -80,7 +84,7 @@ func (a *Adaptor) SetConnected(b bool) {
 	a.connected = b
 }
 
-// ToJSON returns a json representation of adaptor
+// ToJSON returns a json representation of an adaptor
 func (a *Adaptor) ToJSON() *JSONConnection {
 	return &JSONConnection{
 		Name:    a.Name(),

doc.go

@@ -2,14 +2,9 @@
 
 /*
 Package gobot provides a framework for robotics, physical computing and the internet of things.
-It is the main point of entry in your Gobot application. A Gobot
+It is the main point of entry for your Gobot application. A Gobot program
 is typically composed of one or more robots that makes up a project.
 
-Commands are a way to expose your robots functionality with the external world.
-A Gobot can be configured to expose a restful HTTP interface using the api
-package. You can define custom commands on your Gobot and interact with your
-application as a web service.
-
 Basic Setup
 
     package main
@@ -35,71 +30,76 @@ Basic Setup
       gbot.Start()
     }
 
-Web Enabled? You bet!
+Blinking an LED (Hello Eve!)
 
     package main
 
     import (
-    	"fmt"
+    	"time"
 
     	"github.com/hybridgroup/gobot"
-    	"github.com/hybridgroup/gobot/api"
+    	"github.com/hybridgroup/gobot/platforms/firmata"
+    	"github.com/hybridgroup/gobot/platforms/gpio"
     )
 
     func main() {
     	gbot := gobot.NewGobot()
 
-      // Starts the API server on default port 3000
-    	api.NewAPI(gbot).Start()
+    	firmataAdaptor := firmata.NewFirmataAdaptor("arduino", "/dev/ttyACM0")
+    	led := gpio.NewLedDriver(firmataAdaptor, "led", "13")
 
-      // Accessible via http://localhost:3000/api/commands/say_hello
-    	gbot.AddCommand("say_hello", func(params map[string]interface{}) interface{} {
-    		return "Master says hello!"
-    	})
+    	work := func() {
+    		gobot.Every(1*time.Second, func() {
+    			led.Toggle()
+    		})
+    	}
 
-    	hello := gbot.AddRobot(gobot.NewRobot("Eve"))
+    	robot := gobot.NewRobot("Eve",
+    		[]gobot.Connection{firmataAdaptor},
+    		[]gobot.Device{led},
+    		work,
+    	)
 
-      // Accessible via http://localhost:3000/robots/Eve/commands/say_hello
-    	hello.AddCommand("say_hello", func(params map[string]interface{}) interface{} {
-    		return fmt.Sprintf("%v says hello!", hello.Name)
-    	})
+    	gbot.AddRobot(robot)
 
     	gbot.Start()
     }
 
-Blinking teh LED (Hello Eve!)
+Web Enabled? You bet! Gobot can be configured to expose a restful HTTP interface
+using the api package. You can define custom commands on your robots, in addition
+to the built-in device driver commands, and interact with your application as a
+web service.
+
 
     package main
 
     import (
-    	"time"
+    	"fmt"
 
     	"github.com/hybridgroup/gobot"
-    	"github.com/hybridgroup/gobot/platforms/firmata"
-    	"github.com/hybridgroup/gobot/platforms/gpio"
+    	"github.com/hybridgroup/gobot/api"
     )
 
     func main() {
     	gbot := gobot.NewGobot()
 
-    	firmataAdaptor := firmata.NewFirmataAdaptor("arduino", "/dev/ttyACM0")
-    	led := gpio.NewLedDriver(firmataAdaptor, "led", "13")
+      // Starts the API server on default port 3000
+    	api.NewAPI(gbot).Start()
 
-    	work := func() {
-    		gobot.Every(1*time.Second, func() {
-    			led.Toggle()
-    		})
-    	}
+      // Accessible via http://localhost:3000/api/commands/say_hello
+    	gbot.AddCommand("say_hello", func(params map[string]interface{}) interface{} {
+    		return "Master says hello!"
+    	})
 
-    	robot := gobot.NewRobot("Eve",
-    		[]gobot.Connection{firmataAdaptor},
-    		[]gobot.Device{led},
-    		work,
-    	)
+    	hello := gbot.AddRobot(gobot.NewRobot("Eve"))
 
-    	gbot.AddRobot(robot)
+      // Accessible via http://localhost:3000/robots/Eve/commands/say_hello
+    	hello.AddCommand("say_hello", func(params map[string]interface{}) interface{} {
+    		return fmt.Sprintf("%v says hello!", hello.Name)
+    	})
 
     	gbot.Start()
     }
+
 */
 package gobot

driver.go

@@ -36,8 +36,13 @@ type Driver struct {
 	driverType string
 }
 
-// NewDriver returns a Driver with specified parameters
-// and sets driver pin, adaptor and interval
+// NewDriver returns a new Driver given a name, driverType and optionally accepts:
+//
+//	string: Pin the driver connects to
+//	AdaptorInterface: Adaptor the driver connects to
+//	time.Duration: Interval used internally for polling where applicable
+//
+// driverType is a label used for identification in the api
 func NewDriver(name string, driverType string, v ...interface{}) *Driver {
 	if name == "" {
 		name = fmt.Sprintf("%X", Rand(int(^uint(0)>>1)))

event.go

@@ -10,8 +10,7 @@ type Event struct {
 	Callbacks []callback
 }
 
-// NewEvent generates a new event by making a channel
-// and start reading from it
+// NewEvent returns a new event which is then ready for publishing and subscribing.
 func NewEvent() *Event {
 	e := &Event{
 		Chan:      make(chan interface{}, 1),
@@ -25,16 +24,15 @@ func NewEvent() *Event {
 	return e
 }
 
-// Writes sends event data to channel
+// Write writes data to the Event
 func (e *Event) Write(data interface{}) {
 	select {
 	case e.Chan <- data:
 	default:
 	}
 }
 
-// Read waits data from channel and execute callbacks
-// for each event when received
+// Read publishes to all subscribers of e if there is any new data
 func (e *Event) Read() {
 	for s := range e.Chan {
 		tmp := []callback{}

gobot.go

@@ -19,7 +19,7 @@ type Gobot struct {
 	trap     func(chan os.Signal)
 }
 
-// NewGobot instantiates a new Gobot
+// NewGobot returns a new Gobot
 func NewGobot() *Gobot {
 	return &Gobot{
 		robots:   &robots{},
@@ -45,17 +45,19 @@ func (g *Gobot) AddCommand(name string, f func(map[string]interface{}) interface
 	g.commands[name] = f
 }
 
-// Commands lists all available commands on this Gobot instance.
+// Commands returns all available commands on this Gobot.
 func (g *Gobot) Commands() map[string]func(map[string]interface{}) interface{} {
 	return g.commands
 }
 
-// Command fetch the associated command using the given command name
+// Command reutnrs a command given a name.
 func (g *Gobot) Command(name string) func(map[string]interface{}) interface{} {
 	return g.commands[name]
 }
 
-// Start runs the main Gobot event loop
+// Start calls the Start method on each robot in it's collection of robots, and
+// stops all robots on reception of a SIGINT. Start will block the execution of
+// your main function until it receives the SIGINT.
 func (g *Gobot) Start() {
 	g.robots.Start()
 
@@ -71,18 +73,19 @@ func (g *Gobot) Start() {
 	})
 }
 
-// Robots fetch all robots associated with this Gobot instance.
+// Robots returns all robots associated with this Gobot instance.
 func (g *Gobot) Robots() *robots {
 	return g.robots
 }
 
-// AddRobot adds a new robot to our Gobot instance.
+// AddRobot adds a new robot to the internal collection of robots. Returns the
+// added robot
 func (g *Gobot) AddRobot(r *Robot) *Robot {
 	*g.robots = append(*g.robots, r)
 	return r
 }
 
-// Robot find a robot with a given name.
+// Robot returns a robot given name. Returns nil on no robot.
 func (g *Gobot) Robot(name string) *Robot {
 	for _, robot := range *g.Robots() {
 		if robot.Name == name {
@@ -92,7 +95,7 @@ func (g *Gobot) Robot(name string) *Robot {
 	return nil
 }
 
-// ToJSON retrieves a JSON representation of this Gobot.
+// ToJSON returns a JSON representation of this Gobot.
 func (g *Gobot) ToJSON() *JSONGobot {
 	jsonGobot := &JSONGobot{
 		Robots:   []*JSONRobot{},

robot.go

@@ -13,9 +13,9 @@ type JSONRobot struct {
 	Devices     []*JSONDevice     `json:"devices"`
 }
 
-// Robot software representation of a physical board. A robot is a named
-// entitity that manages multiple IO devices using a set of adaptors. Additionally
-// a user can specificy custom commands to control a robot remotely.
+// Robot is a named entitity that manages a collection of connections and devices.
+// It containes it's own work routine and a collection of
+// custom commands to control a robot remotely via the Gobot api.
 type Robot struct {
 	Name        string
 	commands    map[string]func(map[string]interface{}) interface{}
@@ -46,8 +46,11 @@ func (r *robots) Each(f func(*Robot)) {
 	}
 }
 
-// NewRobot constructs a new named robot. Though a robot's name will be generated,
-// we recommend that user take care of naming a robot for later access.
+// NewRobot returns a new Robot given a name and optionally accepts:
+//
+// 	[]Connection: Connections which are automatically started and stopped with the robot
+//	[]Device: Devices which are automatically started and stopped with the robot
+//	func(): The work routine the robot will execute once all devices and connections have been initialized and started
 func NewRobot(name string, v ...interface{}) *Robot {
 	if name == "" {
 		name = fmt.Sprintf("%X", Rand(int(^uint(0)>>1)))
@@ -87,24 +90,22 @@ func NewRobot(name string, v ...interface{}) *Robot {
 	return r
 }
 
-// AddCommand setup a new command that we be made available via the REST api.
+// AddCommand adds a new command to the robot's collection of commands
 func (r *Robot) AddCommand(name string, f func(map[string]interface{}) interface{}) {
 	r.commands[name] = f
 }
 
-// Commands lists out all available commands on this robot.
+// Commands returns all available commands on the robot.
 func (r *Robot) Commands() map[string]func(map[string]interface{}) interface{} {
 	return r.commands
 }
 
-// Command fetch a named command on this robot.
+// Command returns the command given a name.
 func (r *Robot) Command(name string) func(map[string]interface{}) interface{} {
 	return r.commands[name]
 }
 
-// Start a robot instance and runs it's work function if any. You should not
-// need to manually start a robot if already part of a Gobot application as the
-// robot will be automatically started for you.
+// Start starts all the robot's connections and drivers and runs it's work function.
 func (r *Robot) Start() {
 	log.Println("Starting Robot", r.Name, "...")
 	if err := r.Connections().Start(); err != nil {
@@ -119,18 +120,19 @@ func (r *Robot) Start() {
 	}
 }
 
-// Devices retrieves all devices associated with this robot.
+// Devices returns all devices associated with this robot.
 func (r *Robot) Devices() *devices {
 	return r.devices
 }
 
-// AddDevice adds a new device on this robot.
+// AddDevice adds a new device to the robots collection of devices. Returns the
+// added device.
 func (r *Robot) AddDevice(d Device) Device {
 	*r.devices = append(*r.Devices(), d)
 	return d
 }
 
-// Device finds a device by name.
+// Device returns a device given a name. Returns nil on no device.
 func (r *Robot) Device(name string) Device {
 	if r == nil {
 		return nil
@@ -143,18 +145,19 @@ func (r *Robot) Device(name string) Device {
 	return nil
 }
 
-// Connections retrieves all connections on this robot.
+// Connections returns all connections associated with this robot.
 func (r *Robot) Connections() *connections {
 	return r.connections
 }
 
-// AddConnection add a new connection on this robot.
+// AddConnection adds a new connection to the robots collection of connections.
+// Returns the added connection.
 func (r *Robot) AddConnection(c Connection) Connection {
 	*r.connections = append(*r.Connections(), c)
 	return c
 }
 
-// Connection finds a connection by name.
+// Connection returns a connection given a name. Returns nil on no connection.
 func (r *Robot) Connection(name string) Connection {
 	if r == nil {
 		return nil
@@ -167,7 +170,7 @@ func (r *Robot) Connection(name string) Connection {
 	return nil
 }
 
-// ToJSON returns a JSON representation of the master robot.
+// ToJSON returns a JSON representation of the robot.
 func (r *Robot) ToJSON() *JSONRobot {
 	jsonRobot := &JSONRobot{
 		Name:        r.Name,