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

Eli Bendersky 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 mailing list