cmd/geth: improve command help messages (#3227)

cmd/geth/accountcmd.go

@@ -31,30 +31,37 @@ import (
 
 var (
 	walletCommand = cli.Command{
-		Name:  "wallet",
-		Usage: "ethereum presale wallet",
-		Subcommands: []cli.Command{
-			{
-				Action: importWallet,
-				Name:   "import",
-				Usage:  "import ethereum presale wallet",
-			},
-		},
+		Name:      "wallet",
+		Usage:     "Manage Ethereum presale wallets",
+		ArgsUsage: "",
+		Category:  "ACCOUNT COMMANDS",
 		Description: `
-
-    get wallet import /path/to/my/presale.wallet
+    geth wallet import /path/to/my/presale.wallet
 
 will prompt for your password and imports your ether presale account.
 It can be used non-interactively with the --password option taking a
 passwordfile as argument containing the wallet password in plaintext.
 
-`}
+`,
+		Subcommands: []cli.Command{
+			{
+				Action:    importWallet,
+				Name:      "import",
+				Usage:     "Import Ethereum presale wallet",
+				ArgsUsage: "<keyFile>",
+				Description: `
+TODO: Please write this
+`,
+			},
+		},
+	}
 	accountCommand = cli.Command{
-		Action: accountList,
-		Name:   "account",
-		Usage:  "manage accounts",
+		Action:    accountList,
+		Name:      "account",
+		Usage:     "Manage accounts",
+		ArgsUsage: "",
+		Category:  "ACCOUNT COMMANDS",
 		Description: `
-
 Manage accounts lets you create new accounts, list all existing accounts,
 import a private key into a new account.
 
@@ -86,17 +93,21 @@ And finally. DO NOT FORGET YOUR PASSWORD.
 `,
 		Subcommands: []cli.Command{
 			{
-				Action: accountList,
-				Name:   "list",
-				Usage:  "print account addresses",
+				Action:    accountList,
+				Name:      "list",
+				Usage:     "Print account addresses",
+				ArgsUsage: " ",
+				Description: `
+TODO: Please write this
+`,
 			},
 			{
-				Action: accountCreate,
-				Name:   "new",
-				Usage:  "create a new account",
+				Action:    accountCreate,
+				Name:      "new",
+				Usage:     "Create a new account",
+				ArgsUsage: " ",
 				Description: `
-
-    ethereum account new
+    geth account new
 
 Creates a new account. Prints the address.
 
@@ -106,19 +117,19 @@ You must remember this passphrase to unlock your account in the future.
 
 For non-interactive use the passphrase can be specified with the --password flag:
 
-    ethereum --password <passwordfile> account new
+    geth --password <passwordfile> account new
 
 Note, this is meant to be used for testing only, it is a bad idea to save your
 password to file or expose in any other way.
-					`,
+`,
 			},
 			{
-				Action: accountUpdate,
-				Name:   "update",
-				Usage:  "update an existing account",
+				Action:    accountUpdate,
+				Name:      "update",
+				Usage:     "Update an existing account",
+				ArgsUsage: "<address>",
 				Description: `
-
-    ethereum account update <address>
+    geth account update <address>
 
 Update an existing account.
 
@@ -130,19 +141,19 @@ format to the newest format or change the password for an account.
 
 For non-interactive use the passphrase can be specified with the --password flag:
 
-    ethereum --password <passwordfile> account update <address>
+    geth --password <passwordfile> account update <address>
 
 Since only one password can be given, only format update can be performed,
 changing your password is only possible interactively.
-					`,
+`,
 			},
 			{
-				Action: accountImport,
-				Name:   "import",
-				Usage:  "import a private key into a new account",
+				Action:    accountImport,
+				Name:      "import",
+				Usage:     "Import a private key into a new account",
+				ArgsUsage: "<keyFile>",
 				Description: `
-
-    ethereum account import <keyfile>
+    geth account import <keyfile>
 
 Imports an unencrypted private key from <keyfile> and creates a new account.
 Prints the address.
@@ -155,13 +166,13 @@ You must remember this passphrase to unlock your account in the future.
 
 For non-interactive use the passphrase can be specified with the -password flag:
 
-    ethereum --password <passwordfile> account import <keyfile>
+    geth --password <passwordfile> account import <keyfile>
 
 Note:
 As you can directly copy your encrypted accounts to another ethereum instance,
 this import mechanism is not needed when you transfer an account between
 nodes.
-					`,
+`,
 			},
 		},
 	}

