[Doc-SIG] docstring grammar

[Skip Montanaro]

    Edward> Skip said:
    >> len(o:sequence) -> IntType
    Edward> no, yuck, don't do it.

    Edward> Pack that information into the argument sections by all means;
    Edward> but the way for that one-liner to `name' the arguments should be
    Edward> about getting across the `what does this argument mean'
    Edward> information.  Being told

    Edward>     transcribe(s1:stream, s2:stream)

    Edward> doesn't tell me the thing I really want to know, where

    Edward>     transcribe(source, target)

Whatever... ;-)

The point I guess I tried to make but didn't was that the

    sig -> type

line types the return value but not the parameters.  If the arguments are to
be typed someplace else, that's cool.  Where will the return type be
"declared"?  Just in the -> sig?

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