[Doc-SIG] docstring grammar

[Skip Montanaro]

In David's original proposal he wrote:

    For compatibility with Guido, IDLE and Pythonwin (and increasing the
    likelihood that the proposal will be accepted by GvR), the docstrings of
    callables must follow the following convention established in Python's
    builtins:
    
         >>> print len.__doc__
         len(object) -> integer
    
         Return the number of items of a sequence or mapping.
    
    In other words, the first paragraph must fit on a line, repeat the name
    of the callable, with a 'wordy' signature, the ' -> ' string, and the
    type of the return value.

Chiming in rather late.  Perhaps this was already discussed, but I didn't
see it in the immediate followups to David's original proposal...

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

There should be a couple shorthands, for instance, using "sequence",
"mapping" or "number" to represent objects that exhibit the given behavior,
or "object" to represent an arbitrary (untyped) parameter or return value.
Otherwise, I'd suggest the types be the names defined by the types module.
Of course, I'm ignoring the types of the elements of aggregate types.  I'll
let someone smarter make a more concrete proposal in this regard.

Why worry about this?  Well, people have been asking over and over for type
information.  This looks parseable to me, doesn't change the language, yet
could be used by a type inferencer, "safer" compiler or other type-oriented
tools.

Skip Montanaro | http://www.mojam.com/
skip@mojam.com | http://www.musi-cal.com/
847-971-7098   | Python: Programming the way Guido indented...