httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ryan Bloom <...@raleigh.ibm.com>
Subject Re: Apache 2000, err Apache 2.0 gets real
Date Mon, 02 Aug 1999 12:22:29 GMT

> 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.
 */

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:

seach for /* ***
Grab the project name, and the functions docs.  Strip out the leading *
from all lines.  Save it to a file called:

    projectname_projectsection

where projectname is taken from the first line, and projectsection is
taken from one of two places.  1)  A file in the directory, 2)  The name
of the most important directory in the path, determined by a command line 
option. For example the docs in apr/file_io/unix/*.c would be stored in
"apr_file_io", because I would specify that the file_io section is the
most important path section.

This could be extended later, but I think it gives us a good starting
place.

Ryan

_______________________________________________________________________
Ryan Bloom		rbb@raleigh.ibm.com
4205 S Miami Blvd	
RTP, NC 27709		It's a beautiful sight to see good dancers 
			doing simple steps.  It's a painful sight to
			see beginners doing complicated patterns.	


Mime
View raw message