From b9c98d0ffdba899ba37c2a99dae23d28d73a0e6d Mon Sep 17 00:00:00 2001
From: Javier Cervantes <1.27201@gmail.com>
Date: Mon, 20 Oct 2014 10:46:03 -0500
Subject: [PATCH] Adding godocs documentation to joystick package

---
 platforms/joystick/doc.go              | 72 ++++++++++++++++++++++++++
 platforms/joystick/joystick_adaptor.go |  5 ++
 platforms/joystick/joystick_driver.go  | 19 +++++--
 3 files changed, 93 insertions(+), 3 deletions(-)
 create mode 100644 platforms/joystick/doc.go

diff --git a/platforms/joystick/doc.go b/platforms/joystick/doc.go
new file mode 100644
index 00000000..46bf5da3
--- /dev/null
+++ b/platforms/joystick/doc.go
@@ -0,0 +1,72 @@
+/*
+This package provides the Gobot adaptor and drivers for the PS3 controller, Xbox 360 controller, or any other joysticks and game controllers that are compatible with Simple DirectMedia Layer (http://www.libsdl.org/).
+
+Installing:
+
+This package requires `sdl2` to be installed on your system
+Then install package with:
+
+	go get github.com/hybridgroup/gobot && go install github.com/hybridgroup/gobot/platforms/joystick
+
+Example:
+
+	package main
+
+	import (
+		"fmt"
+
+		"github.com/hybridgroup/gobot"
+		"github.com/hybridgroup/gobot/platforms/joystick"
+	)
+
+	func main() {
+		gbot := gobot.NewGobot()
+
+		joystickAdaptor := joystick.NewJoystickAdaptor("ps3")
+		joystick := joystick.NewJoystickDriver(joystickAdaptor,
+			"ps3",
+			"./platforms/joystick/configs/dualshock3.json",
+		)
+
+		work := func() {
+			gobot.On(joystick.Event("square_press"), func(data interface{}) {
+				fmt.Println("square_press")
+			})
+			gobot.On(joystick.Event("square_release"), func(data interface{}) {
+				fmt.Println("square_release")
+			})
+			gobot.On(joystick.Event("triangle_press"), func(data interface{}) {
+				fmt.Println("triangle_press")
+			})
+			gobot.On(joystick.Event("triangle_release"), func(data interface{}) {
+				fmt.Println("triangle_release")
+			})
+			gobot.On(joystick.Event("left_x"), func(data interface{}) {
+				fmt.Println("left_x", data)
+			})
+			gobot.On(joystick.Event("left_y"), func(data interface{}) {
+				fmt.Println("left_y", data)
+			})
+			gobot.On(joystick.Event("right_x"), func(data interface{}) {
+				fmt.Println("right_x", data)
+			})
+			gobot.On(joystick.Event("right_y"), func(data interface{}) {
+				fmt.Println("right_y", data)
+			})
+		}
+
+		robot := gobot.NewRobot("joystickBot",
+			[]gobot.Connection{joystickAdaptor},
+			[]gobot.Device{joystick},
+			work,
+		)
+
+		gbot.AddRobot(robot)
+
+		gbot.Start()
+	}
+
+For further information refer to joystick README:
+https://github.com/hybridgroup/gobot/blob/master/platforms/joystick/README.md
+*/
+package joystick
diff --git a/platforms/joystick/joystick_adaptor.go b/platforms/joystick/joystick_adaptor.go
index a67af685..5cd8af97 100644
--- a/platforms/joystick/joystick_adaptor.go
+++ b/platforms/joystick/joystick_adaptor.go
@@ -16,6 +16,9 @@ type JoystickAdaptor struct {
 	connect  func(*JoystickAdaptor)
 }
 
+// NewJoysctickAdaptor creates a new adaptor with specified name.
+// It creates a connect function to joystick in position 0
+// or panics if no joystick can be found
 func NewJoystickAdaptor(name string) *JoystickAdaptor {
 	return &JoystickAdaptor{
 		Adaptor: *gobot.NewAdaptor(
@@ -33,11 +36,13 @@ func NewJoystickAdaptor(name string) *JoystickAdaptor {
 	}
 }
 
+// Connect returns true if connection to device is succesfull
 func (j *JoystickAdaptor) Connect() bool {
 	j.connect(j)
 	return true
 }
 
+// Finalize closes connection to device
 func (j *JoystickAdaptor) Finalize() bool {
 	j.joystick.Close()
 	return true
diff --git a/platforms/joystick/joystick_driver.go b/platforms/joystick/joystick_driver.go
index 6b8c3c12..7d604075 100644
--- a/platforms/joystick/joystick_driver.go
+++ b/platforms/joystick/joystick_driver.go
@@ -16,17 +16,20 @@ type JoystickDriver struct {
 	poll   func() sdl.Event
 }
 
+// pair is a JSON representation of name and id
 type pair struct {
 	Name string `json:"name"`
 	ID   int    `json:"id"`
 }
 
+// hat is a JSON representation of hat, name and id
 type hat struct {
 	Hat  int    `json:"hat"`
 	Name string `json:"name"`
 	ID   int    `json:"id"`
 }
 
+// joystickConfig is a JSON representation of configuration values
 type joystickConfig struct {
 	Name    string `json:"name"`
 	Guid    string `json:"guid"`
@@ -35,6 +38,11 @@ type joystickConfig struct {
 	Hats    []hat  `json:"Hats"`
 }
 
+// NewJoystickDriver creates a joyscript driver by name.
+//
+// It adds the following events:
+//     (button)_press - triggered when (button) is pressed
+//     (button)_release - triggered when (button) is released
 func NewJoystickDriver(a *JoystickAdaptor, name string, config string) *JoystickDriver {
 	d := &JoystickDriver{
 		Driver: *gobot.NewDriver(
@@ -67,10 +75,12 @@ func NewJoystickDriver(a *JoystickAdaptor, name string, config string) *Joystick
 	return d
 }
 
+// adaptor returns joystick adaptor
 func (j *JoystickDriver) adaptor() *JoystickAdaptor {
 	return j.Adaptor().(*JoystickAdaptor)
 }
 
+// Start initiallizes event polling with defined interval
 func (j *JoystickDriver) Start() bool {
 	gobot.Every(j.Interval(), func() {
 		event := j.poll()
@@ -81,6 +91,7 @@ func (j *JoystickDriver) Start() bool {
 	return true
 }
 
+// HandleEvent publishes an specific event according to data received
 func (j *JoystickDriver) handleEvent(event sdl.Event) error {
 	switch data := event.(type) {
 	case *sdl.JoyAxisEvent:
@@ -124,6 +135,7 @@ func (j *JoystickDriver) handleEvent(event sdl.Event) error {
 	return nil
 }
 
+// Halt stops joystick driver
 func (j *JoystickDriver) Halt() bool { return true }
 
 func (j *JoystickDriver) findName(id uint8, list []pair) string {
@@ -135,10 +147,11 @@ func (j *JoystickDriver) findName(id uint8, list []pair) string {
 	return ""
 }
 
+// findHatName returns name from hat found by id in provided list
 func (j *JoystickDriver) findHatName(id uint8, hat uint8, list []hat) string {
-	for _, value := range list {
-		if int(id) == value.ID && int(hat) == value.Hat {
-			return value.Name
+	for _, lHat := range list {
+		if int(id) == lHat.ID && int(hat) == lHat.Hat {
+			return lHat.Name
 		}
 	}
 	return ""