[PYTHON DOC-SIG] Docstrings .. formatting
Richard Jones
richard.jones@BoM.GOV.AU
Fri, 19 Apr 1996 01:35:19 GMT
[Guido, I've cc'ed this to you because I'm not sure if you get all the SIG
lists... sorry if you get a dupe...]
Warning! Warning! This email rambles! Stream of consciousness!
OK, I've just finished a 3-day Java course. I've gotta say that they
have definitely got a Good Thing in their class browser that interprets
the documentation within the class files.
Now, Python has got docstrings, which are in some ways better than
comments a-la Java. They're also worse in other ways.
Some of the benefits:
- Nice and easy and obvious to add to modules.
Some of the disadvantages:
- Difficult to access.
- No standard format for docstrings making a class browser type
application quite difficult.
At the moment, Python has two documentation sources, which can be (and at
the moment, are) out of sync. And it's a pain as a developer to have to
create two sets of documentation.
I realise that there's some pretty printers out there that will handle
some docstrings, but unfortunately they required the module to either be
in Python or for them to be imported. Importing often isn't enough - you
actually need to instatiate an object to access some of the docstrings.
This is unacceptable.
The solution seems obvious:
. We need to make docstrings available to the user at the instant that
the module is imported. No instantiation should be required. This would
probably (definitely?) require changes to the way that docstrings are
stored in the interpreter. Would it perhaps be possible to store them in
one container per module?
. We need to standardise the format of docstrings. This should not be
difficult. Really. What I propose to this end is that we supply a list
of recommended fields within the docstring, which may be as simple as
`Usage:', `Description:', `See Also:', `Keywords:' etc. These fields are
then defined to contain such information as, in the case of the
`Description:' field, a one-line description followed by a more lengthy
description if required. Extracting and using information stored this way
in a docstring would be made much easier.
Once the above two steps are taken, it will be much easier to create and
update meaningful documentation (and using the `See Also' field,
cross-references) and produce consistent pretty documentation.
Comments?
Richard
Richard Jones, Satellite Section at the Bureau of Meteorology, Australia.
MIME and PGP accepted. Work phone: +61-3-9669-4539
=================
DOC-SIG - SIG for the Python Documentation Project
send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================