[issue13386] Document documentation conventions for optional args

[Baptiste Carvello]

Baptiste Carvello <devel at baptiste-carvello.net> added the comment:

Le 14/11/2011 13:40, Ezio Melotti a écrit :

>> 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.
> 

agreed, the [] notation also has its dangers. But the current situation
doesn't avoid them, because users will meet both notations.

>> 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 [].
> 

the thing is, beginners need to use other people's functions before they
really get into writing their own. You need some practice with a syntax
before you are able to recognize it in another context.

>> 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?
> 

I'd say the fact that the main information (that the argument is
optional) is not highlighted and only appears as a side-effect of having
a default. Inversely, a lot of importance is given to the value of the
default, which most users can ignore at first.

>> 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.
> 

That would would solve the problem for the stdlib, but other C libraries
also have optional arguments which don't accept keyword arguments (for
example NumPy ufuncs). Will converting to a keyword argument work for
all of them?

>> 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?
> 

I would say we need one. It should probably also be part of the "help()"
tool, as the function prototype is the first information that
help(function) displays.

Cheers,
Baptiste

----------

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