Added initial round of comments for API documentation

internal/util/util.go

@@ -13,6 +13,11 @@ import (
 	"time"
 )
 
+// PathExists() is a wrapper function that simplifies checking
+// if a file or directory already exists at the provided path.
+//
+// Returns whether the path exists and no error if successful,
+// otherwise, it returns false with an error.
 func PathExists(path string) (bool, error) {
 	_, err := os.Stat(path)
 	if err == nil {
@@ -24,6 +29,8 @@ func PathExists(path string) (bool, error) {
 	return false, err
 }
 
+// GetNextIP() returns the next IP address, but does not account
+// for net masks.
 func GetNextIP(ip *net.IP, inc uint) *net.IP {
 	if ip == nil {
 		return &net.IP{}
@@ -40,7 +47,14 @@ func GetNextIP(ip *net.IP, inc uint) *net.IP {
 	return &r
 }
 
-// Generic convenience function used to make HTTP requests.
+// MakeRequest() is a wrapper function that condenses simple HTTP
+// requests done to a single call. It expects an optional HTTP client,
+// URL, HTTP method, request body, and request headers. This function
+// is useful when making many requests where only these few arguments
+// are changing.
+//
+// Returns a HTTP response object, response body as byte array, and any
+// error that may have occurred with making the request.
 func MakeRequest(client *http.Client, url string, httpMethod string, body []byte, headers map[string]string) (*http.Response, []byte, error) {
 	// use defaults if no client provided
 	if client == nil {
@@ -69,6 +83,12 @@ func MakeRequest(client *http.Client, url string, httpMethod string, body []byte
 	return res, b, err
 }
 
+// MakeOutputDirectory() creates a new directory at the path argument if
+// the path does not exist
+//
+// TODO: Refactor this function for hive partitioning or possibly move into
+// the logging package.
+// TODO: Add an option to force overwriting the path.
 func MakeOutputDirectory(path string) (string, error) {
 	// get the current data + time using Go's stupid formatting
 	t := time.Now()
@@ -93,12 +113,27 @@ func MakeOutputDirectory(path string) (string, error) {
 	return final, nil
 }
 
+// SplitPathForViper() is an utility function to split a path into 3 parts:
+// - directory
+// - filename
+// - extension
+// The intent was to break a path into a format that's more easily consumable
+// by spf13/viper's API. See the "LoadConfig()" function in internal/config.go
+// for more details.
+//
+// TODO: Rename function to something more generalized.
 func SplitPathForViper(path string) (string, string, string) {
 	filename := filepath.Base(path)
 	ext := filepath.Ext(filename)
 	return filepath.Dir(path), strings.TrimSuffix(filename, ext), strings.TrimPrefix(ext, ".")
 }
 
+// FormatErrorList() is a wrapper function that unifies error list formatting
+// and makes printing error lists consistent.
+//
+// NOTE: The error returned IS NOT an error in itself and may be a bit misleading.
+// Instead, it is a single condensed error composed of all of the errors included
+// in the errList argument.
 func FormatErrorList(errList []error) error {
 	var err error
 	for i, e := range errList {
@@ -108,6 +143,9 @@ func FormatErrorList(errList []error) error {
 	return err
 }
 
+// HasErrors() is a simple wrapper function to check if an error list contains
+// errors. Having a function that clearly states its purpose helps to improve
+// readibility although it may seem pointless.
 func HasErrors(errList []error) bool {
 	return len(errList) > 0
 }