[docs] [issue13386] Document documentation conventions for optional args

[Ezio Melotti]

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>
<http://bugs.python.org/issue13386>
_______________________________________