From aee96536cbf503cac27e275bcc31afb632e1fa12 Mon Sep 17 00:00:00 2001 From: Virgil Date: Sat, 4 Apr 2026 05:13:27 +0000 Subject: [PATCH] refactor(ax): modernize command docs --- cmd/mining/cmd/doctor.go | 4 ++-- cmd/mining/cmd/list.go | 2 +- cmd/mining/cmd/peer.go | 13 ++++++------- cmd/mining/cmd/remote.go | 28 ++++++++++++++-------------- cmd/mining/cmd/serve.go | 2 +- cmd/mining/cmd/simulate.go | 2 +- cmd/mining/cmd/start.go | 2 +- cmd/mining/cmd/status.go | 2 +- cmd/mining/cmd/stop.go | 2 +- cmd/mining/cmd/uninstall.go | 2 +- cmd/mining/cmd/update.go | 2 +- 11 files changed, 30 insertions(+), 31 deletions(-) diff --git a/cmd/mining/cmd/doctor.go b/cmd/mining/cmd/doctor.go index 5369886..a3fbc44 100644 --- a/cmd/mining/cmd/doctor.go +++ b/cmd/mining/cmd/doctor.go @@ -16,7 +16,7 @@ import ( const signpostFilename = ".installed-miners" // validateConfigPath("/home/alice/.config/lethean-desktop/miners/config.json") // nil -// validateConfigPath("/tmp/config.json") // error +// validateConfigPath("/tmp/config.json") // error because the path is outside XDG_CONFIG_HOME func validateConfigPath(configPath string) error { expectedBase := filepath.Join(xdg.ConfigHome, "lethean-desktop") @@ -29,7 +29,7 @@ func validateConfigPath(configPath string) error { return nil } -// doctorCmd.Use == "doctor" and RunE refreshes the local installation cache. +// doctor refreshes the miner installation cache and refreshes the cached summary on disk. var doctorCmd = &cobra.Command{ Use: "doctor", Short: "Check and refresh the status of installed miners", diff --git a/cmd/mining/cmd/list.go b/cmd/mining/cmd/list.go index 7a8b850..b5b89a2 100644 --- a/cmd/mining/cmd/list.go +++ b/cmd/mining/cmd/list.go @@ -6,7 +6,7 @@ import ( "github.com/spf13/cobra" ) -// listCmd.Use == "list" and RunE prints running and available miners. +// mining list prints the running miners and the installable miners. var listCmd = &cobra.Command{ Use: "list", Short: "List running and available miners", diff --git a/cmd/mining/cmd/peer.go b/cmd/mining/cmd/peer.go index e3c87eb..5b4c2ea 100644 --- a/cmd/mining/cmd/peer.go +++ b/cmd/mining/cmd/peer.go @@ -8,15 +8,14 @@ import ( "github.com/spf13/cobra" ) -// findPeerByPartialID("a1b2c3") // defined in remote.go and used by peer subcommands -// peerCmd.Use == "peer" and RunE groups peer-management subcommands. +// peer add, peer list, peer remove, peer ping, and peer optimal live under this command group. var peerCmd = &cobra.Command{ Use: "peer", Short: "Manage peer nodes", Long: `Add, remove, and manage connections to peer nodes.`, } -// peerAddCmd.Use == "add" and RunE registers a new peer by address. +// peer add --address 10.0.0.2:9090 --name worker-1 registers a peer by address. var peerAddCmd = &cobra.Command{ Use: "add", Short: "Add a peer node", @@ -65,7 +64,7 @@ to exchange public keys and establish a secure connection.`, }, } -// peerListCmd.Use == "list" and RunE prints registered peers. +// peer list prints the currently registered peers and their connection status. var peerListCmd = &cobra.Command{ Use: "list", Short: "List registered peers", @@ -106,7 +105,7 @@ var peerListCmd = &cobra.Command{ }, } -// peerRemoveCmd.Use == "remove " and RunE removes the selected peer. +// peer remove a1b2c3d4e5f6 removes the selected peer from the registry. var peerRemoveCmd = &cobra.Command{ Use: "remove ", Short: "Remove a peer from registry", @@ -134,7 +133,7 @@ var peerRemoveCmd = &cobra.Command{ }, } -// peerPingCmd.Use == "ping " and RunE prints a ping placeholder. +// peer ping a1b2c3d4e5f6 measures the selected peer's reachability. var peerPingCmd = &cobra.Command{ Use: "ping ", Short: "Ping a peer and update metrics", @@ -159,7 +158,7 @@ var peerPingCmd = &cobra.Command{ }, } -// peerOptimalCmd.Use == "optimal" and RunE prints the best peer by score. +// peer optimal --count 4 prints the four best peers by score. var peerOptimalCmd = &cobra.Command{ Use: "optimal", Short: "Show the optimal peer based on metrics", diff --git a/cmd/mining/cmd/remote.go b/cmd/mining/cmd/remote.go index acec93d..a0eeeef 100644 --- a/cmd/mining/cmd/remote.go +++ b/cmd/mining/cmd/remote.go @@ -17,14 +17,14 @@ var ( controllerErr error ) -// remoteCmd.Use == "remote" and RunE groups remote node commands. +// remote status, remote start, remote stop, remote logs, remote connect, remote disconnect, and remote ping live under this command group. var remoteCmd = &cobra.Command{ Use: "remote", Short: "Control remote mining nodes", Long: `Send commands to remote worker nodes and retrieve their status.`, } -// remoteStatusCmd.Use == "status [peer-id]" and RunE prints remote stats. +// remote status a1b2c3d4e5f6 prints stats for one peer, while remote status prints the whole fleet. var remoteStatusCmd = &cobra.Command{ Use: "status [peer-id]", Short: "Get mining status from remote peers", @@ -78,7 +78,7 @@ var remoteStatusCmd = &cobra.Command{ }, } -// remoteStartCmd.Use == "start " and RunE starts a miner on a peer. +// remote start a1b2c3d4e5f6 --type xmrig --profile default starts a miner on the selected peer. var remoteStartCmd = &cobra.Command{ Use: "start ", Short: "Start miner on remote peer", @@ -112,7 +112,7 @@ var remoteStartCmd = &cobra.Command{ }, } -// remoteStopCmd.Use == "stop [miner-name]" and RunE stops a remote miner. +// remote stop a1b2c3d4e5f6 xmrig-1 stops a named miner on the selected peer. var remoteStopCmd = &cobra.Command{ Use: "stop [miner-name]", Short: "Stop miner on remote peer", @@ -151,7 +151,7 @@ var remoteStopCmd = &cobra.Command{ }, } -// remoteLogsCmd.Use == "logs " and RunE prints remote logs. +// remote logs a1b2c3d4e5f6 xmrig-1 prints the first 100 log lines for the remote miner. var remoteLogsCmd = &cobra.Command{ Use: "logs ", Short: "Get console logs from remote miner", @@ -187,7 +187,7 @@ var remoteLogsCmd = &cobra.Command{ }, } -// remoteConnectCmd.Use == "connect " and RunE opens a peer connection. +// remote connect a1b2c3d4e5f6 opens a WebSocket connection to the peer. var remoteConnectCmd = &cobra.Command{ Use: "connect ", Short: "Connect to a remote peer", @@ -215,7 +215,7 @@ var remoteConnectCmd = &cobra.Command{ }, } -// remoteDisconnectCmd.Use == "disconnect " and RunE closes a peer connection. +// remote disconnect a1b2c3d4e5f6 closes the active peer connection. var remoteDisconnectCmd = &cobra.Command{ Use: "disconnect ", Short: "Disconnect from a remote peer", @@ -243,7 +243,7 @@ var remoteDisconnectCmd = &cobra.Command{ }, } -// remotePingCmd.Use == "ping " and RunE averages multiple ping samples. +// remote ping a1b2c3d4e5f6 --count 4 averages four ping samples. var remotePingCmd = &cobra.Command{ Use: "ping ", Short: "Ping a remote peer", @@ -265,8 +265,8 @@ var remotePingCmd = &cobra.Command{ fmt.Printf("Pinging %s (%s)...\n", peer.Name, peer.Address) - var totalRTT float64 - var successful int + var totalRoundTripMillis float64 + var successfulPings int for i := 0; i < count; i++ { rtt, err := controller.PingPeer(peer.ID) @@ -275,16 +275,16 @@ var remotePingCmd = &cobra.Command{ continue } fmt.Printf(" Ping %d: %.2f ms\n", i+1, rtt) - totalRTT += rtt - successful++ + totalRoundTripMillis += rtt + successfulPings++ if i < count-1 { time.Sleep(time.Second) } } - if successful > 0 { - fmt.Printf("\nAverage: %.2f ms (%d/%d successful)\n", totalRTT/float64(successful), successful, count) + if successfulPings > 0 { + fmt.Printf("\nAverage: %.2f ms (%d/%d successful)\n", totalRoundTripMillis/float64(successfulPings), successfulPings, count) } else { fmt.Println("\nAll pings failed.") } diff --git a/cmd/mining/cmd/serve.go b/cmd/mining/cmd/serve.go index 6441ced..e9f86fc 100644 --- a/cmd/mining/cmd/serve.go +++ b/cmd/mining/cmd/serve.go @@ -22,7 +22,7 @@ var ( namespace string ) -// serveCmd.Use == "serve" and RunE starts the HTTP API and shell. +// mining serve starts the HTTP API and interactive shell. var serveCmd = &cobra.Command{ Use: "serve", Short: "Start the mining service and interactive shell", diff --git a/cmd/mining/cmd/simulate.go b/cmd/mining/cmd/simulate.go index 6b98d50..fd59101 100644 --- a/cmd/mining/cmd/simulate.go +++ b/cmd/mining/cmd/simulate.go @@ -21,7 +21,7 @@ var ( simAlgorithm string ) -// simulateCmd.Use == "simulate" and RunE starts the service with fake miners. +// mining simulate --count 3 --preset cpu-medium starts the API with fake miners. var simulateCmd = &cobra.Command{ Use: "simulate", Short: "Start the service with simulated miners for UI testing", diff --git a/cmd/mining/cmd/start.go b/cmd/mining/cmd/start.go index df00d90..912dee8 100644 --- a/cmd/mining/cmd/start.go +++ b/cmd/mining/cmd/start.go @@ -13,7 +13,7 @@ var ( minerWallet string ) -// startCmd.Use == "start [miner_name]" and RunE starts the requested miner. +// mining start xmrig --pool pool.example.com:3333 --wallet 44... starts the selected miner. var startCmd = &cobra.Command{ Use: "start [miner_name]", Short: "Start a new miner", diff --git a/cmd/mining/cmd/status.go b/cmd/mining/cmd/status.go index 5b445c5..6d24757 100644 --- a/cmd/mining/cmd/status.go +++ b/cmd/mining/cmd/status.go @@ -9,7 +9,7 @@ import ( "golang.org/x/text/language" ) -// statusCmd.Use == "status [miner_name]" and RunE prints live miner stats. +// mining status xmrig-rx_0 prints live stats for a running miner. var statusCmd = &cobra.Command{ Use: "status [miner_name]", Short: "Get status of a running miner", diff --git a/cmd/mining/cmd/stop.go b/cmd/mining/cmd/stop.go index 4dd34b0..93e5066 100644 --- a/cmd/mining/cmd/stop.go +++ b/cmd/mining/cmd/stop.go @@ -7,7 +7,7 @@ import ( "github.com/spf13/cobra" ) -// stopCmd.Use == "stop [miner_name]" and RunE stops the named miner. +// mining stop xmrig-rx_0 stops the named miner. var stopCmd = &cobra.Command{ Use: "stop [miner_name]", Short: "Stop a running miner", diff --git a/cmd/mining/cmd/uninstall.go b/cmd/mining/cmd/uninstall.go index 1748347..26e577d 100644 --- a/cmd/mining/cmd/uninstall.go +++ b/cmd/mining/cmd/uninstall.go @@ -7,7 +7,7 @@ import ( "github.com/spf13/cobra" ) -// uninstallCmd.Use == "uninstall [miner_type]" and RunE removes the miner. +// mining uninstall xmrig removes the miner and refreshes the cache. var uninstallCmd = &cobra.Command{ Use: "uninstall [miner_type]", Short: "Uninstall a miner", diff --git a/cmd/mining/cmd/update.go b/cmd/mining/cmd/update.go index 2d830ae..0d61ea3 100644 --- a/cmd/mining/cmd/update.go +++ b/cmd/mining/cmd/update.go @@ -23,7 +23,7 @@ func validateUpdateConfigPath(configPath string) error { return nil } -// updateCmd.Use == "update" and RunE checks cached miner versions for upgrades. +// mining update checks cached miner versions and reports available upgrades. var updateCmd = &cobra.Command{ Use: "update", Short: "Check for updates to installed miners",