[Doc-SIG] docstring signatures

[Edward D. Loper]

Guido,

On doc-sig, we're trying to put together some standards/conventions
for writing documentation strings, to propose in a PEP.  (These
conventions could then be used by all manner of docstring-related
tools).  Tibs said he thought that you wanted to require that such
conventions include a "signature" for docstrings of callable objects,
such as::

    def primes(n):
        """
        primes(n) -> lst -- Return a list of all primes in the range [2,n].
        
        <more detailed description...>
        """
        ...

or::
    def primes(n):
        """
        primes(n) -> lst

        Return a list of all primes in the range [2,n].
        
        <more detailed description...>
        """
        ...

However, it was unclear to me whether that would be affected any by
the introduction of tools like inspect.py and pydoc.py's help
function.  In particular, much of the "signature" information can be
obtained by calls to inspect methods; and there is a question of what
to do if the "signature" disagrees with inspect.

When designing our docstring conventions, should we include
signatures, like the one given?  Or can we feel free to put
information about what is returned by the function, etc., in other
places (e.g., under a "Returns: " section)?

If you do want us to include signatures, is there somewhere
where what they should look like is defined (e.g., whether
you should say "primes(n) -> lst" or "primes(int) -> list")?

-Edward