Python Documentation Blows!

[Roger Binns]

> What would it take to develop an JavaDoc like repository.

Have you seen what epydoc produces?  Here is an example:

  http://epydoc.sourceforge.net/stdlib/

I have found *by far* that the best docs are for PHP.
It has little to do with the actual official content
(which is fairly complete and well written and almost always
includes an example), but a lot to do with how anybody can
annotate the pages, wiki style.  Here is an example for
the sort function:

  http://us2.php.net/manual/en/function.sort.php

Having all those comments is really helpful, and they also
help for updating the documentation.  If there are a lot
of comments against a page then the main body really
needs some more work!

(And for those of you who don't know PHP, you will find
the commentary confusing.  This is because one of the
authors of PHP decided that a list is the same thing
as a dict with numeric keys, and so PHP only has a
dict type that behaves like lists and dicts.  I
won't even mention the tripe equals sign operator!)

Roger