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