[Python-Dev] PEP 287: reStructuredText Standard Docstring Format

[Samuele Pedroni]

From: Fredrik Lundh <fredrik@pythonware.com>
> samuele wrote:
> 
> > how many eons would pass before we see a PEP about
> > those *relevant* issues? Presumably JavaDoc is a good
> > start point for this <wink>.
> 
> do you need a PEP, or is it okay if I just post some code?
> 

Code please, see code is less controversial than PEPs...

[From PEP 287]

    The lack of a standard syntax for
    docstrings has hampered the development of standard tools for
    extracting docstrings and transforming them into documentation in
    standard formats (e.g., HTML, DocBook, TeX).  There have been a
    number of proposed markup formats and variations, and many tools
    tied to these proposals, but without a standard docstring format
    they have failed to gain a strong following and/or floundered
    half-finished.

Honestly, is that true?

JavaDoc would be useful even if it didn't allow HTML
but just the @tags, IOW rich formatting is a very secondary
issue, indeed programmers are lazy and the important part of
JavaDoc is getting proper inter-references and bind the information
that can be extracted from code (parms) with their doc description.

OTOH

Perl POD is used for the standard doc for Perl modules.

The API doc that comes from Sun is html produced
out of the JavaDoc markup.

Python standard doc should be specified in the format described
at http://www.python.org/doc/2.2p1/doc/doc.html, let's
refer to it as  py-tex-markup

how does the PEP relate to producing from inline docstrings
at least a first cut in a subset of the py-tex-markup format?

indeed py-tex-markup is maybe overkill for the casual module,
but the issue is also that there is not a tool that produce it
from the docs inside a casual module (or there is such tool???),
and on the same line of reasoning reST is also maybe
overkill especially if it does translate to py-tex-markup

considering-every-module-dreams-to-become-a-standard-module-and-
-receive-BDFL-blessing-ly y'rs