[docs] [issue13386] Document documentation conventions for optional args
Eric V. Smith
report at bugs.python.org
Sat Nov 12 11:53:48 CET 2011
Eric V. Smith <eric at trueblade.com> added the comment:
To your last point, I think it's important to specify the default value placeholder (basically a sentinel) in the documentation. For example, if a function takes -1 to mean "all occurrences", then the caller needs to know how what value to pass in in order to let the function compute the value. This is especially true if it's cheaper for the function to compute the value instead of the caller.
I've run into this problem before, where I wanted to pass in some sentinel value and I had to read the source to figure out what it was. I think the function was in the standard library, but now I can't recall what it was.
Python tracker <report at bugs.python.org>
More information about the docs