Re: API documentation wanted (for Python in particular)

On Sun, 12 Mar 2006, Daniel Berlin wrote:
> > Daniel> See, this is where i disagree. Expecting people to read well
> > Daniel> documented .h files to discover what the interface for
> > Daniel> something is, IMHO, is perfectly fine.

I strongly disagree. Expecting people to have the sources lying around
is unreasonable. The people who install binary packages that were
created by third parties would also like documentation.

> It's pretty standard in projects i've seen to keep API documentation in
> the code, or have it generated from the comments. Anything else gets
> out of date *very* quickly, and becomes worse than useless.

Generating documentation from structured comments in the code makes
a lot of sense. Doxygen can do that. The subversion project uses
doxygen. The missing pieces are:

  * The procedure for rolling release tarballs doesn't include
    "run doxygen to generate the documentation".
  * The release tarballs don't include the doxygen-generated
    documentation.
  * The install procedure doesn't install the doxygen-documented
    documentation.

--apb (Alan Barrett)

---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Received on Wed Mar 15 07:05:36 2006