Properly format function documentation comments

core/1globals.go

@@ -4,12 +4,10 @@ import (
 	"os"
 )
 
-// global variables used across multiple files
 var (
 	Home, _ = os.UserHomeDir()
 )
 
-// global constants used across multiple files
 const (
 	AnsiError        = "\033[38;5;9m"
 	AnsiReset        = "\033[0m"

core/2globalsUNIX.go

@@ -2,19 +2,17 @@
 
 package core
 
-// EntryRoot path to libmutton entry directory
-var EntryRoot = Home + "/.local/share/libmutton"
-var ConfigDir = Home + "/.config/libmutton"
-var ConfigPath = ConfigDir + "/libmutton.ini"
+var EntryRoot = Home + "/.local/share/libmutton" // path to libmutton entry directory
+var ConfigDir = Home + "/.config/libmutton"      // path to libmutton configuration directory
+var ConfigPath = ConfigDir + "/libmutton.ini"    // path to libmutton configuration file
 
-// PathSeparator defines the character used to separate directories in a path (platform-specific)
 const (
-	PathSeparator = "/"
-	IsWindows     = false
+	PathSeparator = "/"   // platform-specific path separator
+	IsWindows     = false // platform indicator
 )
 
-// enableVirtualTerminalProcessing is a dummy function on UNIX-like systems (only needed on Windows)
-// TODO remove after migration off of GPG, as pinentry is responsible for disabling ANSI escape sequence interpretation
+// enableVirtualTerminalProcessing is a dummy function on UNIX-like systems (only needed on Windows).
+// TODO Remove after migration off of GPG, as pinentry is responsible for disabling ANSI escape sequence interpretation.
 func enableVirtualTerminalProcessing() {
 	return
 }

core/2globalsWIN.go

@@ -7,19 +7,17 @@ import (
 	"syscall"
 )
 
-// EntryRoot path to libmutton entry directory
-var EntryRoot = Home + "\\AppData\\Local\\libmutton\\entries"
-var ConfigDir = Home + "\\AppData\\Local\\libmutton\\config"
-var ConfigPath = ConfigDir + "\\libmutton.ini"
+var EntryRoot = Home + "\\AppData\\Local\\libmutton\\entries" // path to libmutton entry directory
+var ConfigDir = Home + "\\AppData\\Local\\libmutton\\config"  // path to libmutton configuration directory
+var ConfigPath = ConfigDir + "\\libmutton.ini"                // path to libmutton configuration file
 
-// PathSeparator defines the character used to separate directories in a path (platform-specific)
 const (
-	PathSeparator = "\\"
-	IsWindows     = true
+	PathSeparator = "\\" // platform-specific path separator
+	IsWindows     = true // platform indicator
 )
 
-// enableVirtualTerminalProcessing ensures ANSI escape sequences are interpreted properly on Windows
-// TODO remove after migration off of GPG, as pinentry is responsible for disabling ANSI escape sequence interpretation
+// enableVirtualTerminalProcessing ensures ANSI escape sequences are interpreted properly on Windows.
+// TODO Remove after migration off of GPG, as pinentry is responsible for disabling ANSI escape sequence interpretation.
 func enableVirtualTerminalProcessing() {
 	stdout := syscall.Handle(os.Stdout.Fd())
 

core/configParser.go

@@ -7,8 +7,8 @@ import (
 	"gopkg.in/ini.v1"
 )
 
-// loadConfig loads the libmutton.ini file and returns the configuration
-// utility function for ParseConfig and WriteConfig, do not call directly
+// loadConfig loads the libmutton.ini file and returns the configuration.
+// It is a utility function for ParseConfig and WriteConfig; do not call directly.
 func loadConfig() *ini.File {
 	cfg, err := ini.Load(ConfigPath)
 	if err != nil {
@@ -18,10 +18,10 @@ func loadConfig() *ini.File {
 	return cfg
 }
 
-// ParseConfig reads the libmutton.ini file and returns a slice of values for the specified keys
-// requires requestedValues: a slice of arrays (length 2) each containing a section and a key name
-// requires missingValueError: an error message to display if a key is missing a value, set to "" for auto-generated or "0" to exit/return silently with code 0
-// returns config: a slice of values for the specified keys
+// ParseConfig reads the libmutton.ini file and returns a slice of values for the specified keys.
+// Requires: requestedValues (a slice of length 2 arrays each containing a section and a key name),
+// missingValueError (an error message to display if a key is missing a value, set to "" for auto-generated or "0" to exit/return silently with code 0).
+// Returns: config (slice of values for the specified keys).
 func ParseConfig(valuesRequested [][2]string, missingValueError string) []string {
 	cfg := loadConfig()
 
@@ -49,8 +49,8 @@ func ParseConfig(valuesRequested [][2]string, missingValueError string) []string
 	return config
 }
 
-// WriteConfig writes the provided key-value pairs under the specified section headers in the libmutton.ini file
-// requires valuesToWrite: a slice of arrays (length 3) each containing a section, a key name, and a value
+// WriteConfig writes the provided key-value pairs under the specified section headers in the libmutton.ini file.
+// Requires: valuesToWrite (a slice of length 3 arrays each containing a section, a key name, and a value).
 func WriteConfig(valuesToWrite [][3]string, append bool) {
 	var cfg *ini.File
 

core/copy.go

@@ -11,7 +11,7 @@ import (
 	"github.com/pquerna/otp/totp"
 )
 
-// CopyArgument copies a field from an entry to the clipboard
+// CopyArgument copies a field from an entry to the clipboard.
 func CopyArgument(executableName, targetLocation string, field int) {
 	if isFile, _ := TargetIsFile(targetLocation, true, 2); isFile {
 
@@ -59,7 +59,7 @@ func CopyArgument(executableName, targetLocation string, field int) {
 	}
 }
 
-// ClipClearArgument is called to clear the clipboard after 30 seconds if the contents have not been modified
+// ClipClearArgument is called to clear the clipboard after 30 seconds if the contents have not been modified.
 func ClipClearArgument() {
 	// read previous clipboard contents from stdin
 	clipScanner := bufio.NewScanner(os.Stdin)
@@ -71,7 +71,7 @@ func ClipClearArgument() {
 	}
 }
 
-// GenTOTP generates a TOTP token from a secret (supports standard and Steam TOTP)
+// GenTOTP generates a TOTP token from a secret (supports standard and Steam TOTP).
 func GenTOTP(secret string, time time.Time, forSteam bool) string {
 	var totpToken string
 	var err error

core/copyDARWIN.go

@@ -10,9 +10,7 @@ import (
 	"time"
 )
 
-// TODO MacOS support is entirely untested - I would appreciate feedback on this implementation
-
-// copyField copies a field from an entry to the clipboard
+// copyField copies a field from an entry to the clipboard.
 func copyField(executableName, copySubject string) {
 	cmd := exec.Command("pbcopy")
 	writeToStdin(cmd, copySubject)
@@ -35,7 +33,7 @@ func copyField(executableName, copySubject string) {
 	}
 }
 
-// clipClear is called in a separate process to clear the clipboard after 30 seconds
+// clipClear is called in a separate process to clear the clipboard after 30 seconds.
 func clipClear(oldContents string) {
 	time.Sleep(30 * time.Second)
 

core/copyTERMUX.go

@@ -10,7 +10,7 @@ import (
 	"time"
 )
 
-// copyField copies a field from an entry to the clipboard
+// copyField copies a field from an entry to the clipboard.
 func copyField(executableName, copySubject string) {
 	cmd := exec.Command("termux-clipboard-set")
 	writeToStdin(cmd, copySubject)
@@ -33,7 +33,7 @@ func copyField(executableName, copySubject string) {
 	}
 }
 
-// clipClear is called in a separate process to clear the clipboard after 30 seconds
+// clipClear is called in a separate process to clear the clipboard after 30 seconds.
 func clipClear(oldContents string) {
 	time.Sleep(30 * time.Second)
 

core/copyUNIXGeneric.go

@@ -10,7 +10,7 @@ import (
 	"time"
 )
 
-// copyField copies a field from an entry to the clipboard
+// copyField copies a field from an entry to the clipboard.
 func copyField(executableName, copySubject string) {
 	var envSet bool // track whether environment variables are set
 	var cmd *exec.Cmd
@@ -44,7 +44,7 @@ func copyField(executableName, copySubject string) {
 	}
 }
 
-// clipClear is called in a separate process to clear the clipboard after 30 seconds
+// clipClear is called in a separate process to clear the clipboard after 30 seconds.
 func clipClear(oldContents string) {
 	time.Sleep(30 * time.Second)
 

core/copyWIN.go

@@ -10,7 +10,7 @@ import (
 	"time"
 )
 
-// copyField copies a field from an entry to the clipboard
+// copyField copies a field from an entry to the clipboard.
 func copyField(executableName, copySubject string) {
 	cmd := exec.Command("powershell.exe", "-c", fmt.Sprintf("echo '%s' | Set-Clipboard", strings.ReplaceAll(copySubject, "'", "''")))
 	err := cmd.Run()
@@ -32,7 +32,7 @@ func copyField(executableName, copySubject string) {
 	}
 }
 
-// clipClear is called in a separate process to clear the clipboard after 30 seconds
+// clipClear is called in a separate process to clear the clipboard after 30 seconds.
 func clipClear(oldContents string) {
 	time.Sleep(30 * time.Second)
 

core/edit.go

@@ -1,6 +1,6 @@
 package core
 
-// GetOldEntryData decrypts and returns old entry data (with all required lines present)
+// GetOldEntryData decrypts and returns old entry data (with all required lines present).
 func GetOldEntryData(targetLocation string, field int) []string {
 	// ensure targetLocation exists
 	TargetIsFile(targetLocation, true, 2)
@@ -10,14 +10,14 @@ func GetOldEntryData(targetLocation string, field int) []string {
 
 	// return the old entry data with all required lines present
 	if field > 0 {
-		return EnsureSliceLength(unencryptedEntry, field)
+		return ensureSliceLength(unencryptedEntry, field)
 	} else {
 		return unencryptedEntry
 	}
 }
 
-// EnsureSliceLength ensures slice is long enough to contain the specified index
-func EnsureSliceLength(slice []string, index int) []string {
+// ensureSliceLength is a utility function that ensures a slice is long enough to contain the specified index.
+func ensureSliceLength(slice []string, index int) []string {
 	for len(slice) <= index {
 		slice = append(slice, "")
 	}

core/exitHard.go

@@ -4,6 +4,7 @@ package core
 
 import "os"
 
+// Exit (hard) is meant to be used in non-interactive CLI implementations to exit the program after an operation.
 func Exit(code int) {
 	os.Exit(code)
 }

core/exitSoft.go

@@ -2,6 +2,7 @@
 
 package core
 
+// Exit (soft) is meant to be used in interactive implementations (GUIs/TUIs) to keep the program running after an operation.
 func Exit(code int) {
 	return code
 }

core/gpg.go

@@ -9,7 +9,7 @@ import (
 
 // TODO GPG support is a temporary feature - it will be replaced with a different encryption scheme in the future
 
-// DecryptGPG decrypts a GPG-encrypted file and returns the contents as a slice of (trimmed) strings
+// DecryptGPG decrypts a GPG-encrypted file and returns the contents as a slice of (trimmed) strings.
 func DecryptGPG(targetLocation string) []string {
 	cmd := exec.Command("gpg", "--pinentry-mode", "loopback", "-q", "-d", targetLocation)
 	output, err := cmd.Output()
@@ -26,7 +26,7 @@ func DecryptGPG(targetLocation string) []string {
 	return outputSlice
 }
 
-// EncryptGPG encrypts a slice of strings using GPG and returns the encrypted data as a byte slice
+// EncryptGPG encrypts a slice of strings using GPG and returns the encrypted data as a byte slice.
 func EncryptGPG(input []string) []byte {
 	cmd := exec.Command("gpg", "-q", "-r", ParseConfig([][2]string{{"LIBMUTTON", "gpgID"}}, "")[0], "-e")
 	writeToStdin(cmd, strings.Join(input, "\n"))

core/init.go

@@ -9,7 +9,7 @@ import (
 	"time"
 )
 
-// GpgUIDListGen generates a list of all GPG key IDs on the system and returns them as a slice of strings
+// GpgUIDListGen generates a list of all GPG key IDs on the system and returns them as a slice of strings.
 func GpgUIDListGen() []string {
 	cmd := exec.Command("gpg", "-k", "--with-colons")
 	gpgOutputBytes, _ := cmd.Output()
@@ -24,7 +24,7 @@ func GpgUIDListGen() []string {
 	return uidSlice
 }
 
-// GpgKeyGen generates a new GPG key and returns the key ID
+// GpgKeyGen generates a new GPG key and returns the key ID.
 func GpgKeyGen() string {
 	gpgGenTempFile := CreateTempFile()
 	defer func(name string) {
@@ -52,7 +52,7 @@ func GpgKeyGen() string {
 	return "libmutton-" + unixTime + " (gpg-libmutton) <github.com/rwinkhart/libmutton>"
 }
 
-// DirInit creates the libmutton directories
+// DirInit creates the libmutton directories.
 func DirInit(preserveOldConfigDir bool) {
 	// create EntryRoot
 	err := os.MkdirAll(EntryRoot, 0700)

core/targetLocationFormatUNIX.go

@@ -2,7 +2,7 @@
 
 package core
 
-// TargetLocationFormat returns the full location of an entry (given the name) formatted for the current platform
+// TargetLocationFormat returns the full location of an entry (given the name) formatted for the current platform.
 func TargetLocationFormat(targetLocationIncomplete string) string {
 	return EntryRoot + targetLocationIncomplete
 }

core/targetLocationFormatWIN.go

@@ -4,7 +4,7 @@ package core
 
 import "strings"
 
-// TargetLocationFormat returns the full location of an entry (given the name) formatted for the current platform
+// TargetLocationFormat returns the full location of an entry (given the name) formatted for the current platform.
 func TargetLocationFormat(targetLocationIncomplete string) string {
 	return EntryRoot + strings.ReplaceAll(targetLocationIncomplete, "/", PathSeparator)
 }

core/utilitiesMisc.go

@@ -11,9 +11,9 @@ import (
 	"strings"
 )
 
-// TargetIsFile TargetStatusCheck checks if the targetLocation is a file, directory, or is inaccessible
-// failCondition: 0 = fail on inaccessible, 1 = fail on inaccessible/file, 2 = fail on inaccessible/directory
-// returns: isFile, isAccessible
+// TargetIsFile checks if the targetLocation is a file, directory, or is inaccessible.
+// Requires: failCondition (0 = fail on inaccessible, 1 = fail on inaccessible&file, 2 = fail on inaccessible&directory).
+// Returns: isFile, isAccessible.
 func TargetIsFile(targetLocation string, errorOnFail bool, failCondition uint8) (bool, bool) {
 	targetInfo, err := os.Stat(targetLocation)
 	if err != nil {
@@ -39,7 +39,7 @@ func TargetIsFile(targetLocation string, errorOnFail bool, failCondition uint8)
 	}
 }
 
-// WriteEntry writes entryData to an encrypted file at targetLocation
+// WriteEntry writes entryData to an encrypted file at targetLocation.
 func WriteEntry(targetLocation string, entryData []string, verifyEntryDoesNotExist bool) {
 	if verifyEntryDoesNotExist {
 		_, isAccessible := TargetIsFile(targetLocation, false, 0)
@@ -57,7 +57,7 @@ func WriteEntry(targetLocation string, entryData []string, verifyEntryDoesNotExi
 	}
 }
 
-// writeToStdin writes a string to a command's stdin
+// writeToStdin is a utility function that writes a string to a command's stdin.
 func writeToStdin(cmd *exec.Cmd, input string) {
 	stdin, err := cmd.StdinPipe()
 	if err != nil {
@@ -73,7 +73,7 @@ func writeToStdin(cmd *exec.Cmd, input string) {
 	}()
 }
 
-// CreateTempFile creates a temporary file and returns a pointer to it
+// CreateTempFile creates a temporary file and returns a pointer to it.
 func CreateTempFile() *os.File {
 	tempFile, err := os.CreateTemp("", "*.markdown")
 	if err != nil {
@@ -83,7 +83,7 @@ func CreateTempFile() *os.File {
 	return tempFile
 }
 
-// RemoveTrailingEmptyStrings removes empty strings from the end of a slice
+// RemoveTrailingEmptyStrings removes empty strings from the end of a slice.
 func RemoveTrailingEmptyStrings(slice []string) []string {
 	for i := len(slice) - 1; i >= 0; i-- {
 		if slice[i] != "" {
@@ -93,9 +93,9 @@ func RemoveTrailingEmptyStrings(slice []string) []string {
 	return []string{}
 }
 
-// StringGen generates a random string of a specified length and complexity
-// safeForFileName: if true, the generated string will only contain special characters that are safe for file names (only impacts complex strings)
-// complexity: minimum percentage of special characters to be returned in the generated string (only impacts complex strings)
+// StringGen generates a random string of a specified length and complexity.
+// Requires: complexity (minimum percentage of special characters to be returned in the generated string; only impacts complex strings),
+// safeForFileName: (if true, the generated string will only contain special characters that are safe for file names; only impacts complex strings).
 func StringGen(length int, complex bool, complexity float64, safeForFileName bool) string {
 	var actualSpecialChars int // track the number of special characters in the generated string
 	var minSpecialChars int    // track the minimum number of special characters to accept
@@ -146,7 +146,7 @@ func StringGen(length int, complex bool, complexity float64, safeForFileName boo
 	}
 }
 
-// EntryIsNotEmpty iterates through entryData and returns true if any line is not empty
+// EntryIsNotEmpty iterates through entryData and returns true if any line is not empty.
 func EntryIsNotEmpty(entryData []string) bool {
 	for _, line := range entryData {
 		if line != "" {