Update utils docs

examples_test.go

@@ -0,0 +1,75 @@
+package gobot_test
+
+import (
+	"fmt"
+	"github.com/hybridgroup/gobot"
+	"testing"
+	"time"
+)
+
+func ExampleEvery() {
+	gobot.Every(1*time.Second, func() {
+		fmt.Println("Hello")
+	})
+}
+
+func ExampleAfter() {
+	gobot.After(1*time.Second, func() {
+		fmt.Println("Hello")
+	})
+}
+
+func ExamplePublish() {
+	e := gobot.NewEvent()
+	gobot.Publish(e, 100)
+}
+
+func ExampleOn() {
+	e := gobot.NewEvent()
+	gobot.On(e, func(s interface{}) {
+		fmt.Println(s)
+	})
+	gobot.Publish(e, 100)
+	gobot.Publish(e, 200)
+}
+
+func ExampleOnce() {
+	e := gobot.NewEvent()
+	gobot.Once(e, func(s interface{}) {
+		fmt.Println(s)
+		fmt.Println("I will no longer respond to events")
+	})
+	gobot.Publish(e, 100)
+	gobot.Publish(e, 200)
+}
+
+func ExampleRand() {
+	i := gobot.Rand(100)
+	fmt.Sprintln("%v is > 0 && < 100", i)
+}
+
+func ExampleFromScale() {
+	fmt.Println(gobot.FromScale(5, 0, 10))
+	// Output:
+	// 0.5
+}
+
+func ExampleToScale() {
+	fmt.Println(gobot.ToScale(500, 0, 10))
+	// Output:
+	// 10
+}
+
+func ExampleAssert() {
+	t := &testing.T{}
+	var a int = 100
+	var b int = 100
+	gobot.Assert(t, a, b)
+}
+
+func ExampleRefute() {
+	t := &testing.T{}
+	var a int = 100
+	var b int = 200
+	gobot.Refute(t, a, b)
+}

test_helper.go

@@ -14,6 +14,9 @@ func logFailure(t *testing.T, message string) {
 	s := strings.Split(file, "/")
 	t.Errorf("%v:%v: %v", s[len(s)-1], line, message)
 }
+
+// Assert ensures a and b are equal and of the same type, or else it
+// causes a t.Error
 func Assert(t *testing.T, a interface{}, b interface{}) {
 	if !reflect.DeepEqual(a, b) {
 		logFailure(t, fmt.Sprintf("%v - \"%v\", should equal,  %v - \"%v\"",
@@ -21,6 +24,7 @@ func Assert(t *testing.T, a interface{}, b interface{}) {
 	}
 }
 
+// Refute ensures a and b are not equal, causes a t.Error if they are equal
 func Refute(t *testing.T, a interface{}, b interface{}) {
 	if reflect.DeepEqual(a, b) {
 		logFailure(t, fmt.Sprintf("%v - \"%v\", should not equal,  %v - \"%v\"",

utils.go

@@ -7,7 +7,8 @@ import (
 	"time"
 )
 
-// Every triggers f every `t` time until the end of days.
+// Every triggers f every t time until the end of days. It does not wait for the
+// previous execution of f to finish before it fires the next f.
 func Every(t time.Duration, f func()) {
 	c := time.Tick(t)
 
@@ -19,40 +20,40 @@ func Every(t time.Duration, f func()) {
 	}()
 }
 
-// After triggers the passed function after `t` duration.
+// After triggers f after t duration.
 func After(t time.Duration, f func()) {
 	time.AfterFunc(t, f)
 }
 
-// Publish emits an event by writting value
+// Publish emits val to all subscribers of e.
 func Publish(e *Event, val interface{}) {
 	e.Write(val)
 }
 
-// On adds `f` to callbacks that are executed on specified event
+// On executes f when e is Published to.
 func On(e *Event, f func(s interface{})) {
 	e.Callbacks = append(e.Callbacks, callback{f, false})
 }
 
-// Once adds `f` to callbacks that are executed on specified event
-// and sets flag to be called only once
+// Once is similar to On except that it only executes f one time.
 func Once(e *Event, f func(s interface{})) {
 	e.Callbacks = append(e.Callbacks, callback{f, true})
 }
 
-// Rand generates random int lower than max
+// Rand returns a positive random int up to max
 func Rand(max int) int {
 	i, _ := rand.Int(rand.Reader, big.NewInt(int64(max)))
 	return int(i.Int64())
 }
 
-// FromScale creates a scale using min and max values
-// to be used in combination with ToScale
+// FromScale returns a converted input from min, max to 0.0...1.0.
 func FromScale(input, min, max float64) float64 {
 	return (input - math.Min(min, max)) / (math.Max(min, max) - math.Min(min, max))
 }
 
-// ToScale is used with FromScale to return input converted to new scale
+// ToScale returns a converted input from 0...1 to min...max scale.
+// If input is less than min then ToScale returns min.
+// If input is greater than max then ToScale returns max
 func ToScale(input, min, max float64) float64 {
 	i := input*(math.Max(min, max)-math.Min(min, max)) + math.Min(min, max)
 	if i < math.Min(min, max) {