[Python-Dev] Python Doc problems

skip at pobox.com skip at pobox.com
Fri Sep 29 15:05:18 CEST 2006


    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


More information about the Python-Dev mailing list