[bug] CLI Help when some "options" are required is self-contradicting

[shannonwells]

Description

In several places in the CLI help, we have text that puts --someOption in square brackets, but such an option is required. This is confusing, since the extended help has no indication that these things are required. Example is the miner create help text quoted below.

If I run the miner create command as I have before (go-filecoin miner create 10 100), it fails, saying only that --price is required. But both gas price and gas limit are required arguments. In Unix help, square brackets around an argument mean it is optional, however these arguments are in square brackets in the help text. In the "USAGE" section and the miner --help output, --price and --limit aren't shown at all (so the miner command help can't be used as a quick reference because it's incomplete). In the "OPTIONS" shown below, --price and --limit also aren't marked required.

Expected Behavior

All help text should show all required arguments. The only arguments in square brackets should be optional ones. In the extended help (e.g. OPTIONS section), these arguments should say "required" in some way, and be the same way everywhere.

Current Behavior

 $ gf miner create --help
USAGE
  go-filecoin miner create <pledge> <collateral> - Create a new file miner with <pledge> 1GB sectors and <collateral> FIL

SYNOPSIS
  go-filecoin miner create [--from=<from>] [--peerid=<peerid>] [--price=<price>] [--limit=<limit>] [--] <pledge> <collateral>

ARGUMENTS

  <pledge>     - The size of the pledge (in 1GB sectors) for the miner
  <collateral> - The amount of collateral in FIL to be sent (minimum 0.001 FIL per sector)

OPTIONS

  --from   string - Address to send from.
  --peerid string - Base58-encoded libp2p peer ID that the miner will operate.
  --price  string - Price (FIL e.g. 0.00013) to pay for each GasUnits consumed mining this message.
  --limit  uint64 - Maximum number of GasUnits this message is allowed to consume.

Starting points

If there is a single default gas limit and gas price, then the default option text will need to be updated in main.go.

Also look in commands/ for functions that call parseGasOptions:

• message.go
• miner.go and other functions in this file
• payment_channel.go and other functions in this file

[mishmosh]

@shannonwells in order to prepare this as a good first issue, can you please add some clarification?

1. Please specify which command(s) need to be edited
2. Add links to code

[travisperson]

I believe these are actually going to be optional at some point right? I believe I remember @acruikshank saying that later the price and limit will be set to best guesses automatically.

Should the fix here be to set defaults on the options that can later be removed when we have the best-guess behavior?

[shannonwells]

I think that's a good idea. If there are defaults set they should also be documented.

[travisperson]

I think we get the documentation for free (at least if we are just documenting in the command help text). An example of this is the ping command.

https://github.com/filecoin-project/go-filecoin/blob/7cc6a6b790c3fd74e2f68c061a5e239348037b32/commands/ping.go#L27-L29

USAGE
  go-filecoin ping <peer ID>... - Send echo request packets to p2p network members

SYNOPSIS
  go-filecoin ping [--count=<count> | -n] [--] <peer ID>...

ARGUMENTS

  <peer ID>... - ID of peer to be pinged.

OPTIONS

  -n, --count uint - Number of ping messages to send. Default: 10.

[shannonwells]

by "documented" I meant "documented in the help output," not in a separate document.