[Doc-SIG] Proposal: don't nest optional brackets

[Michael Foord]

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/