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