From de0efc266686675a53ca630e89a5a8deddb26d4f Mon Sep 17 00:00:00 2001
From: Javier Cervantes <1.27201@gmail.com>
Date: Mon, 20 Oct 2014 13:17:47 -0500
Subject: [PATCH] Adding godocs documentation to intel-iot package

---
 platforms/intel-iot/edison/digital_pin.go    | 18 +++++++++++++++++
 platforms/intel-iot/edison/edison_adaptor.go | 21 +++++++++++++++++++-
 platforms/intel-iot/edison/i2c_device.go     |  5 +++++
 platforms/intel-iot/edison/pwm_pin.go        | 18 +++++++++++++++++
 platforms/intel-iot/intel-iot.go             |  9 +++++++++
 5 files changed, 70 insertions(+), 1 deletion(-)

diff --git a/platforms/intel-iot/edison/digital_pin.go b/platforms/intel-iot/edison/digital_pin.go
index 7df44a75..1088c3bb 100644
--- a/platforms/intel-iot/edison/digital_pin.go
+++ b/platforms/intel-iot/edison/digital_pin.go
@@ -5,18 +5,27 @@ import (
 	"strconv"
 )
 
+// gpioPath returns base gpio path
 func gpioPath() string {
 	return "/sys/class/gpio"
 }
+
+// gpioExportPath returns export path
 func gpioExportPath() string {
 	return gpioPath() + "/export"
 }
+
+// gpioUnExportPath returns unexport path
 func gpioUnExportPath() string {
 	return gpioPath() + "/unexport"
 }
+
+// gpioDirectionPath returns direction path for specified pin
 func gpioDirectionPath(pin string) string {
 	return gpioPath() + "/gpio" + pin + "/direction"
 }
+
+// gpioValuePath returns value path for specified pin
 func gpioValuePath(pin string) string {
 	return gpioPath() + "/gpio" + pin + "/value"
 }
@@ -26,12 +35,15 @@ type digitalPin struct {
 	dir string
 }
 
+// newDigitalPin returns an exported digital pin
 func newDigitalPin(pin int) *digitalPin {
 	d := &digitalPin{pin: strconv.Itoa(pin)}
 	d.export()
 	return d
 }
 
+// setDir sets writes a directory using direction path for specified pin.
+// It panics on error
 func (d *digitalPin) setDir(dir string) {
 	d.dir = dir
 	err := writeFile(gpioDirectionPath(d.pin), dir)
@@ -40,6 +52,8 @@ func (d *digitalPin) setDir(dir string) {
 	}
 }
 
