[PYTHON DOC-SIG] Docstrings .. formatting

[Richard Jones]

[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
=================