[docs] [issue13386] Document documentation conventions for optional args
report at bugs.python.org
Mon Nov 14 00:13:56 CET 2011
Eli Bendersky <eliben at gmail.com> added the comment:
Ezio, regarding your latest message:
"The problem is when the default placeholder is some unique object() or some _internal value (we had something similar with a socket timeout once)."
I hope this should be rare enough not to present a significant problem with the _convention_. Such cases can be reviewed specifically and the best way to document will be discussed per case.
"Also for something like str.strip(), would you document chars=None or chars=" \n\r\t\v\f"?"
I think it would be better to document chars=None, because this is a simple value the user can pass (if he wants to do it explicitly), without thinking (and forgetting) about the specific delimeters. That None actually means " \n\r\t\v\f" should be explicitly documented below the function signature, of course.
Python tracker <report at bugs.python.org>
More information about the docs