[Doc-SIG] docstring grammar
email@example.com (Skip Montanaro)
Tue, 30 Nov 1999 14:39:17 -0600 (CST)
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
>>> 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
Skip Montanaro | http://www.mojam.com/
firstname.lastname@example.org | http://www.musi-cal.com/
847-971-7098 | Python: Programming the way Guido indented...