apache api documentation

[Stanley Gambarin <st...@cs.bu.edu>]

	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 
down the amount of time required by other developers to learn all the 
functions provided by core, and avoid reinventing already existing
functions.  The documentation would also allow to distinguish the
functions that should be used by the whole server (scope: global), 
functions allowed to be used only by the core (scope: core_local), 
functions written for use by only one module (scope: mod_local), and
possibly functions that are calling outside programs (scope: extern).
	This would also provide for the basis of establishing module
dependencies to avoid code repetition (e.g. mod_include and mod_cgi have
some code which is identical).  Using the above scheme, it would be
possible to either (a) require both modules to be compiled together or
(b) extract common parts (by Perl-written preprocessor) into a separate 
file and still keep module independence.
	Another nifty idea would be to use scope: rule in the headers
to generate different header files (ones to be used by module only,
if scope: mod_local, or only http_*.c , if scope: core_local).

	Note that this is a long term project and probably would be a
good addition to 2.0  I volunteer to start writing the aforementioned
documentation iff there is a general interest in seeing the above in 
the server.  If not,  well then, ...
	As an example, I provided a short example of what I envision
the docs to look like (this is for open_error_log() in http_log.c)
Any feedback is always welcomed...
							Stanley.
/*apapi
 *
 * name		: open_error_log
 * scope	: core_local
 * arg		: server_rec 	*s
 * arg		: pool 		*p
 * retval	: void
 * descr	: This function opens an error log for the server.
 *		  The name for the log is contained in the error_fname
 *                field of the server_rec structure.  If the name starts
 *                with a "|", the server starts the program, which is 
 *                specified by the string following the "|" and feeds any 
 *                error messages to the program's standard input.
 *                After successful completion, an error message can be
 *                logged via (FILE *)error_log member of the server_rec 
 *                structure.
 * notes       	: Any error conditions will result in the server
 *                termination.  Memory is allocated from pool structure,
 *                specified as an argument.
 * future  	: Set error condition and return, without exiting.
 */ 
void open_error_log(server_rec *s, pool *p)
{ ... }

Re: apache api documentation

[Marc Slemko <ma...@worldgate.com>]

On Wed, 9 Jul 1997, Alexei Kosut wrote:

> 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 :)

General comment: more things in the source should be documented.  I would
be happy with every function having a comment with documentation.  One of
the many problems I run into when debugging things, is that very few
functions are documented as working _any_ way; they just do something
which sometimes is something like what something that calls it somewhere
wants.

Re: apache api documentation

[Alexei Kosut <ak...@organic.com>]

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 <ak...@organic.com>

Re: apache api documentation

[Ingo Luetkebohle <in...@blank.pages.de>]

On Thu, 10 Jul 1997, Stanley Gambarin wrote:
> Warning: this is a long message.  I will soon have some free time

You lucky boy ;-)

Anyway, great idea. Do it.

---/dev/il

Re: apache api documentation

[Marc Slemko <ma...@worldgate.com>]

On Thu, 10 Jul 1997, Stanley Gambarin wrote:

> /*apapi

This is not strictly part of the API.  Functions 

>  *
>  * name		: open_error_log
>  * scope	: core_local
>  * arg		: server_rec 	*s
>  * arg		: pool 		*p
>  * retval	: void

I can see what arguments it takes and what it returns from the 
definition.

>  * descr	: This function opens an error log for the server.
>  *		  The name for the log is contained in the error_fname
>  *                field of the server_rec structure.  If the name starts
>  *                with a "|", the server starts the program, which is 
>  *                specified by the string following the "|" and feeds any 
>  *                error messages to the program's standard input.
>  *                After successful completion, an error message can be
>  *                logged via (FILE *)error_log member of the server_rec 
>  *                structure.
>  * notes       	: Any error conditions will result in the server
>  *                termination.  Memory is allocated from pool structure,
>  *                specified as an argument.
>  * future  	: Set error condition and return, without exiting.
>  */ 
> void open_error_log(server_rec *s, pool *p)
> { ... }

I'm not sure it is necessary to go into that much depth.  The purpose
shouldn't be to explain the code (after all, code is the best
documentation) but provide a general overview.  Preconditions and
postoconditions would be useful (not formal ones necessarily, just stuff
like "takes a non-null string and converts it into a TCP packet to kill a
NT box".  

The main focus should be on the API itself and defining it; not so much
because people can't understand it as because it would provide a
documented standard for how things _should_ interact and what modules
should do and should use, as opposed to the current "if-it-works-do-it
until it is changed for the next version because no one knows what it is
supposed to do".