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

cmd/geth/accountcmd.go

@@ -32,29 +32,36 @@ import (
 var (
 	walletCommand = cli.Command{
 		Name:      "wallet",
-		Usage: "ethereum presale wallet",
+		Usage:     "Manage Ethereum presale wallets",
-		Subcommands: []cli.Command{
+		ArgsUsage: "",
-			{
+		Category:  "ACCOUNT COMMANDS",
-				Action: importWallet,
-				Name:   "import",
-				Usage:  "import ethereum presale wallet",
-			},
-		},
 		Description: `
-
+    geth wallet import /path/to/my/presale.wallet
-    get 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",
+		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.
 
@@ -88,15 +95,19 @@ And finally. DO NOT FORGET YOUR PASSWORD.
 			{
 				Action:    accountList,
 				Name:      "list",
-				Usage:  "print account addresses",
+				Usage:     "Print account addresses",
+				ArgsUsage: " ",
+				Description: `
+TODO: Please write this
+`,
 			},
 			{
 				Action:    accountCreate,
 				Name:      "new",
-				Usage:  "create a new account",
+				Usage:     "Create a new account",
+				ArgsUsage: " ",
 				Description: `
-
+    geth account new
-    ethereum account new
 
 Creates a new account. Prints the address.
 
@@ -106,7 +117,7 @@ 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.
@@ -115,10 +126,10 @@ password to file or expose in any other way.
 			{
 				Action:    accountUpdate,
 				Name:      "update",
-				Usage:  "update an existing account",
+				Usage:     "Update an existing account",
+				ArgsUsage: "<address>",
 				Description: `
-
+    geth account update <address>
-    ethereum account update <address>
 
 Update an existing account.
 
@@ -130,7 +141,7 @@ 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.
@@ -139,10 +150,10 @@ changing your password is only possible interactively.
 			{
 				Action:    accountImport,
 				Name:      "import",
-				Usage:  "import a private key into a new account",
+				Usage:     "Import a private key into a new account",
+				ArgsUsage: "<keyFile>",
 				Description: `
-
+    geth account import <keyfile>
-    ethereum account import <keyfile>
 
 Imports an unencrypted private key from <keyfile> and creates a new account.
 Prints the address.
@@ -155,7 +166,7 @@ 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,

cmd/geth/chaincmd.go

@@ -42,12 +42,19 @@ var (
 	importCommand = cli.Command{
 		Action:    importChain,
 		Name:      "import",
-		Usage:  `import a blockchain file`,
+		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`,
+		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
@@ -58,17 +65,29 @@ if already existing.
 	upgradedbCommand = cli.Command{
 		Action:    upgradeDB,
 		Name:      "upgradedb",
-		Usage:  "upgrade chainblock database",
+		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",
+		ArgsUsage: " ",
+		Category:  "BLOCKCHAIN COMMANDS",
+		Description: `
+TODO: Please write this
+`,
 	}
 	dumpCommand = cli.Command{
 		Action:    dump,
 		Name:      "dump",
-		Usage:  `dump a specific block from storage`,
+		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

@@ -32,7 +32,9 @@ var (
 	consoleCommand = cli.Command{
 		Action:    localConsole,
 		Name:      "console",
-		Usage:  `Geth Console: interactive JavaScript environment`,
+		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.
@@ -42,7 +44,9 @@ 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)`,
+		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.
@@ -53,7 +57,9 @@ 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`,
+		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,
@@ -76,7 +77,9 @@ func init() {
 		{
 			Action:    makedag,
 			Name:      "makedag",
-			Usage:  "generate ethash dag (for testing)",
+			Usage:     "Generate ethash DAG (for testing)",
+			ArgsUsage: "<blockNum> <outputDir>",
+			Category:  "MISCELLANEOUS COMMANDS",
 			Description: `
 The makedag command generates an ethash DAG in /tmp/dag.
 
@@ -87,7 +90,9 @@ Regular users do not need to execute it.
 		{
 			Action:    version,
 			Name:      "version",
-			Usage:  "print ethereum version numbers",
+			Usage:     "Print version numbers",
+			ArgsUsage: " ",
+			Category:  "MISCELLANEOUS COMMANDS",
 			Description: `
 The output of this command is supposed to be machine-readable.
 `,
@@ -95,9 +100,11 @@ The output of this command is supposed to be machine-readable.
 		{
 			Action:    initGenesis,
 			Name:      "init",
-			Usage:  "bootstraps and initialises a new genesis block (JSON)",
+			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.
 `,
@@ -105,7 +112,9 @@ participating.
 		{
 			Action:    license,
 			Name:      "license",
-			Usage:  "displays geth's license information",
+			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

@@ -51,7 +51,9 @@ var (
 	monitorCommand = cli.Command{
 		Action:    monitor,
 		Name:      "monitor",
-		Usage:  `Geth Monitor: node metrics monitoring and visualization`,
+		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