PEP 287: reStructuredText Standard Docstring Format

[David Goodger]

John Roth wrote:
> I don't particularly like the table syntax, (it's too much typing
> for my taste) but I don't have a reasonable alternative.

The readability of tables is far more important than the ease of writing.
Emacs table-mode is very useful for producing ASCII-art tables.

> The one question I've got is very, very basic:
> 
> why is it in a docstring?

The first sentence of the Abstract answers this:

    When plaintext hasn't been expressive enough for inline
    documentation, Python programmers have sought out a format for
    docstrings.

> Lots of people use docstrings for relatively short, online prompts.

I'm not sure what you mean.  I see three possibilities:

1. Are you using docstrings for something other than documentation [#]_?
   Then this PEP may not apply to your application.

   .. [#] After all, "docstring" does derive from "documentation string".

2. Are you referring to the "tooltips" that pop up in IDEs when you type
   a function/method name?  The ones I'm familiar with are generated
   from the parsed function/method signatures.

3. Are you objecting to extended, comprehensive docstrings, that may be
   unsuitable for ``print my_object.__doc__``, and may take up space in
   the running program?  Then the "Additional Docstrings" proposal from
   PEP 258 may reassure you.

If those don't address your concern, please elaborate.

> Some other mechanism should exist for extensive documentation that is
> intended for translation to some other format for eventual printing
> or display independent of the program.

That's the whole point of docstring extraction tools.  This PEP is merely
proposing a standard for the format of those docstrings.

> I much prefer not to have this stuff in the compiled module.

Then don't put it in.  Some don't want inline documentation.  Many do, and
this PEP is for them.

-- 
David Goodger    goodger at users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net