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

Éric Araujo report at bugs.python.org
Tue Nov 15 15:01:02 CET 2011


Éric Araujo <merwok at netwok.org> added the comment:

>>> 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.
>> So would it be worth the effort to identify each such place in the built-ins/stdlib and
>> eventually change them all?  I've seen support for doing so in other tracker issues and think
>> it's a good idea personally.
Me too.  (Can you give the #ids of these other issues?)

> Probably, if this will bring some added value in addition to being easier to document.
I think we should fix C functions to accept kwargs for the sake of Python programmers, not merely to ease documentation (that would just be a nice side-effect :)


> a few interesting cases such as "range([start,] stop[, step])"or "islice(seq, [start,] stop [, step])"
> I'm afraid those last examples cannot be described with valid Python syntax.
Sphinx lets us give multiple signatures.  I’ve just checked that this markup is valid and does not create duplicate index entries

  .. function:: range(stop)
                range(start, stop)
                range(start, stop, step)

:)

----------

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


More information about the docs mailing list