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

[Fred Drake]

[Just noticed this old conversation.]

On Jun 22, 2008, at 7:36 AM, Georg Brandl wrote:
> I'm +0. I'd like to hear Fred's opinion since (I guess) he  
> introduced the
> nested bracket notation. If he's okay with it, I'll write a script  
> that
> converts the signatures in the whole documentation.


Hmm.  I'm fairly certain I didn't create it, but at this point, I  
might be mistaken.

The nested notation makes sense for optional arguments, especially  
where keywords aren't supported.  This is still the case for many of  
the APIs written in C, and those cases often won't be changed due to  
performance considerations.  (Adding keyword support definitely slows  
things down.)

For code implemented in Python, it's less of an issue, since the  
keyword support is always there unless the author of the code went out  
of the way to avoid it (using *args, for example).  This happens, but  
isn't very common.

But that's part of my reservation about this.  With the nested  
notation, it's possible to specify signatures that are different from  
the implementation signatures.  I think that's valuable still.

So I guess now someone will tell me this has already been changed, and  
I missed it.

--sigh--


   -Fred

-- 
Fred Drake   <fdrake at acm.org>