From bf7bc97c3aa1fa87684192d5216a7d8eb2203ace Mon Sep 17 00:00:00 2001
From: Adrian Zankich <adrian@hybridgroup.com>
Date: Sun, 28 Sep 2014 20:32:31 -0700
Subject: [PATCH] Add sphero docs

---
 platforms/sphero/sphero_adaptor.go | 11 ++++++++++-
 platforms/sphero/sphero_driver.go  | 28 ++++++++++++++++++++++++----
 2 files changed, 34 insertions(+), 5 deletions(-)

diff --git a/platforms/sphero/sphero_adaptor.go b/platforms/sphero/sphero_adaptor.go
index c74282e6..40c15507 100644
--- a/platforms/sphero/sphero_adaptor.go
+++ b/platforms/sphero/sphero_adaptor.go
@@ -1,17 +1,20 @@
 package sphero
 
 import (
+	"io"
+
 	"github.com/hybridgroup/gobot"
 	"github.com/tarm/goserial"
-	"io"
 )
 
+// Represents a Connection to a Sphero
 type SpheroAdaptor struct {
 	gobot.Adaptor
 	sp      io.ReadWriteCloser
 	connect func(*SpheroAdaptor)
 }
 
+// NewSpheroAdaptor returns a new SpheroAdaptor given a name and port
 func NewSpheroAdaptor(name string, port string) *SpheroAdaptor {
 	return &SpheroAdaptor{
 		Adaptor: *gobot.NewAdaptor(
@@ -30,12 +33,16 @@ func NewSpheroAdaptor(name string, port string) *SpheroAdaptor {
 	}
 }
 
+// Connect initiates a connection to the Sphero. Returns true on successful connection.
 func (a *SpheroAdaptor) Connect() bool {
 	a.connect(a)
 	a.SetConnected(true)
 	return true
 }
 
+// Reconnect attempts to reconnect to the Sphero. If the Sphero has an active connection
+// it will first close that connection and then establish a new connection.
+// Returns true on Successful reconnection
 func (a *SpheroAdaptor) Reconnect() bool {
 	if a.Connected() == true {
 		a.Disconnect()
@@ -43,12 +50,14 @@ func (a *SpheroAdaptor) Reconnect() bool {
 	return a.Connect()
 }
 
+// Disconnect terminates the connection to the Sphero. Returns true on successful disconnect.
 func (a *SpheroAdaptor) Disconnect() bool {
 	a.sp.Close()
 	a.SetConnected(false)
 	return true
 }
 
+// Finalize finalizes the SpheroAdaptor
 func (a *SpheroAdaptor) Finalize() bool {
 	return true
 }
diff --git a/platforms/sphero/sphero_driver.go b/platforms/sphero/sphero_driver.go
index f2cc5c3a..f27c0bb5 100644
--- a/platforms/sphero/sphero_driver.go
+++ b/platforms/sphero/sphero_driver.go
@@ -15,6 +15,7 @@ type packet struct {
 	checksum uint8
 }
 
+// Represents a Sphero
 type SpheroDriver struct {
 	gobot.Driver
 	seq             uint8
@@ -37,6 +38,15 @@ type Collision struct {
 	Timestamp uint32
 }
 
+// NewSpheroDriver returns a new SpheroDriver given a SpheroAdaptor and name.
+//
+// Adds the following API Commands:
+// 	"Roll" - See SpheroDriver.Roll
+// 	"Stop" - See SpheroDriver.Stop
+// 	"GetRGB" - See SpheroDriver.GetRGB
+// 	"SetBackLED" - See SpheroDriver.SetBackLED
+// 	"SetHeading" - See SpheroDriver.SetHeading
+// 	"SetStabilization" - See SpheroDriver.SetStabilization
 func NewSpheroDriver(a *SpheroAdaptor, name string) *SpheroDriver {
 	s := &SpheroDriver{
 		Driver: *gobot.NewDriver(
@@ -97,10 +107,11 @@ func (s *SpheroDriver) adaptor() *SpheroAdaptor {
 	return s.Adaptor().(*SpheroAdaptor)
 }
 
-func (s *SpheroDriver) Init() bool {
-	return true
-}
-
+// Start starts the SpheroDriver and enables Collision Detection.
+// Returns true on successful start.
+//
+// Emits the Events:
+// 	"collision" SpheroDriver.Collision - On Collision Detected
 func (s *SpheroDriver) Start() bool {
 	go func() {
 		for {
@@ -155,6 +166,8 @@ func (s *SpheroDriver) Start() bool {
 	return true
 }
 
+// Halt halts the SpheroDriver and sends a SpheroDriver.Stop command to the Sphero.
+// Returns true on successful halt.
 func (s *SpheroDriver) Halt() bool {
 	gobot.Every(10*time.Millisecond, func() {
 		s.Stop()
@@ -163,22 +176,27 @@ func (s *SpheroDriver) Halt() bool {
 	return true
 }
 
+// SetRGB sets the Sphero to the given r, g, and b values
 func (s *SpheroDriver) SetRGB(r uint8, g uint8, b uint8) {
 	s.packetChannel <- s.craftPacket([]uint8{r, g, b, 0x01}, 0x02, 0x20)
 }
 
+// GetRGB returns the current r, g, b value of the Sphero
 func (s *SpheroDriver) GetRGB() []uint8 {
 	return s.getSyncResponse(s.craftPacket([]uint8{}, 0x02, 0x22))
 }
 
+// SetBackLED sets the Sphero Back LED to the specified brightness
 func (s *SpheroDriver) SetBackLED(level uint8) {
 	s.packetChannel <- s.craftPacket([]uint8{level}, 0x02, 0x21)
 }
 
+// SetHeading sets the heading of the Sphero
 func (s *SpheroDriver) SetHeading(heading uint16) {
 	s.packetChannel <- s.craftPacket([]uint8{uint8(heading >> 8), uint8(heading & 0xFF)}, 0x02, 0x01)
 }
 
+// SetStabilization enables or disables the built-in auto stabilizing features of the Sphero
 func (s *SpheroDriver) SetStabilization(on bool) {
 	b := uint8(0x01)
 	if on == false {
@@ -187,10 +205,12 @@ func (s *SpheroDriver) SetStabilization(on bool) {
 	s.packetChannel <- s.craftPacket([]uint8{b}, 0x02, 0x02)
 }
 
+// Roll sends a roll command to the Sphero gives a speed and heading
 func (s *SpheroDriver) Roll(speed uint8, heading uint16) {
 	s.packetChannel <- s.craftPacket([]uint8{speed, uint8(heading >> 8), uint8(heading & 0xFF), 0x01}, 0x02, 0x30)
 }
 
+// Stop sets the Sphero to a roll speed of 0
 func (s *SpheroDriver) Stop() {
 	s.Roll(0, 0)
 }