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
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4