Mailman 3 September 2008 - Doc-SIG

Proposal: don't nest optional brackets
by A.M. Kuchling Sept. 26, 2008

Sept. 26, 2008

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]]) 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." 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? --amk

8 9

Re: [Doc-SIG] Proposal: don't nest optional brackets
by Forest Sept. 25, 2008

Sept. 25, 2008

On Wed, September 24, 2008 10:21 am, A.M. Kuchling wrote: > > .. method:: socket.recv_into(buffer[, nbytes[, flags]]) Straying slightly from the issue of keyword arguments, I'd like to point out that the nested brackets imply to me that the flags arg requires the nbytes arg to be present as well. Compare to your suggestions: > * Add '=' after parameters that can be provided as keywords: > buffer=, [nbytes=, flags=] ... > > * Write keyword arguments as unnested square brackets: > (buffer[, nbytes][, flags]) Neither of those notations conveys a dependence of one argument on the other.

1 0

Docs search improved
by Georg Brandl Sept. 25, 2008

Sept. 25, 2008

The docs search now searches for objects whose name contains the search word before doing full-text search. Please let me know if it works as expected. 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.

1 0