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

Jim Jewett jimjjewett at gmail.com
Wed Aug 16 01:22:24 CEST 2006

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

"""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."""


More information about the Python-3000 mailing list