[docs] [issue13386] Document documentation conventions for optional args
report at bugs.python.org
Mon Nov 14 13:40:09 CET 2011
Ezio Melotti <ezio.melotti at gmail.com> added the comment:
Thanks for the feedback!
> 1) she naturally understood the meaning of the [opt] notation
I guess this depends on her background, I've seen people trying to use  in function calls because they saw them in the doc or confusing them for lists, so I guess that each notation has its pros and cons.
> 2) she did not understand the opt=default notation, as she didn't
> have a sufficient experience with Python to recognize the syntax
I agree that at the beginning it could be a bit confusing, but keyword arguments are an important part of Python and it's among the first things that one should learn. After that it should be even more natural than .
> 3) even after learning what it meant, she still found that notation
> obscure and unappealing
...or maybe not. Can she say what in particular is obscure and unappealing?
> 4) she got annoyed that two completely different notations where used
> for two very close concepts
This is a good point, and we are trying to move to the arg=default notation. Unfortunately there are still places that use the old notation. C functions that have optional arguments but don't accept keyword arguments are a bit unusual, and IIUC in most of the cases that's an implementation detail that could be removed.
> 5) she got annoyed that there was no user-discoverable and
> user-understandable document introducing those notations (if there is > one, my mistake :-)
This brings ups another interesting point. These conventions will probably end up in the "documenting" section, that is aimed to doc writers. Do we need an introductory page aimed to the readers that explains the conventions used in the doc?
Python tracker <report at bugs.python.org>
More information about the docs