From 06b9527a3373d8a677f93bccea447d45ea794c6a Mon Sep 17 00:00:00 2001 From: Randall Winkhart Date: Sun, 11 Aug 2024 16:37:28 -0400 Subject: [PATCH] Properly format function documentation comments --- core/1globals.go | 2 -- core/2globalsUNIX.go | 16 ++++++------- core/2globalsWIN.go | 16 ++++++------- core/configParser.go | 16 ++++++------- core/copy.go | 6 ++--- core/copyDARWIN.go | 6 ++--- core/copyTERMUX.go | 4 ++-- core/copyUNIXGeneric.go | 4 ++-- core/copyWIN.go | 4 ++-- core/edit.go | 8 +++---- core/exitHard.go | 1 + core/exitSoft.go | 1 + core/gpg.go | 4 ++-- core/init.go | 6 ++--- core/targetLocationFormatUNIX.go | 2 +- core/targetLocationFormatWIN.go | 2 +- core/utilitiesMisc.go | 22 +++++++++--------- sync/1globals.go | 4 +--- sync/client.go | 40 ++++++++++++++++---------------- sync/common.go | 20 ++++++++-------- sync/commonUNIX.go | 6 ++--- sync/commonWIN.go | 6 ++--- sync/init.go | 8 +++---- sync/input.go | 7 +++--- sync/server.go | 6 ++--- 25 files changed, 105 insertions(+), 112 deletions(-) diff --git a/core/1globals.go b/core/1globals.go index 055e9b2..2b4c0bd 100644 --- a/core/1globals.go +++ b/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" diff --git a/core/2globalsUNIX.go b/core/2globalsUNIX.go index c24a3a3..88c800d 100644 --- a/core/2globalsUNIX.go +++ b/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 } diff --git a/core/2globalsWIN.go b/core/2globalsWIN.go index 5f4539b..92cd134 100644 --- a/core/2globalsWIN.go +++ b/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()) diff --git a/core/configParser.go b/core/configParser.go index ea471e1..8174b4b 100644 --- a/core/configParser.go +++ b/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 diff --git a/core/copy.go b/core/copy.go index dc74ae8..5cd47f1 100644 --- a/core/copy.go +++ b/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 diff --git a/core/copyDARWIN.go b/core/copyDARWIN.go index 3acd452..e0fa150 100644 --- a/core/copyDARWIN.go +++ b/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) diff --git a/core/copyTERMUX.go b/core/copyTERMUX.go index dc5b70b..550851f 100644 --- a/core/copyTERMUX.go +++ b/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) diff --git a/core/copyUNIXGeneric.go b/core/copyUNIXGeneric.go index 11768e1..c6c6a82 100644 --- a/core/copyUNIXGeneric.go +++ b/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) diff --git a/core/copyWIN.go b/core/copyWIN.go index b7f865c..3671b90 100644 --- a/core/copyWIN.go +++ b/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) diff --git a/core/edit.go b/core/edit.go index fb7cdb0..5127f03 100644 --- a/core/edit.go +++ b/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, "") } diff --git a/core/exitHard.go b/core/exitHard.go index df16b53..f59292b 100644 --- a/core/exitHard.go +++ b/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) } diff --git a/core/exitSoft.go b/core/exitSoft.go index 0680291..8845fe8 100644 --- a/core/exitSoft.go +++ b/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 } diff --git a/core/gpg.go b/core/gpg.go index e1a6721..d868f5d 100644 --- a/core/gpg.go +++ b/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")) diff --git a/core/init.go b/core/init.go index 68aeced..2d26e3b 100644 --- a/core/init.go +++ b/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) " } -// DirInit creates the libmutton directories +// DirInit creates the libmutton directories. func DirInit(preserveOldConfigDir bool) { // create EntryRoot err := os.MkdirAll(EntryRoot, 0700) diff --git a/core/targetLocationFormatUNIX.go b/core/targetLocationFormatUNIX.go index 4162419..ca99a30 100644 --- a/core/targetLocationFormatUNIX.go +++ b/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 } diff --git a/core/targetLocationFormatWIN.go b/core/targetLocationFormatWIN.go index b1f8ce4..bfe1101 100644 --- a/core/targetLocationFormatWIN.go +++ b/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) } diff --git a/core/utilitiesMisc.go b/core/utilitiesMisc.go index c5f871b..308bff1 100644 --- a/core/utilitiesMisc.go +++ b/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 != "" { diff --git a/sync/1globals.go b/sync/1globals.go index 53367f1..58972e4 100644 --- a/sync/1globals.go +++ b/sync/1globals.go @@ -2,12 +2,10 @@ package sync import "github.com/rwinkhart/libmutton/core" -// define field separator constants const ( FSSpace = "\u259d" // ▝ space/list separator FSPath = "\u259e" // ▞ path separator FSMisc = "\u259f" // ▟ misc. field separator (if \u259d is already used) ) -// rootLength stores length of core.EntryRoot string -var rootLength = len(core.EntryRoot) +var rootLength = len(core.EntryRoot) // length of core.EntryRoot string diff --git a/sync/client.go b/sync/client.go index 9a4258b..96df1e7 100644 --- a/sync/client.go +++ b/sync/client.go @@ -13,15 +13,15 @@ import ( "golang.org/x/crypto/ssh/knownhosts" ) -// global constants used only in this file +// ANSI color constants used only in this file const ( ansiDelete = "\033[38;5;1m" ansiDownload = "\033[38;5;2m" ansiUpload = "\033[38;5;4m" ) -// GetSSHClient returns an SSH client connection to the server (also returns the remote EntryRoot as a string and the server's OS as a bool - IsWindows) -// only supports key-based authentication (passphrases are supported for CLI-based implementations) +// GetSSHClient returns an SSH client connection to the server (also returns the remote EntryRoot and an indicator of the server's OS). +// Only supports key-based authentication (passphrases are supported for CLI-based implementations). func GetSSHClient(manualSync bool) (*ssh.Client, string, bool) { // get SSH config info, exit if not configured (displaying an error if the sync job was called manually) var sshUserConfig []string @@ -99,7 +99,7 @@ func GetSSHClient(manualSync bool) (*ssh.Client, string, bool) { return sshClient, entryRoot, isWindows } -// GetSSHOutput runs a command over SSH and returns the output as a string +// GetSSHOutput runs a command over SSH and returns the output as a string. func GetSSHOutput(sshClient *ssh.Client, cmd, stdin string) string { // create a session sshSession, err := sshClient.NewSession() @@ -126,7 +126,7 @@ func GetSSHOutput(sshClient *ssh.Client, cmd, stdin string) string { return outputString } -// getRemoteDataFromClient returns a map of remote entries to their modification times, a list of remote folders, a list of queued deletions, and the current server+client times as UNIX timestamps +// getRemoteDataFromClient returns a map of remote entries to their modification times, a list of remote folders, a list of queued deletions, and the current server&client times as UNIX timestamps. func getRemoteDataFromClient(sshClient *ssh.Client, manualSync bool) (map[string]int64, []string, []string, int64, int64) { // get remote output over SSH clientDeviceID, _ := os.ReadDir(core.ConfigDir + core.PathSeparator + "devices") @@ -171,7 +171,7 @@ func getRemoteDataFromClient(sshClient *ssh.Client, manualSync bool) (map[string return entryModMap, folders, deletions, serverTime, clientTime } -// getLocalData returns a map of local entries to their modification times +// getLocalData returns a map of local entries to their modification times. func getLocalData() map[string]int64 { // get a list of all entries entries, _ := WalkEntryDir() @@ -189,7 +189,7 @@ func getLocalData() map[string]int64 { return entryModMap } -// targetLocationFormatSFTP formats the target location to match the remote server's entry directory and path separator +// targetLocationFormatSFTP formats the target location to match the remote server's entry directory and path separator. func targetLocationFormatSFTP(targetName, serverEntryRoot string, serverIsWindows bool) string { if !serverIsWindows { return serverEntryRoot + targetName @@ -198,7 +198,7 @@ func targetLocationFormatSFTP(targetName, serverEntryRoot string, serverIsWindow } } -// sftpSync takes two slices of entries (one for downloads and one for uploads) and syncs them between the client and server using SFTP +// sftpSync takes two slices of entries (one for downloads and one for uploads) and syncs them between the client and server using SFTP. func sftpSync(sshClient *ssh.Client, sshEntryRoot string, sshIsWindows bool, downloadList, uploadList []string) { // create an SFTP client from sshClient sftpClient, err := sftp.NewClient(sshClient) @@ -323,8 +323,8 @@ func sftpSync(sshClient *ssh.Client, sshEntryRoot string, sshIsWindows bool, dow } } -// syncLists determines which entries need to be downloaded and uploaded for synchronizations and calls sftpSync with this information -// using maps means that syncing will be done in an arbitrary order, but it is a worthy tradeoff for speed and simplicity +// syncLists determines which entries need to be downloaded and uploaded for synchronizations and calls sftpSync with this information. +// Using maps means that syncing will be done in an arbitrary order, but it is a worthy tradeoff for speed and simplicity. func syncLists(sshClient *ssh.Client, sshEntryRoot string, sshIsWindows, timeSynced bool, localEntryModMap, remoteEntryModMap map[string]int64) { // initialize slices to store entries that need to be downloaded or uploaded var downloadList, uploadList []string @@ -367,7 +367,7 @@ func syncLists(sshClient *ssh.Client, sshEntryRoot string, sshIsWindows, timeSyn fmt.Println("Client is synchronized with server") } -// deletionSync removes entries from the client that have been deleted on the server (multi-client deletion) +// deletionSync removes entries from the client that have been deleted on the server (multi-client deletion). func deletionSync(deletions []string) { var filesDeleted bool for _, deletion := range deletions { @@ -381,8 +381,8 @@ func deletionSync(deletions []string) { } } -// ShearRemoteFromClient removes the target file or directory from the local system and calls the server to remove it remotely and add it to the deletions list -// can safely be called in offline mode, as well, so this is the intended interface for shearing (ShearLocal should only be used directly by the server binary) +// ShearRemoteFromClient removes the target file or directory from the local system and calls the server to remove it remotely and add it to the deletions list. +// It can safely be called in offline mode, as well, so this is the intended interface for shearing (ShearLocal should only be used directly by the server binary). func ShearRemoteFromClient(sshClient *ssh.Client, targetLocationIncomplete string) { deviceID := ShearLocal(targetLocationIncomplete, "") // remove the target from the local system and get the device ID of the client @@ -394,8 +394,8 @@ func ShearRemoteFromClient(sshClient *ssh.Client, targetLocationIncomplete strin core.Exit(0) // sync is not required after shearing since the target has already been removed from the local system } -// RenameRemoteFromClient renames oldLocationIncomplete to newLocationIncomplete on the local system and calls the server to perform the rename remotely and add the old target to the deletions list -// can safely be called in offline mode, as well, so this is the intended interface for renaming (RenameLocal should only be used directly by the server binary) +// RenameRemoteFromClient renames oldLocationIncomplete to newLocationIncomplete on the local system and calls the server to perform the rename remotely and add the old target to the deletions list. +// It can safely be called in offline mode, as well, so this is the intended interface for renaming (RenameLocal should only be used directly by the server binary). func RenameRemoteFromClient(sshClient *ssh.Client, oldLocationIncomplete, newLocationIncomplete string) { RenameLocal(oldLocationIncomplete, newLocationIncomplete, false) // move the target on the local system @@ -411,8 +411,8 @@ func RenameRemoteFromClient(sshClient *ssh.Client, oldLocationIncomplete, newLoc core.Exit(0) } -// AddFolderRemoteFromClient creates a new entry-containing directory on the local system and calls the server to create the folder remotely -// can safely be called in offline mode, as well, so this is the intended interface for adding folders (AddFolderLocal should only be used directly by the server binary) +// AddFolderRemoteFromClient creates a new entry-containing directory on the local system and calls the server to create the folder remotely. +// It can safely be called in offline mode, as well, so this is the intended interface for adding folders (AddFolderLocal should only be used directly by the server binary). func AddFolderRemoteFromClient(sshClient *ssh.Client, targetLocationIncomplete string) { AddFolderLocal(targetLocationIncomplete) // add the folder on the local system GetSSHOutput(sshClient, "libmuttonserver addfolder", strings.ReplaceAll(targetLocationIncomplete, core.PathSeparator, FSPath)) // call the server to create the folder remotely @@ -420,7 +420,7 @@ func AddFolderRemoteFromClient(sshClient *ssh.Client, targetLocationIncomplete s core.Exit(0) } -// folderSync creates folders on the client (from the given list of folder names) +// folderSync creates folders on the client (from the given list of folder names). func folderSync(folders []string) { for _, folder := range folders { // store the full local path of the folder @@ -438,8 +438,8 @@ func folderSync(folders []string) { } } -// RunJob runs the SSH sync job -// setting manualSync to true will throw errors if sync is not configured, as online mode is assumed +// RunJob runs the SSH sync job. +// Setting manualSync to true will throw errors if sync is not configured (online mode is assumed). func RunJob(manualSync bool) { // get SSH client to re-use throughout the sync process sshClient, sshEntryRoot, sshIsWindows := GetSSHClient(manualSync) diff --git a/sync/common.go b/sync/common.go index 0141a08..6b5f779 100644 --- a/sync/common.go +++ b/sync/common.go @@ -9,7 +9,7 @@ import ( "github.com/rwinkhart/libmutton/core" ) -// getModTimes returns a list of all entry modification times +// getModTimes returns a list of all entry modification times. func getModTimes(entryList []string) []int64 { var modList []int64 for _, file := range entryList { @@ -20,7 +20,7 @@ func getModTimes(entryList []string) []int64 { return modList } -// genDeviceIDList returns a pointer to a slice of all registered device IDs +// genDeviceIDList returns a pointer to a slice of all registered device IDs. func genDeviceIDList() *[]fs.DirEntry { // create a slice of all registered devices deviceIDList, err := os.ReadDir(core.ConfigDir + core.PathSeparator + "devices") @@ -31,10 +31,10 @@ func genDeviceIDList() *[]fs.DirEntry { return &deviceIDList } -// ShearLocal removes the target file or directory from the local system -// returns: deviceID (on client), for use in ShearRemoteFromClient -// if the local system is a server, it will also add the target to the deletions list for all clients (except the requesting client) -// this function should only be used directly by the server binary +// ShearLocal removes the target file or directory from the local system. +// Returns: deviceID (only on client; for use in ShearRemoteFromClient). +// If the local system is a server, it will also add the target to the deletions list for all clients (except the requesting client). +// This function should only be used directly by the server binary. func ShearLocal(targetLocationIncomplete, clientDeviceID string) string { // determine if running on a server var onServer bool @@ -77,8 +77,8 @@ func ShearLocal(targetLocationIncomplete, clientDeviceID string) string { // do not exit program, as this function is used as part of ShearRemoteFromClient } -// RenameLocal renames oldLocationIncomplete to newLocationIncomplete on the local system -// this function should only be used directly by the server binary +// RenameLocal renames oldLocationIncomplete to newLocationIncomplete on the local system. +// This function should only be used directly by the server binary. func RenameLocal(oldLocationIncomplete, newLocationIncomplete string, verifyOldLocationExists bool) { // get full paths for both locations oldLocation := core.TargetLocationFormat(oldLocationIncomplete) @@ -104,8 +104,8 @@ func RenameLocal(oldLocationIncomplete, newLocationIncomplete string, verifyOldL // do not exit program, as this function is used as part of RenameRemoteFromClient } -// AddFolderLocal creates a new entry-containing directory on the local system -// this function should only be used directly by the server binary +// AddFolderLocal creates a new entry-containing directory on the local system. +// This function should only be used directly by the server binary. func AddFolderLocal(targetLocationIncomplete string) { // get the full targetLocation path and create the target targetLocationComplete := core.TargetLocationFormat(targetLocationIncomplete) diff --git a/sync/commonUNIX.go b/sync/commonUNIX.go index e0b77de..1071f7f 100644 --- a/sync/commonUNIX.go +++ b/sync/commonUNIX.go @@ -11,8 +11,8 @@ import ( "github.com/rwinkhart/libmutton/core" ) -// WalkEntryDir walks the entry directory and returns lists of all files and directories found (two separate lists) -// regardless of platform, all paths are stored with forward slashes (UNIX-style) +// WalkEntryDir walks the entry directory and returns lists of all files and directories found (two separate lists). +// Regardless of platform, all paths are stored with forward slashes (UNIX-style). func WalkEntryDir() ([]string, []string) { // define file/directory containing slices so that they may be accessed by the anonymous WalkDir function var fileList []string @@ -49,7 +49,7 @@ func WalkEntryDir() ([]string, []string) { return fileList, dirList } -// joinErrorWithEXE joins and returns the two strings it is provided (in error format) with the executable name inserted between them +// joinErrorWithEXE is a utility function that joins and returns the two strings it is provided (in error format) with the executable name inserted between them. func joinErrorWithEXE(firstHalf, secondHalf string) string { return core.AnsiError + firstHalf + os.Args[0] + secondHalf + core.AnsiReset } diff --git a/sync/commonWIN.go b/sync/commonWIN.go index ff0276b..9ea5e1a 100644 --- a/sync/commonWIN.go +++ b/sync/commonWIN.go @@ -12,8 +12,8 @@ import ( "github.com/rwinkhart/libmutton/core" ) -// WalkEntryDir walks the entry directory and returns lists of all files and directories found (two separate lists) -// regardless of platform, all paths are stored with forward slashes (UNIX-style) +// WalkEntryDir walks the entry directory and returns lists of all files and directories found (two separate lists). +// Regardless of platform, all paths are stored with forward slashes (UNIX-style). func WalkEntryDir() ([]string, []string) { // define file/directory containing slices so that they may be accessed by the anonymous WalkDir function var fileList []string @@ -50,7 +50,7 @@ func WalkEntryDir() ([]string, []string) { return fileList, dirList } -// joinErrorWithEXE joins and returns the two strings it is provided (in error format) with the executable name inserted between them +// joinErrorWithEXE is a utility function that joins and returns the two strings it is provided (in error format) with the executable name inserted between them. func joinErrorWithEXE(firstHalf, secondHalf string) string { return core.AnsiError + firstHalf + os.Args[0][strings.LastIndex(os.Args[0], "\\")+1:] + secondHalf + core.AnsiReset } diff --git a/sync/init.go b/sync/init.go index 8959176..098b742 100644 --- a/sync/init.go +++ b/sync/init.go @@ -11,10 +11,10 @@ import ( "github.com/rwinkhart/libmutton/core" ) -// DeviceIDGen generates a new client device ID and registers it with the server -// device IDs are only needed for online synchronization -// device IDs are guaranteed unique as the current UNIX time is appended to them -// returns the remote EntryRoot and OS type (OS type is a bool: core.IsWindows) +// DeviceIDGen generates a new client device ID and registers it with the server. +// Device IDs are only needed for online synchronization. +// Device IDs are guaranteed unique as the current UNIX time is appended to them. +// Returns: the remote EntryRoot and OS type indicator. func DeviceIDGen() (string, string) { deviceIDPrefix, _ := os.Hostname() deviceIDSuffix := core.StringGen(rand.Intn(32)+48, true, 0.2, true) + "-" + strconv.FormatInt(time.Now().Unix(), 10) diff --git a/sync/input.go b/sync/input.go index d848d3a..0bf16f3 100644 --- a/sync/input.go +++ b/sync/input.go @@ -2,15 +2,16 @@ package sync import ( "fmt" - "golang.org/x/crypto/ssh/terminal" "os" + + "golang.org/x/term" ) -// inputKeyFilePassphrase prompts the user for a passphrase for an SSH key file +// inputKeyFilePassphrase prompts the user for a passphrase for an SSH key file. // TODO support non-CLI implementations func inputKeyFilePassphrase() []byte { fmt.Print("\nEnter passphrase for your SSH keyfile: ") - passphrase, _ := terminal.ReadPassword(int(os.Stdin.Fd())) + passphrase, _ := term.ReadPassword(int(os.Stdin.Fd())) fmt.Println() return passphrase } diff --git a/sync/server.go b/sync/server.go index 2861b9e..443be10 100644 --- a/sync/server.go +++ b/sync/server.go @@ -9,9 +9,9 @@ import ( "github.com/rwinkhart/libmutton/core" ) -// GetRemoteDataFromServer prints to stdout the remote entries, mod times, folders, and deletions -// lists in output are separated by FSSpace -// output is meant to be captured over SSH for interpretation by the client +// GetRemoteDataFromServer prints to stdout the remote entries, mod times, folders, and deletions. +// Lists in output are separated by FSSpace. +// Output is meant to be captured over SSH for interpretation by the client. func GetRemoteDataFromServer(clientDeviceID string) { entryList, dirList := WalkEntryDir() modList := getModTimes(entryList)