[Python-3000] Conventions for annotation consumers (was: Re: Draft pre-PEP: function annotations)

[Jim Jewett]

On 8/15/06, Collin Winter <collinw at gmail.com> wrote:
> ... that users won't be using multiple type systems on the same parameter
> (and if they are, that their own problem); for "doc" is that a
> docstring is just a Python string, and there's really only own way to
> look at that within the scope of documentation strings.

oh ye of little cynicism.

(1)  I might well restrict *myself* to a single type system.  But that
doesn't mean I don't ever want to use someone else's modules, or that
I don't want a doc tool to handle them.

(2)  doc strings already exist, and have already grown inconsistent
microstructure.

"""one line summary -- may or may not include the call signature

Longer documentation, which may or may not also include doctests or
ReST or html or sample calls in a non-doctest format or magic tokens
used by various frameworks, such as Design By Contract wrappers.

Oh, and that first blank line?  Some tools rely on it.  Some functions
don't use it.

Of course, some functions don't use docstrings at all, because the
writers are already afraid that a framework like unittest will
misinterpret them."""

-jJ