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

[Ron Adam]

Georg Brandl wrote:

> 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.

I think that would be fine.  Maybe a separate section can be added on the 
topic of understanding function arguments that uses the nested bracketed 
forms to help users understand python signatures.

I was hoping at some point we might be able to generate the signatures and 
summary automatically from the source, and merge in the discussion and 
examples.  But currently generating signatures isn't possible for all 
functions.

BTW... Have you tried out the pydoc patch I submitted George?  I haven't 
got any feedback on it yet, so it's just sitting there gathering dust.

          http://bugs.python.org/issue2001

Ron





> 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.
> 
> Georg
>