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

[Éric Araujo]

É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.
Good point.

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