go lint and documentation tweaks for the gobot package

adaptor.go

@@ -1,11 +1,16 @@
 package gobot
 
+// Adaptor is the interface that describes an adaptor in gobot
 type Adaptor interface {
-	Finalize() []error
-	Connect() []error
+	// Name returns the label for the Adaptor
 	Name() string
+	// Connect initiates the Adaptor
+	Connect() []error
+	// Finalize terminates the Adaptor
+	Finalize() []error
 }
 
+// Porter is the interface that describes an adaptor's port
 type Porter interface {
 	Port() string
 }

commander.go

@@ -4,30 +4,33 @@ type commander struct {
 	commands map[string]func(map[string]interface{}) interface{}
 }
 
+// Commander is the interface which describes the behaviour for a Driver or Adaptor
+// which exposes API commands.
 type Commander interface {
+	// Command returns a command given a name. Returns nil if the command is not found.
 	Command(string) (command func(map[string]interface{}) interface{})
+	// Commands returns a map of commands.
 	Commands() (commands map[string]func(map[string]interface{}) interface{})
+	// AddCommand adds a command given a name.
 	AddCommand(name string, command func(map[string]interface{}) interface{})
 }
 
+// NewCommander returns a new Commander.
 func NewCommander() Commander {
 	return &commander{
 		commands: make(map[string]func(map[string]interface{}) interface{}),
 	}
 }
 
-// Command retrieves a command by name
 func (c *commander) Command(name string) (command func(map[string]interface{}) interface{}) {
 	command, _ = c.commands[name]
 	return
 }
 
-// Commands returns a map of driver commands
 func (c *commander) Commands() map[string]func(map[string]interface{}) interface{} {
 	return c.commands
 }
 
-// AddCommand links specified command name to `f`
 func (c *commander) AddCommand(name string, command func(map[string]interface{}) interface{}) {
 	c.commands[name] = command
 }

connection.go

@@ -1,44 +1,45 @@
 package gobot
 
 import (
-	"errors"
 	"fmt"
 	"log"
 	"reflect"
 )
 
-// JSONConnection holds a JSON representation of a connection.
+// JSONConnection is a JSON representation of a Connection.
 type JSONConnection struct {
 	Name    string `json:"name"`
 	Adaptor string `json:"adaptor"`
 }
 
-// ToJSON returns a json representation of an adaptor
+// NewJSONConnection returns a JSONConnection given a Connection.
 func NewJSONConnection(connection Connection) *JSONConnection {
 	return &JSONConnection{
 		Name:    connection.Name(),
 		Adaptor: reflect.TypeOf(connection).String(),
 	}
 }
 
+// A Connection is an instance of an Adaptor
 type Connection Adaptor
 
-type connections []Connection
+// Connections represents a collection of Connection
+type Connections []Connection
 
 // Len returns connections length
