Georg Brandl wrote:
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.
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]])
What does everyone think?
My proposal: Since we already give a Python-like signature, why not give the
full signature for Python functions? That is, simply show default values for
arguments like
warnings.filterwarnings(action, message="", category=Warning, module="",
lineno=0, append=0)
That way, we also can get rid of awkward tons of parenthetical remarks like
in "If foo is None (which is the default)", and also get to add that information
in the first place where it was missing before.
The argument defaults can be shown in a different typographical style if
desired. Parameters whose default isn't easily displayable can continue to use
the brackets.
For C module functions that don't support keyword arguments, the old way of
nested brackets precisely represents how to call the function, so it should
stay.
Sadly, this proposal is also the most work-intensive one since no automatic
conversion is possible. This being the docs, it is however possible to tackle
this over time on a per-module basis, so this is not necessarily a killer
argument.
+1
It is the most easily understood format by Python programmers for
obvious reasons. Actually static code analysis should be able to
automate this (or even live introspection).
Michael
Georg
--
http://www.ironpythoninaction.com/
http://www.voidspace.org.uk/
http://www.trypython.org/
http://www.ironpython.info/
http://www.theotherdelia.co.uk/
http://www.resolverhacks.net/
_______________________________________________
Doc-SIG maillist - Doc-SIG@python.org
http://mail.python.org/mailman/listinfo/doc-sig
