update function comments and add them where missing. fixes #34

config/config.go

@@ -41,7 +41,7 @@ type Config struct {
 	LocalVersion             uint64 `json:"LocalVersion"`             // (D) The local version of this program that is currently running.
 }
 
-// COnfigJSONParametersExplained() returns a nicely formatted string which
+// ConfigJSONParametersExplained() returns a nicely formatted string which
 // describes all the public variables available to the user for configuration.
 func ConfigJSONParametersExplained() string {
 	return `

loader/loader.go

@@ -48,7 +48,7 @@ func NewLoader(processesPath string) (*Loader, error) {
 	return loader, nil
 }
 
-// getProcessesFromJSONFile will read in a set of JSON values which define both
+// processesFromJSONFile will read in a set of JSON values which define both
 // the canonical name of the process as well as the command and any associated
 // parameters to successfully execute that command. A slice containing a
 // LoaderProcess struct for each individual command to execute will be returned.
@@ -185,6 +185,9 @@ func (ldr *Loader) StartSynchronous() []LoaderProcess {
 	return ldr.Processes
 }
 
+// Run will continuously execute this specific instance of Loader indefinitely.
+// Should only be called externally when all configuration options have been
+// correctly setup and you wish to execute a set number of processes forever.
 func (ldr *Loader) Run() {
 	go func() {
 		for 1 == 1 {

logger/logger.go

@@ -83,7 +83,8 @@ func StandardLogger(logBaseName string) error {
 
 // CurrentLogContents returns the contents of the current log file that's being
 // managed by the logger instance. The current log should be active thus
-// multiple calls to CurrentLogContents() should give different results.
+// multiple calls to CurrentLogContents() should give different results assuming
+// the log is being actively written to.
 func (lgr *Logger) CurrentLogContents() ([]byte, error) {
 
 	lgr.writer.Flush()
@@ -145,6 +146,9 @@ func (lgr *Logger) initLogger(logBaseName string) error {
 	return nil
 }
 
+// Write satisfies the writer interface for golang. This allows an instance of
+// Logger to be passed in to the os/exec library for capturing from both the
+// stdout and stderr steams.
 func (lgr *Logger) Write(p []byte) (n int, err error) {
 	lgr.LogMessage(string(p))
 	return len(p), nil

network/network.go

@@ -47,9 +47,11 @@ func NewNetwork() (*Network, error) {
 	return netw, nil
 }
 
-// this was multi-threaded at first but it had reduced reliability when 20+
-// network requests went out simultaneously. this will run in the background as
-// it is so it won't really need to be multithreaded.
+// IsInternetReachable will reach out to the internet and attempt to query a
+// number of publicly reachable API endpoints or public websites. The list is
+// quite extensive and the endpoints targeted should be extremely reliable. If
+// a significant ratio of these sites can't be reached then AEN knows that the
+// internet is currently unreachable and returns false.
 func (con *Network) IsInternetReachable() bool {
 
 	numQueries := len(con.endpoints)

profiler/profiler.go

@@ -108,11 +108,11 @@ func ProfileAsArchive() (*os.File, error) {
 	return tarBall, nil
 }
 
-// SendArchiveReportAsAttachment will generate each individual piece of the
+// SendArchiveProfileAsAttachment will generate each individual piece of the
 // system profile inside its own file. It will then gzip and tarball the
 // resulting pieces into a single archive for compressing and convenience
-// purposes. The original pieces will be automatically cleaned up the archive
-// is generated.
+// purposes. The original pieces will be automatically cleaned up when the
+// archive is generated.
 func SendArchiveProfileAsAttachment() (*os.File, error) {
 	filePtr, err := ProfileAsArchive()
 	if err != nil {
@@ -124,6 +124,8 @@ func SendArchiveProfileAsAttachment() (*os.File, error) {
 	return filePtr, reporter.SendAttachment(generateEmailSubject(), generateEmailBody(), filePtr)
 }
 
+// generateEmailSubject will create the necessary formatted and pretty email
+// subject and return it for the current profile that was just generated.
 func generateEmailSubject() string {
 	var buf bytes.Buffer
 	buf.WriteString(PROFILE_EMAIL_SUBJECT)
@@ -132,12 +134,16 @@ func generateEmailSubject() string {
 	return string(buf.Bytes())
 }
 
+// generateEmailBody will create the necessary email body contents and return it
+// for the current profile that was just generated.
 func generateEmailBody() []byte {
 	var buf bytes.Buffer
 	buf.WriteString("A full system profile is attached.")
 	return buf.Bytes()
 }
 
+// Run will ensure that the profiler is constantly active and sending out
+// new profile updates at the interval defined by CheckInFrequencySeconds.
 func Run() {
 	// kick off the system profiler loop to send out system profiles at the specified interval
 	go func() {

rest/rest.go

@@ -53,9 +53,6 @@ const LOG_REST_PATH = "logs"
 // The REST path name which calls the update handler
 const UPDATE_REST_PATH = "update"
 
-// The REST path name which calls the config handler
-const CONFIG_REST_PATH = "config"
-
 // The REST path name which calls the check in handler
 const CHECKIN_REST_PATH = "checkin"
 
@@ -107,6 +104,10 @@ func NewRestHandler() (*RestHandler, error) {
 	return &rh, nil
 }
 
+// buildGorillaPath will build a complete gorilla path argument for the given
+// root endpoint and all of the given arguments. Each successive argument will
+// be separated by a set of forward slashes to separate it from all the other
+// arguments. E.G. root/arg1/arg2/arg3 etc.
 func buildGorillaPath(root string, arguments ...string) string {
 	var routeBuf bytes.Buffer
 	routeBuf.WriteString("/")
@@ -121,6 +122,10 @@ func buildGorillaPath(root string, arguments ...string) string {
 	return routeBuf.String()
 }
 
+// buildRestPath will generate a full rest path give an endpoint and arguments.
+// This is very useful for sending out fully qualified links to specific
+// endpoints. This is used for documentation purposes when the REST server
+// starts up so the end-user can get notified of all active rest endpoints.
 func buildRestPath(protocol, host, port, root string, arguments ...string) string {
 	var routeBuf bytes.Buffer
 	routeBuf.WriteString(protocol)
@@ -139,10 +144,10 @@ func buildRestPath(protocol, host, port, root string, arguments ...string) strin
 	return routeBuf.String()
 }
 
-// startupRestServer will start up the local REST server where this remote
+// StartupRestServer will start up the local REST server where this remote
 // machine will listen for incoming commands on. A free port on this local
 // machine will be automatically detected and used. The randomly chosen
-// available port will be logged locally as well as emailed.
+// available port will be logged locally as well as reported via email.
 func (rh *RestHandler) StartupRestServer() error {
 	port, err := freeport.Get()
 	if err != nil {
@@ -229,10 +234,10 @@ func (rh *RestHandler) writeResponseAndLog(errorMessage string, httpStatusCode i
 	logger.Lgr.LogMessage(statusBuffer.String())
 }
 
-// checkinHandler will handle receiving and verifying check-in commands via REST.
-// Check-in commands will notify the remote machine that the remote user would
-// like the machine to perform a check-in. A check-in will send all pertinent data
-// regarding the current operating status of this remote machine.
+// checkinHandler will handle receiving and verifying check-in commands via
+// REST. Check-in commands will notify the remote machine that the remote user
+// would like the machine to perform a check-in. A check-in will send all
+// pertinent data regarding the current operating status of this remote machine.
 func (rh *RestHandler) checkinHandler(writer http.ResponseWriter, request *http.Request) {
 
 	var err error
@@ -272,9 +277,8 @@ func (rh *RestHandler) checkinHandler(writer http.ResponseWriter, request *http.
 
 // executeHandler will handle receiving and verifying execute commands via REST.
 // Execute commands will allow the local machine to execute the code contained
-// at the remote location. Currently considering supporting executables and
-// Python files. Should we do a JSON config instead to allow call command,
-// parameters, and a location to the file to download all cleanly in one?
+// in the body of the POST that is sent. Currently python, shell script, and
+// raw binaries are supported. This is an EXTREMELY powerful function.
 func (rh *RestHandler) executeHandler(writer http.ResponseWriter, request *http.Request) {
 
 	var err error
@@ -334,6 +338,11 @@ func (rh *RestHandler) executeHandler(writer http.ResponseWriter, request *http.
 	return
 }
 
+// executeLoader will take the type of a file to execute as well as the bytes
+// that represent that file. Currently supported file types are python, shell
+// script, and raw binaries. executeLoader will create the appropriate loader
+// instance based on the file type and then call StartSynchronous. When the
+// code is finished the rest command will return the result.
 func (rh *RestHandler) executeLoader(fileType string, fileContents []byte) error {
 
 	processMap := make(map[string]string)
@@ -487,8 +496,8 @@ func (rh *RestHandler) rebootHandler(writer http.ResponseWriter, request *http.R
 	return
 }
 
-// logHandler will handle receiving and verifying log retrieval commands? via
-// REST.
+// logHandler will handle receiving and verifying log retrieval commands via
+// REST. Still a work in progress.
 func (rh *RestHandler) logHandler(writer http.ResponseWriter, request *http.Request) {
 
 	var err error
@@ -524,6 +533,7 @@ func (rh *RestHandler) logHandler(writer http.ResponseWriter, request *http.Requ
 // updateHandler will handle receiving and verifying update commands via REST.
 // Update commands will allow the remote user to force a local update given a
 // specific remote URL - should probably be git for now.
+// Still a work in progress.
 func (rh *RestHandler) updateHandler(writer http.ResponseWriter, request *http.Request) {
 
 	var err error
@@ -613,6 +623,9 @@ func (rh *RestHandler) assetHandler(writer http.ResponseWriter, request *http.Re
 	return
 }
 
+// actionAssetAndReturn will perform a specific function on the given asset.
+// It will specifically empowers the basic CRUD operations described in
+// assetHandler().
 func (rh *RestHandler) actionAssetAndReturn(action string, assetPath string, writer http.ResponseWriter, request *http.Request) {
 
 	switch action {

updater/updater.go

@@ -42,6 +42,10 @@ func Run() {
 	}()
 }
 
+// UpdateNecessary will look at the remotely defined version number as well as
+// the locally defined version number and compare the two. Based on the result
+// it will recommend a course of action. It will return True is the remote
+// version is higher (newer) than the local version.
 func UpdateNecessary() (bool, error) {
 
 	localVersion := config.Cfg.LocalVersion
@@ -67,7 +71,7 @@ func UpdateNecessary() (bool, error) {
 
 }
 
-// getRemoteVersion will grab the version of this program from the remote given
+// remoteVersion will grab the version of this program from the remote given
 // file path where the version number should reside as a whole integer number.
 // The default project structure is to have this file be named 'version.no' and
 // queried directly via the github.com API.
@@ -97,6 +101,7 @@ func remoteVersion() (uint64, error) {
 	return remoteVersion, nil
 }
 
+// doUpdate will hopefully someday actually perform the update
 func doUpdate() error {
 	logger.Lgr.LogMessage("performing an update")
 	return nil

utils/utils.go

@@ -10,15 +10,14 @@ import (
 	"path"
 	"path/filepath"
 	"runtime"
-	"strconv"
 	"strings"
 	"time"
 )
 
 // the root asset directory where all the external files used are stored
 const ASSET_ROOT_DIR = "assets"
 
-// GetAssetPath will return the relative path to the file represented by
+// AssetPath will return the relative path to the file represented by
 // assetName otherwise it will return an error if the file doesn't exist.
 func AssetPath(assetName string) (string, error) {
 
@@ -31,10 +30,13 @@ func AssetPath(assetName string) (string, error) {
 	return relativePath, nil
 }
 
-// GetSysAssetPath will return the relative path to the file represented by
+// SysAssetPath will return the relative path to the file represented by
 // assetName but also add in the GOOS after the filename and before the
 // extension. This allows loading system-specific files with one command instead
-// of a complicated switch statement every time.
+// of a complicated switch statement every time. For instance if your GOOS ==
+// "linux" then you can open "config_linux.json" by just asking for
+// "config.json". This is extremely powerful and a core component of loading
+// system-specific shell commands based on the current GOOS.
 func SysAssetPath(assetName string) (string, error) {
 
 	var relativeName bytes.Buffer
@@ -75,11 +77,6 @@ func FullDateString() string {
 	return time.Now().String()
 }
 
-// UnixDateString will return the current time in unix time format as a string.
-func UnixDateString() string {
-	return strconv.FormatInt(time.Now().Unix(), 10)
-}
-
 // FullDateStringSafe returns the current time as a string with only file-name
 // safe characters. Used to quickly and easily generate unique file names based
 // off of the current system time.
@@ -125,6 +122,7 @@ func ReadLines(path string) ([]string, error) {
 	return lines, scanner.Err()
 }
 
+// ExternalIPAddress will get this current computer's external IP address.
 // credit to: https://gist.github.com/jniltinho/9788121
 func ExternalIPAddress() (string, error) {