PEP 287: reStructuredText Standard Docstring Format

[John Roth]

"David Goodger" <goodger at users.sourceforge.net> wrote in message
news:B8CFEB59.20D3E%goodger at users.sourceforge.net...
> John Roth wrote:

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

It's this one. PEP 258 does not reassure me, until I see it
in the same, or an earlier, version of Python than this goes into.
Unless that happens, the reference is pie in the sky snake oil.

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

I think you've missed the point. If you **need** markup, then
it's too complex for the quick help that docstrings were originally
intended for, and that many people routinely include in their programs.

I'm not against including documentation in the **source**, nor am
I against a supported syntax for doing so. What I'm against is
coopting a mechanism intended for something else, when at least
some people want **both**.

John Roth
>
> --
> 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
>