httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From r..@covalent.net
Subject Re: pod2text
Date Thu, 01 Jun 2000 18:15:15 GMT

I really don't think it is the format.  Having the docs in the header
files means that the majority of the header file is documentation instead
of prototypes.  This makes the header harder to read, and it makes it
harder for people to find what they want.

As far as a single point for the docs, when the docs were in the C files,
there was a single point for the docs.  It was the Unix
(common) directories C files.  Since there are no functions in APR that
Unix doesn't implement this works just fine, and it keeps the docs away
from people who just want to quickly find a prototype.

We NEVER duplicated docs, (well we did for a few days, once) at a time 
when files were first copied to a new directory and before they were
modified to be completely un-recognizable and cleaned of docs.

BTW, having the API docs in the C files worked for the entire time that
APR was being heavily modified.  The fact is that if we are just using the
comments to generate real docs, then it doesn't matter what format they
are in or where it is stored.  Is POD perfect, no.  Should we change
it?  I don't really care, I put it in POD because it was easy and I needed
it done ASAP.  Should it be moved out of the headers?  IMHO yes most
definately.  The headers should be small and easy for people to use to
grab the prototypes.  If we want minimal docs in there fine, but don't
make people wade through tons of API docs just to get to the prototypes.

Ryan

> I think that they should stay in the header. Since the APR file structure
> allows for multiple implementations, then the header is the single point
> for the docs (conversely: duplicating the docs across files will lead to
> skew much more easily).
> 
> Using a different format should clean up the headers, so they are more
> readable.

_______________________________________________________________________________
Ryan Bloom                        	rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------


Mime
View raw message