[Python-Dev] Re: [Python-checkins] python/dist/src/Lib heapq.py,NONE,1.1

[Guido van Rossum]

> > I was originally going to make it an unnamed string
> > literal -- maybe that's better?
> 
> In PEP 258 I call those "Additional Docstrings":
> 
>     Many programmers would like to make extensive use of docstrings
>     for API documentation.  However, docstrings do take up space in
>     the running program, so some of these programmers are reluctant to
>     "bloat up" their code.  Also, not all API documentation is
>     applicable to interactive environments, where __doc__ would be
>     displayed.
> 
>     The docstring processing system's extraction tools will
>     concatenate all string literal expressions which appear at the
>     beginning of a definition or after a simple assignment.  Only the
>     first strings in definitions will be available as __doc__, and can
>     be used for brief usage text suitable for interactive sessions;
>     subsequent string literals and all attribute docstrings are
>     ignored by the Python bytecode compiler and may contain more
>     extensive API information.
> 
>     Example::
> 
>         def function(arg):
>             """This is __doc__, function's docstring."""
>             """
>             This is an additional docstring, ignored by the bytecode
>             compiler, but extracted by the Docutils.
>             """
>             pass
> 
> (Original idea from Moshe Zadka.)

Ah, I thought there had to be something like that. :-)

Do you also recognize this if there are comments between?  Or blank
lines?  E.g.

   def f():
       """
       foo
       """

       # blah

       """
       bar
       """

--Guido van Rossum (home page: http://www.python.org/~guido/)