[Doc-SIG] docstring grammar

[David Ascher]

On Tue, 30 Nov 1999, Skip Montanaro wrote:

> The one complaint I have with the wordy signature is that it partially types
> the function.  It specifies a return type, but not the input parameter
> types.  Why go only halfway?  I suggest you either use type names for
> parameters and return value or annotate the parameter names with types:
> 
>     len(o:sequence) -> IntType

I propose to defer this discussion.  I think it's a fine idea in general,
but raises a whole bunch of issues, and mixes with other threads like
typing etc.  Furthermore, the current uses of this first line (popups in
IDLE and Pythonwin) might suffer from a significant lengthening of said
line.  Getting the type information in the docstring is however a worthy
goal, but perhaps best left for a subsection:

  Arguments:
     o (sequence) -- an arbitrary sequence object
     
I'd like to finalize the top-level structure, get it in front of GvR's
eyeballs, and then we can tackle each subtopic (so far: list processing,
reference handling, signature, mandatory keywords, keyword registration
process, multilingual keyword support, etc.) at a later date.

--david