[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: API documentation wanted (for Python in particular)

From: Alan Barrett <apb_at_cequrux.com>
Date: 2006-03-15 07:04:19 CET

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

This is an archived mail posted to the Subversion Users mailing list.