Re: Proposal: don't nest optional brackets
Michael Foord <[email protected]>
| Newsgroups | gmane.comp.python.documentation |
|---|---|
| Message-ID | <[email protected]> |
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 - [email protected] http://mail.python.org/mailman/listinfo/doc-sig