Merge pull request #1949 from karalabe/update-command-usage

cmd/geth, cmd/utils, eth: group CLI flags by purpose

3 files changed, 265 insertions, 71 deletions

diff --git a/cmd/geth/main.go b/cmd/geth/main.go
index 8bdc01999..f752029b7 100644
--- a/cmd/geth/main.go
+++ b/cmd/geth/main.go
@@ -74,7 +74,7 @@ func init() {
 		{
 			Action: blockRecovery,
 			Name:   "recover",
-			Usage:  "attempts to recover a corrupted database by setting a new block by number or hash. See help recover.",
+			Usage:  "Attempts to recover a corrupted database by setting a new block by number or hash",
 			Description: `
 The recover commands will attempt to read out the last
 block based on that.
@@ -339,10 +339,8 @@ JavaScript API. See https://github.com/ethereum/go-ethereum/wiki/Javascipt-Conso
 		utils.RPCCORSDomainFlag,
 		utils.VerbosityFlag,
 		utils.BacktraceAtFlag,
-		utils.LogToStdErrFlag,
 		utils.LogVModuleFlag,
 		utils.LogFileFlag,
-		utils.LogJSONFlag,
 		utils.PProfEanbledFlag,
 		utils.PProfPortFlag,
 		utils.MetricsEnabledFlag,
@@ -402,7 +400,6 @@ func makeDefaultExtra() []byte {
 		glog.V(logger.Debug).Infof("extra: %x\n", extra)
 		return nil
 	}
-
 	return extra
 }
 
diff --git a/cmd/geth/usage.go b/cmd/geth/usage.go
new file mode 100644
index 000000000..9223b7cd6
--- /dev/null
+++ b/cmd/geth/usage.go
@@ -0,0 +1,212 @@
+// Copyright 2015 The go-ethereum Authors
+// This file is part of go-ethereum.
+//
+// go-ethereum 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
+// (at your option) any later version.
+//
+// go-ethereum is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with go-ethereum. If not, see <http://www.gnu.org/licenses/>.
+
+// Contains the geth command usage template and generator.
+
+package main
+
+import (
+	"io"
+
+	"github.com/codegangsta/cli"
+	"github.com/ethereum/go-ethereum/cmd/utils"
+)
+
+// AppHelpTemplate is the test template for the default, global app help topic.
+var AppHelpTemplate = `NAME:
+   {{.App.Name}} - {{.App.Usage}}
+
+USAGE:
+   {{.App.HelpName}} [options]{{if .App.Commands}} command [command options]{{end}} {{if .App.ArgsUsage}}{{.App.ArgsUsage}}{{else}}[arguments...]{{end}}
+   {{if .App.Version}}
+VERSION:
+   {{.App.Version}}
+   {{end}}{{if len .App.Authors}}
+AUTHOR(S):
+   {{range .App.Authors}}{{ . }}{{end}}
+   {{end}}{{if .App.Commands}}
+COMMANDS:
+   {{range .App.Commands}}{{join .Names ", "}}{{ "\t" }}{{.Usage}}
+   {{end}}{{end}}{{if .FlagGroups}}
+{{range .FlagGroups}}{{.Name}} OPTIONS:
+  {{range .Flags}}{{.}}
+  {{end}}
+{{end}}{{end}}{{if .App.Copyright }}
+COPYRIGHT:
+   {{.App.Copyright}}
+   {{end}}
+`
+
+// flagGroup is a collection of flags belonging to a single topic.
+type flagGroup struct {
+	Name  string
+	Flags []cli.Flag
+}
+
+// AppHelpFlagGroups is the application flags, grouped by functionality.
+var AppHelpFlagGroups = []flagGroup{
+	{
+		Name: "ETHEREUM",
+		Flags: []cli.Flag{
+			utils.DataDirFlag,
+			utils.NetworkIdFlag,
+			utils.OlympicFlag,
+			utils.TestNetFlag,
+			utils.DevModeFlag,
+			utils.GenesisFileFlag,
+			utils.IdentityFlag,
+			utils.FastSyncFlag,
+			utils.CacheFlag,
+			utils.BlockchainVersionFlag,
+		},
+	},
+	{
+		Name: "ACCOUNT",
+		Flags: []cli.Flag{
+			utils.UnlockedAccountFlag,
+			utils.PasswordFileFlag,
+		},
+	},
+	{
+		Name: "API AND CONSOLE",
+		Flags: []cli.Flag{
+			utils.RPCEnabledFlag,
+			utils.RPCListenAddrFlag,
+			utils.RPCPortFlag,
+			utils.RpcApiFlag,
+			utils.IPCDisabledFlag,
+			utils.IPCApiFlag,
+			utils.IPCPathFlag,
+			utils.RPCCORSDomainFlag,
+			utils.JSpathFlag,
+			utils.ExecFlag,
+		},
+	},
+	{
+		Name: "NETWORKING",
+		Flags: []cli.Flag{
+			utils.BootnodesFlag,
+			utils.ListenPortFlag,
+			utils.MaxPeersFlag,
+			utils.MaxPendingPeersFlag,
+			utils.NATFlag,
+			utils.NoDiscoverFlag,
+			utils.NodeKeyFileFlag,
+			utils.NodeKeyHexFlag,
+		},
+	},
+	{
+		Name: "MINER",
+		Flags: []cli.Flag{
+			utils.MiningEnabledFlag,
+			utils.MinerThreadsFlag,
+			utils.MiningGPUFlag,
+			utils.AutoDAGFlag,
+			utils.EtherbaseFlag,
+			utils.GasPriceFlag,
+			utils.ExtraDataFlag,
+		},
+	},
+	{
+		Name: "GAS PRICE ORACLE",
+		Flags: []cli.Flag{
+			utils.GpoMinGasPriceFlag,
+			utils.GpoMaxGasPriceFlag,
+			utils.GpoFullBlockRatioFlag,
+			utils.GpobaseStepDownFlag,
+			utils.GpobaseStepUpFlag,
+			utils.GpobaseCorrectionFactorFlag,
+		},
+	},
+	{
+		Name: "VIRTUAL MACHINE",
+		Flags: []cli.Flag{
+			utils.VMDebugFlag,
+			utils.VMEnableJitFlag,
+			utils.VMForceJitFlag,
+			utils.VMJitCacheFlag,
+		},
+	},
+	{
+		Name: "LOGGING AND DEBUGGING",
+		Flags: []cli.Flag{
+			utils.VerbosityFlag,
+			utils.LogVModuleFlag,
+			utils.BacktraceAtFlag,
+			utils.LogFileFlag,
+			utils.PProfEanbledFlag,
+			utils.PProfPortFlag,
+			utils.MetricsEnabledFlag,
+		},
+	},
+	{
+		Name: "EXPERIMENTAL",
+		Flags: []cli.Flag{
+			utils.WhisperEnabledFlag,
+			utils.NatspecEnabledFlag,
+		},
+	},
+	{
+		Name: "MISCELLANEOUS",
+		Flags: []cli.Flag{
+			utils.SolcPathFlag,
+		},
+	},
+}
+
+func init() {
+	// Override the default app help template
+	cli.AppHelpTemplate = AppHelpTemplate
+
+	// Define a one shot struct to pass to the usage template
+	type helpData struct {
+		App        interface{}
+		FlagGroups []flagGroup
+	}
+	// Override the default app help printer, but only for the global app help
+	originalHelpPrinter := cli.HelpPrinter
+	cli.HelpPrinter = func(w io.Writer, tmpl string, data interface{}) {
+		if tmpl == AppHelpTemplate {
+			// Iterate over all the flags and add any uncategorized ones
+			categorized := make(map[string]struct{})
+			for _, group := range AppHelpFlagGroups {
+				for _, flag := range group.Flags {
+					categorized[flag.String()] = struct{}{}
+				}
+			}
+			uncategorized := []cli.Flag{}
+			for _, flag := range data.(*cli.App).Flags {
+				if _, ok := categorized[flag.String()]; !ok {
+					uncategorized = append(uncategorized, flag)
+				}
+			}
+			if len(uncategorized) > 0 {
+				// Append all ungategorized options to the misc group
+				miscs := len(AppHelpFlagGroups[len(AppHelpFlagGroups)-1].Flags)
+				AppHelpFlagGroups[len(AppHelpFlagGroups)-1].Flags = append(AppHelpFlagGroups[len(AppHelpFlagGroups)-1].Flags, uncategorized...)
+
+				// Make sure they are removed afterwards
+				defer func() {
+					AppHelpFlagGroups[len(AppHelpFlagGroups)-1].Flags = AppHelpFlagGroups[len(AppHelpFlagGroups)-1].Flags[:miscs]
+				}()
+			}
+			// Render out custom usage screen
+			originalHelpPrinter(w, tmpl, helpData{data, AppHelpFlagGroups})
+		} else {
+			originalHelpPrinter(w, tmpl, data)
+		}
+	}
+}
diff --git a/cmd/utils/flags.go b/cmd/utils/flags.go
index 299ab4abb..d741d0544 100644
--- a/cmd/utils/flags.go
+++ b/cmd/utils/flags.go
@@ -101,35 +101,29 @@ var (
 	// General settings
 	DataDirFlag = DirectoryFlag{
 		Name:  "datadir",
-		Usage: "Data directory to be used",
+		Usage: "Data directory for the databases and keystore",
 		Value: DirectoryString{common.DefaultDataDir()},
 	}
 	NetworkIdFlag = cli.IntFlag{
 		Name:  "networkid",
-		Usage: "Network Id (integer)",
+		Usage: "Network identifier (integer, 0=Olympic, 1=Frontier, 2=Morden)",
 		Value: eth.NetworkId,
 	}
-	BlockchainVersionFlag = cli.IntFlag{
-		Name:  "blockchainversion",
-		Usage: "Blockchain version (integer)",
-		Value: core.BlockChainVersion,
-	}
-	GenesisNonceFlag = cli.IntFlag{
-		Name:  "genesisnonce",
-		Usage: "Sets the genesis nonce",
-		Value: 42,
+	OlympicFlag = cli.BoolFlag{
+		Name:  "olympic",
+		Usage: "Olympic network: pre-configured pre-release test network",
 	}
-	GenesisFileFlag = cli.StringFlag{
-		Name:  "genesis",
-		Usage: "Inserts/Overwrites the genesis block (json format)",
+	TestNetFlag = cli.BoolFlag{
+		Name:  "testnet",
+		Usage: "Morden network: pre-configured test network with modified starting nonces (replay protection)",
 	}
 	DevModeFlag = cli.BoolFlag{
 		Name:  "dev",
-		Usage: "Developer mode. This mode creates a private network and sets several debugging flags",
+		Usage: "Developer mode: pre-configured private network with several debugging flags",
 	}
-	TestNetFlag = cli.BoolFlag{
-		Name:  "testnet",
-		Usage: "Testnet mode. This enables your node to operate on the testnet",
+	GenesisFileFlag = cli.StringFlag{
+		Name:  "genesis",
+		Usage: "Insert/overwrite the genesis block (JSON format)",
 	}
 	IdentityFlag = cli.StringFlag{
 		Name:  "identity",
@@ -146,12 +140,13 @@ var (
 	}
 	CacheFlag = cli.IntFlag{
 		Name:  "cache",
-		Usage: "Megabytes of memory allocated to internal caching",
+		Usage: "Megabytes of memory allocated to internal caching (min 16MB / database forced)",
 		Value: 0,
 	}
-	OlympicFlag = cli.BoolFlag{
-		Name:  "olympic",
-		Usage: "Use olympic style protocol",
+	BlockchainVersionFlag = cli.IntFlag{
+		Name:  "blockchainversion",
+		Usage: "Blockchain version (integer)",
+		Value: core.BlockChainVersion,
 	}
 	FastSyncFlag = cli.BoolFlag{
 		Name:  "fast",
@@ -161,22 +156,20 @@ var (
 		Name:  "lightkdf",
 		Usage: "Reduce KDF memory & CPU usage at some expense of KDF strength",
 	}
-
-	// miner settings
+	// Miner settings
 	// TODO: refactor CPU vs GPU mining flags
-	MiningGPUFlag = cli.StringFlag{
-		Name:  "minegpu",
-		Usage: "Mine with given GPUs. '--minegpu 0,1' will mine with the first two GPUs found.",
+	MiningEnabledFlag = cli.BoolFlag{
+		Name:  "mine",
+		Usage: "Enable mining",
 	}
-
 	MinerThreadsFlag = cli.IntFlag{
 		Name:  "minerthreads",
-		Usage: "Number of miner threads",
+		Usage: "Number of CPU threads to use for mining",
 		Value: runtime.NumCPU(),
 	}
-	MiningEnabledFlag = cli.BoolFlag{
-		Name:  "mine",
-		Usage: "Enable mining",
+	MiningGPUFlag = cli.StringFlag{
+		Name:  "minergpus",
+		Usage: "List of GPUs to use for mining (e.g. '0,1' will use the first two GPUs found)",
 	}
 	AutoDAGFlag = cli.BoolFlag{
 		Name:  "autodag",
@@ -184,27 +177,27 @@ var (
 	}
 	EtherbaseFlag = cli.StringFlag{
 		Name:  "etherbase",
-		Usage: "Public address for block mining rewards. By default the address first created is used",
+		Usage: "Public address for block mining rewards (default = first account created)",
 		Value: "0",
 	}
 	GasPriceFlag = cli.StringFlag{
 		Name:  "gasprice",
-		Usage: "Sets the minimal gasprice when mining transactions",
+		Usage: "Minimal gas price to accept for mining a transactions",
 		Value: new(big.Int).Mul(big.NewInt(50), common.Shannon).String(),
 	}
 	ExtraDataFlag = cli.StringFlag{
 		Name:  "extradata",
-		Usage: "Extra data for the miner",
+		Usage: "Block extra data set by the miner (default = client version)",
 	}
-
+	// Account settings
 	UnlockedAccountFlag = cli.StringFlag{
 		Name:  "unlock",
-		Usage: "Unlock the account given until this program exits (prompts for password). '--unlock n' unlocks the n-th account in order or creation.",
+		Usage: "Unlock an account (may be creation index) until this program exits (prompts for password)",
 		Value: "",
 	}
 	PasswordFileFlag = cli.StringFlag{
 		Name:  "password",
-		Usage: "Path to password file to use with options and subcommands needing a password",
+		Usage: "Password file to use with options/subcommands needing a pass phrase",
 		Value: "",
 	}
 
@@ -228,32 +221,24 @@ var (
 	}
 
 	// logging and debug settings
-	LogFileFlag = cli.StringFlag{
-		Name:  "logfile",
-		Usage: "Send log output to a file",
-	}
 	VerbosityFlag = cli.IntFlag{
 		Name:  "verbosity",
 		Usage: "Logging verbosity: 0-6 (0=silent, 1=error, 2=warn, 3=info, 4=core, 5=debug, 6=debug detail)",
 		Value: int(logger.InfoLevel),
 	}
-	LogJSONFlag = cli.StringFlag{
-		Name:  "logjson",
-		Usage: "Send json structured log output to a file or '-' for standard output (default: no json output)",
+	LogFileFlag = cli.StringFlag{
+		Name:  "logfile",
+		Usage: "Log output file within the data dir (default = no log file generated)",
 		Value: "",
 	}
-	LogToStdErrFlag = cli.BoolFlag{
-		Name:  "logtostderr",
-		Usage: "Logs are written to standard error instead of to files.",
-	}
 	LogVModuleFlag = cli.GenericFlag{
 		Name:  "vmodule",
-		Usage: "The syntax of the argument is a comma-separated list of pattern=N, where pattern is a literal file name (minus the \".go\" suffix) or \"glob\" pattern and N is a log verbosity level.",
+		Usage: "Per-module verbosity: comma-separated list of <module>=<level>, where <module> is file literal or a glog pattern",
 		Value: glog.GetVModule(),
 	}
 	BacktraceAtFlag = cli.GenericFlag{
-		Name:  "backtrace_at",
-		Usage: "If set to a file and line number (e.g., \"block.go:271\") holding a logging statement, a stack trace will be logged",
+		Name:  "backtrace",
+		Usage: "Request a stack trace at a specific logging statement (e.g. \"block.go:271\")",
 		Value: glog.GetTraceLocation(),
 	}
 	PProfEanbledFlag = cli.BoolFlag{
@@ -262,37 +247,37 @@ var (
 	}
 	PProfPortFlag = cli.IntFlag{
 		Name:  "pprofport",
-		Usage: "Port on which the profiler should listen",
+		Usage: "Profile server listening port",
 		Value: 6060,
 	}
 	MetricsEnabledFlag = cli.BoolFlag{
 		Name:  metrics.MetricsEnabledFlag,
-		Usage: "Enables metrics collection and reporting",
+		Usage: "Enable metrics collection and reporting",
 	}
 
 	// RPC settings
 	RPCEnabledFlag = cli.BoolFlag{
 		Name:  "rpc",
-		Usage: "Enable the JSON-RPC server",
+		Usage: "Enable the HTTP-RPC server",
 	}
 	RPCListenAddrFlag = cli.StringFlag{
 		Name:  "rpcaddr",
-		Usage: "Listening address for the JSON-RPC server",
+		Usage: "HTTP-RPC server listening interface",
 		Value: "127.0.0.1",
 	}
 	RPCPortFlag = cli.IntFlag{
 		Name:  "rpcport",
-		Usage: "Port on which the JSON-RPC server should listen",
+		Usage: "HTTP-RPC server listening port",
 		Value: 8545,
 	}
 	RPCCORSDomainFlag = cli.StringFlag{
 		Name:  "rpccorsdomain",
-		Usage: "Domain on which to send Access-Control-Allow-Origin header",
+		Usage: "Domains from which to accept cross origin requests (browser enforced)",
 		Value: "",
 	}
 	RpcApiFlag = cli.StringFlag{
 		Name:  "rpcapi",
-		Usage: "Specify the API's which are offered over the HTTP RPC interface",
+		Usage: "API's offered over the HTTP-RPC interface",
 		Value: comms.DefaultHttpRpcApis,
 	}
 	IPCDisabledFlag = cli.BoolFlag{
@@ -301,7 +286,7 @@ var (
 	}
 	IPCApiFlag = cli.StringFlag{
 		Name:  "ipcapi",
-		Usage: "Specify the API's which are offered over the IPC interface",
+		Usage: "API's offered over the IPC-RPC interface",
 		Value: comms.DefaultIpcApis,
 	}
 	IPCPathFlag = DirectoryFlag{
@@ -311,7 +296,7 @@ var (
 	}
 	ExecFlag = cli.StringFlag{
 		Name:  "exec",
-		Usage: "Execute javascript statement (only in combination with console/attach)",
+		Usage: "Execute JavaScript statement (only in combination with console/attach)",
 	}
 	// Network Settings
 	MaxPeersFlag = cli.IntFlag{
@@ -331,7 +316,7 @@ var (
 	}
 	BootnodesFlag = cli.StringFlag{
 		Name:  "bootnodes",
-		Usage: "Space-separated enode URLs for p2p discovery bootstrap",
+		Usage: "Space-separated enode URLs for P2P discovery bootstrap",
 		Value: "",
 	}
 	NodeKeyFileFlag = cli.StringFlag{
@@ -353,19 +338,21 @@ var (
 	}
 	WhisperEnabledFlag = cli.BoolFlag{
 		Name:  "shh",
-		Usage: "Enable whisper",
+		Usage: "Enable Whisper",
 	}
 	// ATM the url is left to the user and deployment to
 	JSpathFlag = cli.StringFlag{
 		Name:  "jspath",
-		Usage: "JS root path for loadScript and document root for admin.httpGet",
+		Usage: "JavaSript root path for `loadScript` and document root for `admin.httpGet`",
 		Value: ".",
 	}
 	SolcPathFlag = cli.StringFlag{
 		Name:  "solc",
-		Usage: "solidity compiler to be used",
+		Usage: "Solidity compiler command to be used",
 		Value: "solc",
 	}
+
+	// Gas price oracle settings
 	GpoMinGasPriceFlag = cli.StringFlag{
 		Name:  "gpomin",
 		Usage: "Minimum suggested gas price",
@@ -441,7 +428,6 @@ func MakeEthConfig(clientID, version string, ctx *cli.Context) *eth.Config {
 	cfg := &eth.Config{
 		Name:                    common.MakeName(clientID, version),
 		DataDir:                 MustDataDir(ctx),
-		GenesisNonce:            ctx.GlobalInt(GenesisNonceFlag.Name),
 		GenesisFile:             ctx.GlobalString(GenesisFileFlag.Name),
 		FastSync:                ctx.GlobalBool(FastSyncFlag.Name),
 		BlockChainVersion:       ctx.GlobalInt(BlockchainVersionFlag.Name),
@@ -450,7 +436,6 @@ func MakeEthConfig(clientID, version string, ctx *cli.Context) *eth.Config {
 		NetworkId:               ctx.GlobalInt(NetworkIdFlag.Name),
 		LogFile:                 ctx.GlobalString(LogFileFlag.Name),
 		Verbosity:               ctx.GlobalInt(VerbosityFlag.Name),
-		LogJSON:                 ctx.GlobalString(LogJSONFlag.Name),
 		Etherbase:               common.HexToAddress(etherbase),
 		MinerThreads:            ctx.GlobalInt(MinerThreadsFlag.Name),
 		AccountManager:          am,