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

Guido van Rossum guido at python.org
Fri Sep 29 21:29:31 CEST 2006

On 9/29/06, A.M. Kuchling <amk at amk.ca> wrote:

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.

Right.

BTW isn't xah a well-known troll? (There are exactly 666 Google hits for the query ``xah troll'' -- draw your own conclusions. :-)

-- --Guido van Rossum (home page: http://www.python.org/~guido/)

More information about the Python-Dev mailing list