[docs] [issue15831] comma after leading optional argument is after bracket in docs

[Chris Jerdonek]

Chris Jerdonek added the comment:

Thanks for responding to all of those questions, Ezio.  I will update the patch based on your responses.  (Likely most of it will remain the same.)

> Note that if possible, it's better to avoid using the [] and put the default
> values.  However, in these cases the default value seems to be a _void
> placeholder.

Yes, the defaults are "private" in those cases (and in I think pretty much all cases in the patch in which []'s rather than a default value are used to display keyword arguments).

> > I was curious what the preferred way to display the following is,
> > since I don't think any comma/bracket placement will work:
> >
> > ArgumentParser([description][, epilog][, prog][, usage][, add_help][, argument_default][, parents][, prefix_chars][, conflict_handler][, formatter_class])

> If the default values are known you could use them, otherwise this signature looks OK to me.

The comma not being inside the first bracket is what I was concerned about here (which was the issue raised in the original comment).  Using an initial * which you are okay with will address this.  (And yes, they are all keyword arguments.  In fact, the order of the arguments in the docs does not even match the order in the code.)

> > By the way, is the * really necessary in these examples?

> If the args on the right of the * are keyword-only and the one on the left aren't, then yes.

Okay.  I think what threw me is that I don't think we're consistently using the * throughout our docs to denote the beginning of keyword-only arguments.  The ArgumentParser constructor above is just one example.  So I wasn't sure if this notation was preferred or discouraged.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue15831>
_______________________________________