Add support for optional arguments and/or getopt-style options

[lkrms]

Great project! Thanks for all of your work on it 🙌🏻

Before I can convert my function docs to shdoc annotations, I need to find a way to mark arguments as optional, i.e. something equivalent to this:

# my_func REQUIRED_ARG [OPTIONAL_ARG]
my_func() {
  # ...
}

A few possibilities for the melting pot of ideas:

1. @arg?

# @arg $1 string A required argument.
# @arg? $2 string An optional argument.

2. @arg [$2]

# @arg $1 string A required argument.
# @arg [$2] string An optional argument.

3. @arg ?$2

# @arg $1 string A required argument.
# @arg ?$2 string An optional argument.

Non-positional arguments a.k.a. getopt-style options

I don't have suggested syntax ready to go, but annotations to add support for getopt-style options (flags, values, optional values) would be excellent.

These are typically described as follows, where REQUIRED and OPTIONAL are positional:

# my_func [-f] [-w VALUE] [-wOPTIONAL_VALUE] REQUIRED [OPTIONAL...]

Caveats

More complex arrangements would probably be too difficult to design intuitive annotation syntax for and could be explained in @description if needed:

# my_func REQUIRED_ARG [[OPTIONAL_ARG2] OPTIONAL_ARG]

That said, maybe an optional @synopsis tag or similar could be used to provide a compact one-line summary using agreed syntax à la docopt:

# @synopsis my_func <required_arg> [[optional_arg2] optional_arg]

A default synopsis could be generated from @arg annotations if not given explicitly.