A.M. Kuchling schrieb:
To show a series of optional parameters, currently we nest square
brackets.
http://docs.python.org/dev/library/warnings.html#warnings.filterwarnings
warnings.filterwarnings(action[, message[, category[, module[,
lineno[, append]]]]])
My proposal is that we drop the nesting and write this as:
warnings.filterwarnings(action [, message, category, module, lineno, append])
Currently the stylesheets make the brackets very big and dark, so I've
also added a space before the bracket.
Which will be ignored by the signature parser :)
This change means we'd lose the ability to show when two optional
arguments must be supplied at the same time, which could currently be
written like this:
warnings.filterwarnings(action[, message, category[, module]])
In this hypothetical example, if you supply 'message' you must also
supply 'category'. But I think that for most functions, you can
supply each optional argument or not; you rarely need to supply two
optional arguments that are tied in this way, and we can handle such
cases by adding a sentence such as "Both message and category parameters
must be supplied."
That's reasonable. I can't remember if there's a function like this
anywhere (with only the signature as a sign of this calling requirement).
A few places (difflib, doctest, probably others) use this format:
... function:: context_diff(a, b[, fromfile][, tofile][, fromfiledate][,
tofiledate][, n][, lineterm])
It's better than the nested version -- at least it avoids the ]]]]])
at the end -- but I think having a single set of square brackets also
works and reduces the symbolic noise further.
... function:: context_diff(a, b [, fromfile, tofile, fromfiledate, tofiledate,
n, lineterm])
The brackets are large enough that I think this would still be quite
readable; it doesn't seem likely that readers will miss that these
parameters are optional.
What does everyone think?
I'm +0. I'd like to hear Fred's opinion since (I guess) he introduced the
nested bracket notation. If he's okay with it, I'll write a script that
converts the signatures in the whole documentation.
cheers,
Georg
--
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.
_______________________________________________
Doc-SIG maillist - Doc-SIG@python.org
http://mail.python.org/mailman/listinfo/doc-sig
