[Python-Dev] Python Doc problems (original) (raw)

A.M. Kuchling amk at amk.ca
Fri Sep 29 14:10:35 CEST 2006

On Fri, Sep 29, 2006 at 09:49:35AM +0900, stephen at xemacs.org wrote:

What is lost according to him is information about how the elements of a module work together. The docstrings tend to be narrowly focused on the particular function or variable, and too often discuss implementation details.

I agree with this, and am not very interested in tools such as epydoc for this reason. In such autogenerated documentation, you wind up with a list of every single class and function, and both trivial and important classes are given exactly the same emphasis. Such docs are useful as a reference when you know what class you need to look at, but then pydoc also works well for that purpose.

--amk

More information about the Python-Dev mailing list