[Python-Dev] Questions/comments on documentation formatting

[Brett Cannon]

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