[Python-Dev] Questions/comments on documentation formatting (original) (raw)

Brett Cannon brett at python.org
Tue Jan 20 07:03:15 CET 2009

On Mon, Jan 19, 2009 at 19:02, Scott Dial <scott+python-dev at scottdial.com> wrote:

Brett Cannon wrote:

3. Are brackets for optional arguments (e.g. ``def fxn(a [, b=None [, c=None]])``) really necessary when default argument values are present? And do we really need to nest the brackets when it is obvious that having on optional argument means the rest are optional as well? I can't think of an example off the top of my head, but I'm certain the point of nesting the brackets is to delimit the optional arguments into groups. Documenting your fxn() examples as "fxn(a [, b=None, c=None])" would imply that if you provide 'b' then you must provide 'c', or if we abandon nested brackets, it's ambiguous as to the requirements. Imagine seeing "foo(a [, b=None, c=None [, d=None]])" and I think the rationale for such notation becomes clear.

Well, that is such a rare case that I don't know if it warrants the line noise in the argument declaration. That argument also doesn't make sense in the face of fxn(a [, a=None [, b=None]]) where 'b' almost always has no connection to 'a', but is still supposed to be listed that way because of positional arguments being optional. I understand using them for C functions where there is no such thing as a default argument, but it just doesn't make a ton of sense for Python code. I don't know of anyone who was confused by what help() spit out and not having fancy bracketing.

-Brett

More information about the Python-Dev mailing list