httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marc Slemko <ma...@worldgate.com>
Subject Re: apache api documentation
Date Thu, 10 Jul 1997 04:37:16 GMT
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".



Mime
View raw message