input/gvctrl/utils.go: wrote documentation for utils.go

input/gvctrl/utils.go

@@ -1,7 +1,7 @@
 /*
 DESCRIPTION
-  utils.go provides helper functions for functionality found in both gvctrl.go
-  request.go.
+  utils.go provides general constants, structs and helper functions for use in
+  this package.
 
 AUTHORS
   Saxon A. Nelson-Milton <saxon@ausocean.org>
@@ -34,12 +34,15 @@ import (
 	"strings"
 )
 
+// The strings used in encoding the settings form to indicate resultion.
 const (
-	res256 = "4480256"
-	res360 = "6400360"
-	res720 = "12800720"
+	res256 = "4480256"  // 480x256
+	res360 = "6400360"  // 640x360
+	res720 = "12800720" // 1280x720
 )
 
+// Default values for fields in the settings struct when the newSettings
+// constructor is used.
 const (
 	defaultCodec      = CodecH264
 	defaultRes        = "6400360" // 360p
@@ -51,6 +54,8 @@ const (
 	defaultRefresh    = "2000" // 2 seconds
 )
 
+// settings holds string representations required by the settings form for each
+// of the parameters configurable through this API.
 type settings struct {
 	codec      Codec
 	res        string
@@ -62,6 +67,7 @@ type settings struct {
 	refresh    string
 }
 
+// newSetting will return a settings with default values.
 func newSettings() settings {
 	return settings{
 		codec:      defaultCodec,
@@ -75,12 +81,15 @@ func newSettings() settings {
 	}
 }
 
+// md5Hex returns the md5 hex string of s with alphanumerics as upper case.
 func md5Hex(s string) string {
 	h := md5.New()
 	h.Write([]byte(s))
 	return strings.ToUpper(hex.EncodeToString(h.Sum(nil)))
 }
 
+// closestValIdx will return the index of the value in l that is closest to the
+// value v.
 func closestValIdx(v int, l []int) int {
 	var idx int
 	for i := range l {
@@ -91,10 +100,14 @@ func closestValIdx(v int, l []int) int {
 	return idx
 }
 
+// convRate is used to firstly find a value in l closest to the bitrate v (in
+// kbps), convert from kbps to bps, and the convert to string.
 func convRate(v int, l []int) string {
 	return strconv.Itoa(l[closestValIdx(v, l)] * 1000)
 }
 
+// populateForm will populate the settings form using the passed settings struct
+// s and return as a url.Values.
 func populateForm(s settings) url.Values {
 	f := url.Values{}
 	f.Set("dwConnType", "5")