Date: Wed, 9 Jul 1997 21:23:20 -0700 (PDT)
From: Alexei Kosut <akosut@organic.com>
To: new-httpd@apache.org
Subject: Re: apache api documentation
In-Reply-To: <Pine.GSO.3.95q.970709234745.11911A-100000@csa>
Message-ID: <Pine.GSO.3.95.970709211435.24983B-100000@veal.organic.com>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Sender: new-httpd-owner@apache.org
Precedence: bulk
Reply-To: new-httpd@apache.org

On Thu, 10 Jul 1997, Stanley Gambarin wrote:

> 	Warning: this is a long message.  I will soon have some free time
> and was thinking of the following: current documentation provides a 
> minimalistic requirements for setting up and running apache web server.  
> However, there is no documentation whatsoever for the functions that are 
> used by the apache (by latest counts exceeding 600 (core+modules)).  This
> also contributes to the vagueness of the API, where no specific set of
> functions is designated for the outside use.  Therefore, I was thinking
> of sitting down and going over all functions and documenting their 
> functionality, arguments, return types, etc.  Hopefully, this would cut 

I agree with this sentiment. The Apache API has long been undocumented,
which no doubt makes it difficult for people to write well-written
modules. Your idea is sound. However, I should point out one thing:
Although the line is somewhat hazy, there is a specific set of functions
and structures (and a few globals) that make up the Apache module
API. All the other functions are supposed to be used only by the
core. However, due to the style in which Apache is programmed (and the C
language in general), there's nothing really preventing module authors
from doing so.

I don't think that core functions need to be documented. If people can't
figure it out, they shouldn't be messing with it :) Well, maybe not. But
I think it's much more important to identify and specify the module
API. If you want to spend your time doing this, that'd be great, although
you'll probably get some of it wrong - I know I would. There's some weird
stuff in there :)

However, it is defenitely not worth the time to document the functions
used by the standard modules. Those are (should be) internal to those
modules, and aren't worth documenting in the same vein as the API or even
the core functions.

Also, I'm not sure the source is the proper place for this
documentation. A web page (on dev.apache.org, maybe) would be probably
more useful. Although a quick one-line summary in the source might be
useful, if only to remind people to update the docs when they
change/add/delete an API function.

I think that if you have the time, starting such a project would be
worthwhile. Although I also think that Apache 2.0 may change a lot of the
API, and especially a lot of the core. So you may want to
wait. Certainly, documentation of the API has always been a goal of mine
for Apache 2.0. See the mail archives under such message subjects as
"Molly and the Apache API" for my thoughts on the matter.

-- Alexei Kosut <akosut@organic.com>