# [Doc-SIG] Re: docstring signatures

**Guido van Rossum
**
guido@digicool.com

*Sat, 24 Mar 2001 14:01:05 -0500*

>* 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/)