[Doc-SIG] Re: docstring signatures

[Guido van Rossum]

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

Hm, strange.  Tibs must have been channeling someone else.  I've used
this style of docstrings for C functions, where there's no good way to
find out the arguments, but not on Python functions and methods.

> 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)?

Sure.

> 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

PS.  Don't spend too much time trying to make StructuredText or some
variation thereof work.  In my experience with systems that use ST
(like ZWiki), it sucks.  There basically are two options I like:
nicely laid out plain text, or a real markup language like Latex or
DocBook.

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