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