mojombo/tomdoc — Issue #37: Confusion about optional options
Author: dasch
Created: 2011-11-13 13:21:01+00:00
State: open

The specification states that:

> If an argument is optional, you MUST specify the default value.

And continues to display an examples where the `(default: "...")` syntax is used to denote the default value. In the next paragraph:

> For hash arguments, you SHOULD enumerate each valid option in a way similar to how normal arguments are defined.

Yet these use a completely different syntax to denote optional arguments/options, appending `(optional)` to the descriptions.

Why this discrepancy? I would find it easier to read and write TomDoc if these two forms were identical, differing only in the way the arguments were passed (named/positional).

I suggest either allowing both syntaxes or only one, but have it be the same for normal arguments and the options hash items.