cmd/geth/chaincmd.go

@@ -40,35 +40,54 @@ import (
 
 var (
 	importCommand = cli.Command{
-		Action: importChain,
-		Name:   "import",
-		Usage:  `import a blockchain file`,
+		Action:    importChain,
+		Name:      "import",
+		Usage:     "Import a blockchain file",
+		ArgsUsage: "<filename>",
+		Category:  "BLOCKCHAIN COMMANDS",
+		Description: `
+TODO: Please write this
+`,
 	}
 	exportCommand = cli.Command{
-		Action: exportChain,
-		Name:   "export",
-		Usage:  `export blockchain into file`,
+		Action:    exportChain,
+		Name:      "export",
+		Usage:     "Export blockchain into file",
+		ArgsUsage: "<filename> [<blockNumFirst> <blockNumLast>]",
+		Category:  "BLOCKCHAIN COMMANDS",
 		Description: `
 Requires a first argument of the file to write to.
 Optional second and third arguments control the first and
 last block to write. In this mode, the file will be appended
 if already existing.
-		`,
+`,
 	}
 	upgradedbCommand = cli.Command{
-		Action: upgradeDB,
-		Name:   "upgradedb",
-		Usage:  "upgrade chainblock database",
+		Action:    upgradeDB,
+		Name:      "upgradedb",
+		Usage:     "Upgrade chainblock database",
+		ArgsUsage: " ",
+		Category:  "BLOCKCHAIN COMMANDS",
+		Description: `
+TODO: Please write this
+`,
 	}
 	removedbCommand = cli.Command{
-		Action: removeDB,
-		Name:   "removedb",
-		Usage:  "Remove blockchain and state databases",
+		Action:    removeDB,
+		Name:      "removedb",
+		Usage:     "Remove blockchain and state databases",
+		ArgsUsage: " ",
+		Category:  "BLOCKCHAIN COMMANDS",
+		Description: `
+TODO: Please write this
+`,
 	}
 	dumpCommand = cli.Command{
-		Action: dump,
-		Name:   "dump",
-		Usage:  `dump a specific block from storage`,
+		Action:    dump,
+		Name:      "dump",
+		Usage:     "Dump a specific block from storage",
+		ArgsUsage: "[<blockHash> | <blockNum>]...",
+		Category:  "BLOCKCHAIN COMMANDS",
 		Description: `
 The arguments are interpreted as block numbers or hashes.
 Use "ethereum dump 0" to dump the genesis block.

cmd/geth/consolecmd.go

@@ -30,9 +30,11 @@ import (
 
 var (
 	consoleCommand = cli.Command{
-		Action: localConsole,
-		Name:   "console",
-		Usage:  `Geth Console: interactive JavaScript environment`,
+		Action:    localConsole,
+		Name:      "console",
+		Usage:     "Start an interactive JavaScript environment",
+		ArgsUsage: "", // TODO: Write this!
+		Category:  "CONSOLE COMMANDS",
 		Description: `
 The Geth console is an interactive shell for the JavaScript runtime environment
 which exposes a node admin interface as well as the Ðapp JavaScript API.
@@ -40,20 +42,24 @@ See https://github.com/ethereum/go-ethereum/wiki/Javascipt-Console
 `,
 	}
 	attachCommand = cli.Command{
-		Action: remoteConsole,
-		Name:   "attach",
-		Usage:  `Geth Console: interactive JavaScript environment (connect to node)`,
+		Action:    remoteConsole,
+		Name:      "attach",
+		Usage:     "Start an interactive JavaScript environment (connect to node)",
+		ArgsUsage: "", // TODO: Write this!
+		Category:  "CONSOLE COMMANDS",
 		Description: `
 The Geth console is an interactive shell for the JavaScript runtime environment
 which exposes a node admin interface as well as the Ðapp JavaScript API.
 See https://github.com/ethereum/go-ethereum/wiki/Javascipt-Console.
 This command allows to open a console on a running geth node.
-	`,
+`,
 	}
 	javascriptCommand = cli.Command{
-		Action: ephemeralConsole,
-		Name:   "js",
-		Usage:  `executes the given JavaScript files in the Geth JavaScript VM`,
+		Action:    ephemeralConsole,
+		Name:      "js",
+		Usage:     "Execute the specified JavaScript files",
+		ArgsUsage: "", // TODO: Write this!
+		Category:  "CONSOLE COMMANDS",
 		Description: `
 The JavaScript VM exposes a node admin interface as well as the Ðapp
 JavaScript API. See https://github.com/ethereum/go-ethereum/wiki/Javascipt-Console

cmd/geth/main.go

@@ -61,6 +61,7 @@ func init() {
 	// Initialize the CLI app and start Geth
 	app.Action = geth
 	app.HideVersion = true // we have a command to print the version
+	app.Copyright = "Copyright 2013-2016 The go-ethereum Authors"
 	app.Commands = []cli.Command{
 		importCommand,
 		exportCommand,
@@ -74,9 +75,11 @@ func init() {
 		attachCommand,
 		javascriptCommand,
 		{
-			Action: makedag,
-			Name:   "makedag",
-			Usage:  "generate ethash dag (for testing)",
+			Action:    makedag,
+			Name:      "makedag",
+			Usage:     "Generate ethash DAG (for testing)",
+			ArgsUsage: "<blockNum> <outputDir>",
+			Category:  "MISCELLANEOUS COMMANDS",
 			Description: `
 The makedag command generates an ethash DAG in /tmp/dag.
 
@@ -85,27 +88,33 @@ Regular users do not need to execute it.
 `,
 		},
 		{
-			Action: version,
-			Name:   "version",
-			Usage:  "print ethereum version numbers",
+			Action:    version,
+			Name:      "version",
+			Usage:     "Print version numbers",
+			ArgsUsage: " ",
+			Category:  "MISCELLANEOUS COMMANDS",
 			Description: `
 The output of this command is supposed to be machine-readable.
 `,
 		},
 		{
-			Action: initGenesis,
-			Name:   "init",
-			Usage:  "bootstraps and initialises a new genesis block (JSON)",
+			Action:    initGenesis,
+			Name:      "init",
+			Usage:     "Bootstrap and initialize a new genesis block",
+			ArgsUsage: "<genesisPath>",
+			Category:  "BLOCKCHAIN COMMANDS",
 			Description: `
-The init command initialises a new genesis block and definition for the network.
+The init command initializes a new genesis block and definition for the network.
 This is a destructive action and changes the network in which you will be
 participating.
 `,
 		},
 		{
-			Action: license,
-			Name:   "license",
-			Usage:  "displays geth's license information",
+			Action:    license,
+			Name:      "license",
+			Usage:     "Display license information",
+			ArgsUsage: " ",
+			Category:  "MISCELLANEOUS COMMANDS",
 		},
 	}
 
@@ -335,23 +344,22 @@ func makedag(ctx *cli.Context) error {
 	return nil
 }
 
-func version(c *cli.Context) error {
+func version(ctx *cli.Context) error {
 	fmt.Println(strings.Title(clientIdentifier))
 	fmt.Println("Version:", utils.Version)
 	if gitCommit != "" {
 		fmt.Println("Git Commit:", gitCommit)
 	}
 	fmt.Println("Protocol Versions:", eth.ProtocolVersions)
-	fmt.Println("Network Id:", c.GlobalInt(utils.NetworkIdFlag.Name))
+	fmt.Println("Network Id:", ctx.GlobalInt(utils.NetworkIdFlag.Name))
 	fmt.Println("Go Version:", runtime.Version())
 	fmt.Println("OS:", runtime.GOOS)
 	fmt.Printf("GOPATH=%s\n", os.Getenv("GOPATH"))
 	fmt.Printf("GOROOT=%s\n", runtime.GOROOT())
-
 	return nil
 }
 
-func license(c *cli.Context) error {
+func license(_ *cli.Context) error {
 	fmt.Println(`Geth is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation, either version 3 of the License, or
@@ -365,6 +373,5 @@ GNU General Public License for more details.
 You should have received a copy of the GNU General Public License
 along with geth. If not, see <http://www.gnu.org/licenses/>.
 `)
-
 	return nil
 }

cmd/geth/monitorcmd.go

@@ -49,9 +49,11 @@ var (
 		Usage: "Refresh interval in seconds",
 	}
 	monitorCommand = cli.Command{
-		Action: monitor,
-		Name:   "monitor",
-		Usage:  `Geth Monitor: node metrics monitoring and visualization`,
+		Action:    monitor,
+		Name:      "monitor",
+		Usage:     "Monitor and visualize node metrics",
+		ArgsUsage: " ",
+		Category:  "MONITOR COMMANDS",
 		Description: `
 The Geth monitor is a tool to collect and visualize various internal metrics
 gathered by the node, supporting different chart types as well as the capacity