[Python-Dev] PEP 287: reStructuredText Standard Docstring Format (original) (raw)

Samuele Pedroni pedroni@inf.ethz.ch
Fri, 5 Apr 2002 02:22:01 +0200

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