Ezio Melotti <ezio.melotti@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@bugs.python.org> <http://bugs.python.org/issue13386> _______________________________________