[issue13386] Document documentation conventions for optional args

[Ezio Melotti]

Ezio Melotti <ezio.melotti at gmail.com> added the comment:

> You should also explicitly specify what happens in several optional but 
> not keyword args are needed. AFAIU the convention is:
>   func(arg1, arg2[, opt1, opt2])

IIUC that would mean that either you pass only arg1 and arg2, or you also pass both opt1 and opt2.
I think the correct notation for that is e.g.:
  str.startswith(prefix[, start[, end]])

I also saw "func(foo[, bar][, baz])" for cases where either bar or baz can be passed, but since this requires keyword arguments, the "func(foo, bar=x, baz=y)" notation should be used instead, and the documentation should then explain that either one can be passed.

I also agree with what you said in your last message.  What can't be expressed with a notation can always be described with words.

----------

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