+// digitalWrite writes specified value to gpio value path
+// It panics on error
 func (d *digitalPin) digitalWrite(value string) {
 	if d.dir != "out" {
 		d.setDir("out")
@@ -50,6 +64,7 @@ func (d *digitalPin) digitalWrite(value string) {
 	}
 }
 
+// digitalRead reads from gpio value path
 func (d *digitalPin) digitalRead() int {
 	if d.dir != "in" {
 		d.setDir("in")
@@ -67,14 +82,17 @@ func (d *digitalPin) digitalRead() int {
 	return i
 }
 
+// export writes directory for gpio export path
 func (d *digitalPin) export() {
 	writeFile(gpioExportPath(), d.pin)
 }
 
+// unexport writes directory for gpio unexport path
 func (d *digitalPin) unexport() {
 	writeFile(gpioUnExportPath(), d.pin)
 }
 
+// close unexports digital pin
 func (d *digitalPin) close() {
 	d.unexport()
 }
diff --git a/platforms/intel-iot/edison/edison_adaptor.go b/platforms/intel-iot/edison/edison_adaptor.go
index c315c82c..68b1d62c 100644
--- a/platforms/intel-iot/edison/edison_adaptor.go
+++ b/platforms/intel-iot/edison/edison_adaptor.go
@@ -143,6 +143,7 @@ var sysfsPinMap = map[string]sysfsPin{
 	},
 }
 
+// writeFile validates file existence and writes data into it
 func writeFile(name, data string) error {
 	if _, err := os.Stat(name); err == nil {
 		err := ioutil.WriteFile(
@@ -159,6 +160,7 @@ func writeFile(name, data string) error {
 	return nil
 }
 
+// changePinMode writes pin mode to current_pinmux file
 func changePinMode(pin, mode string) {
 	err := writeFile(
 		"/sys/kernel/debug/gpio_debug/gpio"+pin+"/current_pinmux",
@@ -169,6 +171,8 @@ func changePinMode(pin, mode string) {
 	}
 }
 
+// NewEditionAdaptor creates a EdisonAdaptor with specified name and
+// creates connect function
 func NewEdisonAdaptor(name string) *EdisonAdaptor {
 	return &EdisonAdaptor{
 		Adaptor: *gobot.NewAdaptor(
@@ -207,6 +211,8 @@ func NewEdisonAdaptor(name string) *EdisonAdaptor {
 	}
 }
 
+// Connect starts conection with board and creates
+// digitalPins and pwmPins adaptor maps
 func (e *EdisonAdaptor) Connect() bool {
 	e.digitalPins = make(map[int]*digitalPin)
 	e.pwmPins = make(map[int]*pwmPin)
@@ -214,6 +220,7 @@ func (e *EdisonAdaptor) Connect() bool {
 	return true
 }
 
+// Finalize closes connection to board and pins
 func (e *EdisonAdaptor) Finalize() bool {
 	e.tristate.close()
 	for _, pin := range e.digitalPins {
@@ -231,9 +238,14 @@ func (e *EdisonAdaptor) Finalize() bool {
 	}
 	return true
 }
-func (e *EdisonAdaptor) Reconnect() bool  { return true }
+
+// Reconnect retries connection to edison board
+func (e *EdisonAdaptor) Reconnect() bool { return true }
+
+// Disconnect returns true if connection to edison board is finished successfully
 func (e *EdisonAdaptor) Disconnect() bool { return true }
 
+// digitalPin returns matched digitalPin for specified values
 func (e *EdisonAdaptor) digitalPin(pin string, dir string) *digitalPin {
 	i := sysfsPinMap[pin]
 	if e.digitalPins[i.pin] == nil {
@@ -264,14 +276,17 @@ func (e *EdisonAdaptor) digitalPin(pin string, dir string) *digitalPin {
 	return e.digitalPins[i.pin]
 }
 
+// DigitalRead reads digital value from pin
 func (e *EdisonAdaptor) DigitalRead(pin string) int {
 	return e.digitalPin(pin, "in").digitalRead()
 }
 
+// DigitalWrite writes digital value to specified pin
 func (e *EdisonAdaptor) DigitalWrite(pin string, val byte) {
 	e.digitalPin(pin, "out").digitalWrite(strconv.Itoa(int(val)))
 }
 
+// PwmWrite writes scaled pwm value to specified pin
 func (e *EdisonAdaptor) PwmWrite(pin string, val byte) {
 	sysPin := sysfsPinMap[pin]
 	if sysPin.pwmPin != -1 {
@@ -291,6 +306,7 @@ func (e *EdisonAdaptor) PwmWrite(pin string, val byte) {
 	}
 }
 
+// AnalogRead returns value from analog reading of specified pin
 func (e *EdisonAdaptor) AnalogRead(pin string) int {
 	buf, err := ioutil.ReadFile(
 		"/sys/bus/iio/devices/iio:device1/in_voltage" + pin + "_raw",
@@ -305,6 +321,7 @@ func (e *EdisonAdaptor) AnalogRead(pin string) int {
 	return val
 }
 
+// I2cStart initializes i2c device for addresss
 func (e *EdisonAdaptor) I2cStart(address byte) {
 	e.tristate.digitalWrite("0")
 
@@ -331,10 +348,12 @@ func (e *EdisonAdaptor) I2cStart(address byte) {
 	e.i2cDevice.start()
 }
 
+// I2cWrite writes data to i2cDevice
 func (e *EdisonAdaptor) I2cWrite(data []byte) {
 	e.i2cDevice.write(data)
 }
 
+// I2cRead reads data from i2cDevice
 func (e *EdisonAdaptor) I2cRead(size uint) []byte {
 	return e.i2cDevice.read(size)
 }
diff --git a/platforms/intel-iot/edison/i2c_device.go b/platforms/intel-iot/edison/i2c_device.go
index 631fd303..07ed011b 100644
--- a/platforms/intel-iot/edison/i2c_device.go
+++ b/platforms/intel-iot/edison/i2c_device.go
@@ -14,6 +14,7 @@ type i2cDevice struct {
 	i2cLocation string
 }
 
+/// newI2cDevice creates a new i2c device for address
 func newI2cDevice(address byte) *i2cDevice {
 	return &i2cDevice{
 		i2cLocation: I2CLocation,
@@ -21,6 +22,8 @@ func newI2cDevice(address byte) *i2cDevice {
 	}
 }
 
+// start initializes i2c device.
+// Panics on error.
 func (i *i2cDevice) start() {
 	var err error
 	i.file, err = os.OpenFile(i.i2cLocation, os.O_RDWR, os.ModeExclusive)
@@ -39,10 +42,12 @@ func (i *i2cDevice) start() {
 	i.write([]byte{0})
 }
 
+// write writes data to i2c file
 func (i *i2cDevice) write(data []byte) {
 	i.file.Write(data)
 }
 
+// read gets data from i2c file
 func (i *i2cDevice) read(len uint) []byte {
 	buf := make([]byte, len)
 	i.file.Read(buf)
diff --git a/platforms/intel-iot/edison/pwm_pin.go b/platforms/intel-iot/edison/pwm_pin.go
index b7b8857d..3fa864a5 100644
--- a/platforms/intel-iot/edison/pwm_pin.go
+++ b/platforms/intel-iot/edison/pwm_pin.go
@@ -5,21 +5,32 @@ import (
 	"strconv"
 )
 
+// pwmPath returns pwm base path
 func pwmPath() string {
 	return "/sys/class/pwm/pwmchip0"
 }
+
+// pwmExportPath returns export path
 func pwmExportPath() string {
 	return pwmPath() + "/export"
 }
+
+// pwmUnExportPath returns unexport path
 func pwmUnExportPath() string {
 	return pwmPath() + "/unexport"
 }
+
+// pwmDutyCyclePath returns duty_cycle path for specified pin
 func pwmDutyCyclePath(pin string) string {
 	return pwmPath() + "/pwm" + pin + "/duty_cycle"
 }
+
+// pwmPeriodPath returns period path for specified pin
 func pwmPeriodPath(pin string) string {
 	return pwmPath() + "/pwm" + pin + "/period"
 }
+
+// pwmEnablePath returns enable path for specified pin
 func pwmEnablePath(pin string) string {
 	return pwmPath() + "/pwm" + pin + "/enable"
 }
@@ -28,6 +39,7 @@ type pwmPin struct {
 	pin string
 }
 
+// newPwmPin returns an exported and enabled pwmPin
 func newPwmPin(pin int) *pwmPin {
 	p := &pwmPin{pin: strconv.Itoa(pin)}
 	p.export()
@@ -35,6 +47,7 @@ func newPwmPin(pin int) *pwmPin {
 	return p
 }
 
+// enable writes value to pwm enable path
 func (p *pwmPin) enable(val string) {
 	err := writeFile(pwmEnablePath(p.pin), val)
 	if err != nil {
@@ -42,6 +55,7 @@ func (p *pwmPin) enable(val string) {
 	}
 }
 
+// period reads from pwm period path and returns value
 func (p *pwmPin) period() string {
 	buf, err := ioutil.ReadFile(pwmPeriodPath(p.pin))
 	if err != nil {
@@ -50,6 +64,7 @@ func (p *pwmPin) period() string {
 	return string(buf[0 : len(buf)-1])
 }
 
+// writeDuty writes value to pwm duty cycle path
 func (p *pwmPin) writeDuty(duty string) {
 	err := writeFile(pwmDutyCyclePath(p.pin), duty)
 	if err != nil {
@@ -57,14 +72,17 @@ func (p *pwmPin) writeDuty(duty string) {
 	}
 }
 
+// export writes pin to pwm export path
 func (p *pwmPin) export() {
 	writeFile(pwmExportPath(), p.pin)
 }
 
+// export writes pin to pwm unexport path
 func (p *pwmPin) unexport() {
 	writeFile(pwmUnExportPath(), p.pin)
 }
 
+// close disables and unexports pin
 func (p *pwmPin) close() {
 	p.enable("0")
 	p.unexport()
diff --git a/platforms/intel-iot/intel-iot.go b/platforms/intel-iot/intel-iot.go
index 0f464658..23c9af1e 100644
--- a/platforms/intel-iot/intel-iot.go
+++ b/platforms/intel-iot/intel-iot.go
@@ -1 +1,10 @@
+/*
+This package contains the Gobot adaptor for the Intel Edison (http://www.intel.com/content/www/us/en/do-it-yourself/edison.html) IoT platform.
+
+This package currently supports the following Intel IoT hardware:
+- Intel Edison with the Arduino breakout board
+
+For further information refer to intel-iot README:
+https://github.com/hybridgroup/gobot/blob/master/platforms/intel-iot/README.md
+*/
 package inteliot