httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ben Laurie <...@algroup.co.uk>
Subject Re: Apache 2000, err Apache 2.0 gets real
Date Mon, 02 Aug 1999 13:37:53 GMT
Ryan Bloom wrote:
> 
> > Seriously, if you want this to improve, it is my view that inline docco
> > is needed. There's lots of ways to do this. We should choose one.
> 
> Since I've been working on in-line docs for APR, I'll chime in here.  I
> would REALLY like to see Apache docs in-lined.  It can be very annoying to
> figure out what some of the functions are doing, especially if you are
> just trying to fix a small bug and don't have too much time to investigate
> everything properly.
> 
> I suggest we follow the same model I have chosen for APR, which may be
> unreasonable, because I just pulled it out of the air.  But at least that
> way, we can get started on having a simple common in-line docs format for
> all ASF projects.  Or at least a majority of them.
> 
> Basically, I have decided to go real simple with APR, and each function's
> docs look like:
> 
> /* ***APR**********************************************************
>  * Function prototype
>  *    Quick and dirty description
>  * argument description
>  * Any Notes required.  Quirky behavior, anything I felt was important to
>  * document.
>  */

This is nearly like javadoc, which is a reasonable approach, IMO. One
advantage, at least, of javadoc (-style) is that it does the prototype
for you (when you generate the out-of-code doc) and there are tools to
process it.

> Every APR function has this doc, except for the ones that came from Apache
> originally, it was painful doing what I did last week, let alone the stuff
> in the lib directory, those will get done over time.  The next step, is to
> create a script that can extract this information, which I thought I would
> do as follows:

Like I say, there are existing tools. Like doxygen, for example. It
seems silly to reinvent them.

Cheers,

Ben.

--
http://www.apache-ssl.org/ben.html

"My grandfather once told me that there are two kinds of people: those
who work and those who take the credit. He told me to try to be in the
first group; there was less competition there."
     - Indira Gandhi

Mime
View raw message