[Python-Dev] Python Doc problems

[skip at pobox.com]

    Andrew> In such autogenerated documentation, you wind up with a list of
    Andrew> every single class and function, and both trivial and important
    Andrew> classes are given exactly the same emphasis.  

I find this true where I work as well.  Doxygen is used as a documentation
generation tool for our C++ class libraries.  Too many people use that as a
crutch to often avoid writing documentation altogether.  It's worse in many
ways than tools like epydoc, because you don't need to write any docstrings
(or specially formatted comments) to generate reams and reams of virtual
paper.  This sort of documentation is all but useless for a Python
programmer like myself.  I don't really need to know the five syntactic
constructor variants.  I need to know how to use the classes which have been
exposed to me.

I guess this is a long-winded way of saying, "me too".

Skip