[docs] [issue13386] Document documentation conventions for optional args
report at bugs.python.org
Tue Nov 15 15:20:54 CET 2011
Éric Araujo <merwok at netwok.org> added the comment:
>> I think we should fix C functions to accept kwargs for the sake of Python programmers
> And also for compatibility for other implementations like PyPy.
> I'm still not sure that is a good idea to do a mass conversion of all the functions though.
If there were only a handful of them it may be okay, but otherwise one issue per class or module sounds good.
>> Sphinx lets us give multiple signatures
> This is something I was considering, but I'm afraid it might get too verbose
I find my example for range much more readable that the current markup with brackets.
> (and introduce yet another convention).
I can live with this special case for the two or three functions that need it. It becomes moot if range gets fixed to support kwargs :)
> Sometimes this feature is also (mis?)used to group similar functions.
IIUC it *is* the intended use case for the syntax, not a misuse: You tell Sphinx that you want link targets for these functions to end up here, and then you write doc. See for example the os docs: this syntax allows for nice grouping.
Python tracker <report at bugs.python.org>
More information about the docs