-func (c *connections) Len() int {
+func (c *Connections) Len() int {
 	return len(*c)
 }
 
-// Each calls function for each connection
-func (c *connections) Each(f func(Connection)) {
+// Each enumerates through the Connections and calls specified callback function.
+func (c *Connections) Each(f func(Connection)) {
 	for _, connection := range *c {
 		f(connection)
 	}
 }
 
-// Start initializes all the connections.
-func (c *connections) Start() (errs []error) {
+// Start calls Connect on each Connection in c
+func (c *Connections) Start() (errs []error) {
 	log.Println("Starting connections...")
 	for _, connection := range *c {
 		info := "Starting connection " + connection.Name()
@@ -51,20 +52,20 @@ func (c *connections) Start() (errs []error) {
 
 		if errs = connection.Connect(); len(errs) > 0 {
 			for i, err := range errs {
-				errs[i] = errors.New(fmt.Sprintf("Connection %q: %v", connection.Name(), err))
+				errs[i] = fmt.Errorf("Connection %q: %v", connection.Name(), err)
 			}
 			return
 		}
 	}
 	return
 }
 
-// Finalize finishes all the connections.
-func (c *connections) Finalize() (errs []error) {
+// Finalize calls Finalize on each Connection in c
+func (c *Connections) Finalize() (errs []error) {
 	for _, connection := range *c {
 		if cerrs := connection.Finalize(); cerrs != nil {
 			for i, err := range cerrs {
-				cerrs[i] = errors.New(fmt.Sprintf("Connection %q: %v", connection.Name(), err))
+				cerrs[i] = fmt.Errorf("Connection %q: %v", connection.Name(), err)
 			}
 			errs = append(errs, cerrs...)
 		}

device.go

@@ -1,20 +1,20 @@
 package gobot
 
 import (
-	"errors"
 	"fmt"
 	"log"
 	"reflect"
 )
 
-// JSONDevice is a JSON representation of a Gobot Device.
+// JSONDevice is a JSON representation of a Device.
 type JSONDevice struct {
 	Name       string   `json:"name"`
 	Driver     string   `json:"driver"`
 	Connection string   `json:"connection"`
 	Commands   []string `json:"commands"`
 }
 
+// NewJSONDevice returns a JSONDevice given a Device.
 func NewJSONDevice(device Device) *JSONDevice {
 	jsonDevice := &JSONDevice{
 		Name:       device.Name(),
@@ -33,24 +33,26 @@ func NewJSONDevice(device Device) *JSONDevice {
 	return jsonDevice
 }
 
+// A Device is an instnace of a Driver
 type Device Driver
 
-type devices []Device
+// Devices represents a collection of Device
+type Devices []Device
 
 // Len returns devices length
-func (d *devices) Len() int {
+func (d *Devices) Len() int {
 	return len(*d)
 }
 
-// Each calls `f` function each device
-func (d *devices) Each(f func(Device)) {
+// Each enumerates through the Devices and calls specified callback function.
+func (d *Devices) Each(f func(Device)) {
 	for _, device := range *d {
 		f(device)
 	}
 }
 
-// Start starts all the devices.
-func (d *devices) Start() (errs []error) {
+// Start calls Start on each Device in d
+func (d *Devices) Start() (errs []error) {
 	log.Println("Starting devices...")
 	for _, device := range *d {
 		info := "Starting device " + device.Name()
@@ -62,20 +64,20 @@ func (d *devices) Start() (errs []error) {
 		log.Println(info + "...")
 		if errs = device.Start(); len(errs) > 0 {
 			for i, err := range errs {
-				errs[i] = errors.New(fmt.Sprintf("Device %q: %v", device.Name(), err))
+				errs[i] = fmt.Errorf("Device %q: %v", device.Name(), err)
 			}
 			return
 		}
 	}
 	return
 }
 
-// Halt stop all the devices.
-func (d *devices) Halt() (errs []error) {
+// Halt calls Halt on each Device in d
+func (d *Devices) Halt() (errs []error) {
 	for _, device := range *d {
 		if derrs := device.Halt(); len(derrs) > 0 {
 			for i, err := range derrs {
-				derrs[i] = errors.New(fmt.Sprintf("Device %q: %v", device.Name(), err))
+				derrs[i] = fmt.Errorf("Device %q: %v", device.Name(), err)
 			}
 			errs = append(errs, derrs...)
 		}

driver.go

@@ -1,12 +1,18 @@
 package gobot
 
+// Driver is the interface that describes a driver in gobot
 type Driver interface {
+	// Name returns the label for the Driver
+	Name() string
+	// Start initiates the Driver
 	Start() []error
+	// Halt terminates the Driver
 	Halt() []error
-	Name() string
+	// Connection returns the Connection assiciated with the Driver
 	Connection() Connection
 }
 
+// Pinner is the interface that describes a driver's pin
 type Pinner interface {
 	Pin() string
 }

event.go

@@ -5,12 +5,13 @@ type callback struct {
 	once bool
 }
 
+// Event executes the list of Callbacks when Chan is written to.
 type Event struct {
 	Chan      chan interface{}
 	Callbacks []callback
 }
 
-// NewEvent returns a new event which is then ready for publishing and subscribing.
+// NewEvent returns a new Event which is now listening for data.
 func NewEvent() *Event {
 	e := &Event{
 		Chan:      make(chan interface{}, 1),
@@ -24,15 +25,16 @@ func NewEvent() *Event {
 	return e
 }
 
-// Write writes data to the Event
+// Write writes data to the Event, it will not block and will not buffer if there
+// are no active subscribers to the Event.
 func (e *Event) Write(data interface{}) {
 	select {
 	case e.Chan <- data:
 	default:
 	}
 }
 
-// Read publishes to all subscribers of e if there is any new data
+// Read executes all Callbacks when new data is available.
 func (e *Event) Read() {
 	for s := range e.Chan {
 		tmp := []callback{}

eventer.go

@@ -4,30 +4,33 @@ type eventer struct {
 	events map[string]*Event
 }
 
+// Eventer is the interface which describes behaviour for a Driver or Adaptor
+// which uses events.
 type Eventer interface {
+	// Events returns the Event map.
 	Events() (events map[string]*Event)
+	// Event returns an Event by name. Returns nil if the Event is not found.
 	Event(name string) (event *Event)
+	// AddEvent adds a new Event given a name.
 	AddEvent(name string)
 }
 
+// NewEventer returns a new Eventer.
 func NewEventer() Eventer {
 	return &eventer{
 		events: make(map[string]*Event),
 	}
 }
 
-// Events returns driver events map
 func (e *eventer) Events() map[string]*Event {
 	return e.events
 }
 
-// Event returns an event by name if exists
 func (e *eventer) Event(name string) (event *Event) {
 	event, _ = e.events[name]
 	return
 }
 
-// AddEvents adds a new event by name
 func (e *eventer) AddEvent(name string) {
 	e.events[name] = NewEvent()
 }

gobot.go

@@ -6,13 +6,13 @@ import (
 	"os/signal"
 )
 
-// JSONGobot holds a JSON representation of a Gobot.
+// JSONGobot is a JSON representation of a Gobot.
 type JSONGobot struct {
 	Robots   []*JSONRobot `json:"robots"`
 	Commands []string     `json:"commands"`
 }
 
-// ToJSON returns a JSON representation of this Gobot.
+// NewJSONGobot returns a JSONGobt given a Gobot.
 func NewJSONGobot(gobot *Gobot) *JSONGobot {
 	jsonGobot := &JSONGobot{
 		Robots:   []*JSONRobot{},
@@ -29,9 +29,10 @@ func NewJSONGobot(gobot *Gobot) *JSONGobot {
 	return jsonGobot
 }
 
-// Gobot is a container composed of one or more robots
+// Gobot is the main type of your Gobot application and contains a collection of
+// Robots, API commands and Events.
 type Gobot struct {
-	robots *robots
+	robots *Robots
 	trap   func(chan os.Signal)
 	Commander
 	Eventer
@@ -40,7 +41,7 @@ type Gobot struct {
 // NewGobot returns a new Gobot
 func NewGobot() *Gobot {
 	return &Gobot{
-		robots: &robots{},
+		robots: &Robots{},
 		trap: func(c chan os.Signal) {
 			signal.Notify(c, os.Interrupt)
 		},
@@ -88,8 +89,8 @@ func (g *Gobot) Start() (errs []error) {
 	return errs
 }
 
-// Robots returns all robots associated with this Gobot instance.
-func (g *Gobot) Robots() *robots {
+// Robots returns all robots associated with this Gobot.
+func (g *Gobot) Robots() *Robots {
 	return g.robots
 }
 
@@ -100,7 +101,7 @@ func (g *Gobot) AddRobot(r *Robot) *Robot {
 	return r
 }
 
-// Robot returns a robot given name. Returns nil on no robot.
+// Robot returns a robot given name. Returns nil if the Robot does not exist.
 func (g *Gobot) Robot(name string) *Robot {
 	for _, robot := range *g.Robots() {
 		if robot.Name == name {