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 <rep...@bugs.python.org>
<http://bugs.python.org/issue15831>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

Reply via email to