[docs] [issue13386] Document documentation conventions for optional args
report at bugs.python.org
Mon Nov 14 06:11:07 CET 2011
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>
More information about the docs