Return-Path: Delivered-To: apmail-apr-cvs-archive@apr.apache.org Received: (qmail 65797 invoked by uid 500); 17 Mar 2001 15:58:11 -0000 Mailing-List: contact cvs-help@apr.apache.org; run by ezmlm Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: Reply-To: dev@apr.apache.org Delivered-To: mailing list cvs@apr.apache.org Received: (qmail 65786 invoked by uid 1077); 17 Mar 2001 15:58:10 -0000 Date: 17 Mar 2001 15:58:10 -0000 Message-ID: <20010317155810.65785.qmail@apache.org> From: ben@apache.org To: apr-cvs@apache.org Subject: cvs commit: apr/include apr_errno.h apr_file_io.h ben 01/03/17 07:58:10 Modified: docs doxygen.conf include mpm_common.h util_filter.h include apr_errno.h apr_file_io.h Log: More doxygenation. Revision Changes Path 1.4 +3 -2 httpd-2.0/docs/doxygen.conf Index: doxygen.conf =================================================================== RCS file: /home/cvs/httpd-2.0/docs/doxygen.conf,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- doxygen.conf 2001/03/13 22:20:50 1.3 +++ doxygen.conf 2001/03/17 15:58:09 1.4 @@ -8,10 +8,11 @@ MACRO_EXPANSION=YES EXPAND_ONLY_PREDEF=YES -EXPAND_AS_DEFINED=AP_DECLARE +EXPAND_AS_DEFINED= # not sure why this doesn't work as EXPAND_AS_DEFINED, it should! PREDEFINED=APR_DECLARE(x)=x APR_DECLARE_NONSTD(x)=x \ - AP_DECLARE_HOOK(ret,name,args)="ret name args" + AP_DECLARE_HOOK(ret,name,args)="ret name args" AP_DECLARE(x)=x \ + AP_DECLARE_NONSTD(x)=x OPTIMIZE_OUTPUT_FOR_C=YES 1.18 +1 -0 httpd-2.0/include/mpm_common.h Index: mpm_common.h =================================================================== RCS file: /home/cvs/httpd-2.0/include/mpm_common.h,v retrieving revision 1.17 retrieving revision 1.18 diff -u -r1.17 -r1.18 --- mpm_common.h 2001/03/05 20:15:10 1.17 +++ mpm_common.h 2001/03/17 15:58:09 1.18 @@ -108,6 +108,7 @@ * MPM_SYNC_CHILD_TABLE -- sync the scoreboard image between child and parent * MPM_CHILD_PID -- Get the pid from the specified spot in the scoreboard * MPM_NOTE_CHILD_KILLED -- Note the child died in the scoreboard + * */ void ap_reclaim_child_processes(int terminate); 1.48 +62 -85 httpd-2.0/include/util_filter.h Index: util_filter.h =================================================================== RCS file: /home/cvs/httpd-2.0/include/util_filter.h,v retrieving revision 1.47 retrieving revision 1.48 diff -u -r1.47 -r1.48 --- util_filter.h 2001/02/22 04:05:57 1.47 +++ util_filter.h 2001/03/17 15:58:09 1.48 @@ -69,41 +69,38 @@ #endif /** - * @package Apache filter library + * @file util_filter.h + * @brief Apache filter library */ +/** Returned by the bottom-most filter if no data was written. + * @see ap_pass_brigade(). */ #define AP_NOBODY_WROTE -1 +/** Returned by the bottom-most filter if no data was read. + * @see ap_get_brigade(). */ #define AP_NOBODY_READ -2 +/** Returned when?? @bug find out when! */ #define AP_FILTER_ERROR -3 /** - * @heading ap_input_mode_t - input filtering modes - * - * AP_MODE_BLOCKING - * - * The filter shouldn't return until data is received or EOF is hit - * or an error occurs. - * - * AP_MODE_NONBLOCKING - * - * The filter should process any available data/status as normal, - * but will not wait for additional data. - * - * AP_MODE_PEEK - * - * The filter should return APR_SUCCESS if data is available or - * APR_EOF otherwise. The filter must not return any buckets of - * data. Data returned on a subsequent call, when mode is - * AP_MODE_BLOCKING or AP_MODE_NONBLOCKING. + * input filtering modes */ typedef enum { + /** The filter shouldn't return until data is received or EOF is hit + * or an error occurs. */ AP_MODE_BLOCKING, + /** The filter should process any available data/status as normal, + * but will not wait for additional data. */ AP_MODE_NONBLOCKING, + /** The filter should return ::APR_SUCCESS if data is available or + * ::APR_EOF otherwise. The filter must not return any buckets of + * data. Data returned on a subsequent call, when mode is + * ::AP_MODE_BLOCKING or ::AP_MODE_NONBLOCKING. */ AP_MODE_PEEK } ap_input_mode_t; -/* - * FILTER CHAIN +/** + * @defgroup filter FILTER CHAIN * * Filters operate using a "chaining" mechanism. The filters are chained * together into a sequence. When output is generated, it is passed through @@ -130,8 +127,8 @@ /* forward declare the filter type */ typedef struct ap_filter_t ap_filter_t; -/* - * ap_filter_func: +/** + * @name Filter callbacks * * This function type is used for filter callbacks. It will be passed a * pointer to "this" filter, and a "bucket" containing the content to be @@ -152,6 +149,9 @@ * the types and values of the individual buckets should not be altered. * * The return value of a filter should be an APR status value. + * + * @ingroup filter + * @{ */ typedef apr_status_t (*ap_out_filter_func)(ap_filter_t *f, apr_bucket_brigade *b); typedef apr_status_t (*ap_in_filter_func)(ap_filter_t *f, apr_bucket_brigade *b, @@ -161,55 +161,42 @@ ap_in_filter_func in_func; } ap_filter_func; +/** @} */ + /** - * @heading Filter Types - * - * ap_filter_type: - * * Filters have different types/classifications. These are used to group * and sort the filters to properly sequence their operation. * - * AP_FTYPE_CONTENT: - * These filters are used to alter the content that is passed through - * them. Examples are SSI or PHP. - * - * AP_FTYPE_HTTP_HEADER: (XXX somebody rename me or get rid of me please) - * This special type ensures that the HTTP header filter ends up in - * the proper location in the filter chain. - * - * AP_FTYPE_TRANSCODE: - * These filters implement transport encodings (e.g., chunking). - * - * AP_FTYPE_CONNECTION: - * These filters will alter the content, but in ways that are more - * strongly associated with the connection. Examples are splitting - * an HTTP connection into multiple requests and buffering HTTP - * responses across multiple requests. - * - * It is important to note that these types of filters are not allowed - * in a sub-request. A sub-request's output can certainly be filtered - * by AP_FTYPE_CONTENT filters, but all of the "final processing" is - * determined by the main request. - * - * AP_FTYPE_NETWORK: - * These filters don't alter the content. They are responsible for - * sending/receiving data to/from the client. - * * The types have a particular sort order, which allows us to insert them * into the filter chain in a determistic order. Within a particular grouping, * the ordering is equivalent to the order of calls to ap_add_*_filter(). */ typedef enum { + /** These filters are used to alter the content that is passed through + * them. Examples are SSI or PHP. */ AP_FTYPE_CONTENT = 10, + /** (XXX somebody rename me or get rid of me please) + * This special type ensures that the HTTP header filter ends up in + * the proper location in the filter chain. */ AP_FTYPE_HTTP_HEADER = 20, + /** These filters implement transport encodings (e.g., chunking). */ AP_FTYPE_TRANSCODE = 30, + /** These filters will alter the content, but in ways that are + * more strongly associated with the connection. Examples are + * splitting * an HTTP connection into multiple requests and + * buffering HTTP * responses across multiple requests. + * + * It is important to note that these types of filters are not + * allowed in a sub-request. A sub-request's output can certainly + * be filtered by ::AP_FTYPE_CONTENT filters, but all of the "final + * processing" is determined by the main request. */ AP_FTYPE_CONNECTION = 40, + /** These filters don't alter the content. They are responsible for + * sending/receiving data to/from the client. */ AP_FTYPE_NETWORK = 50 } ap_filter_type; -/* - * ap_filter_t: - * +/** * This is the request-time context structure for an installed filter (in * the output filter chain). It provides the callback to use for filtering, * the request this filter is associated with (which is important when @@ -280,12 +267,10 @@ /** * Get the current bucket brigade from the next filter on the filter * stack. The filter should return an apr_status_t value. If the bottom-most - * filter doesn't write to the network, then AP_NOBODY_READ is returned. + * filter doesn't write to the network, then ::AP_NOBODY_READ is returned. * @param filter The next filter in the chain * @param bucket The current bucket brigade - * @param mode AP_MODE_BLOCKING, AP_MODE_NONBLOCKING, or AP_MODE_PEEK - * @return apr_status_t value - * @deffunc apr_status_t ap_get_brigade(ap_filter_t *filter, apr_bucket_brigade *bucket, ap_input_mode_t mode) + * @param mode ::AP_MODE_BLOCKING, ::AP_MODE_NONBLOCKING, or ::AP_MODE_PEEK */ AP_DECLARE(apr_status_t) ap_get_brigade(ap_filter_t *filter, apr_bucket_brigade *bucket, ap_input_mode_t mode); @@ -293,11 +278,9 @@ /** * Pass the current bucket brigade down to the next filter on the filter * stack. The filter should return an apr_status_t value. If the bottom-most - * filter doesn't write to the network, then AP_NOBODY_WROTE is returned. + * filter doesn't write to the network, then ::AP_NOBODY_WROTE is returned. * @param filter The next filter in the chain * @param bucket The current bucket brigade - * @return apr_status_t value - * @deffunc apr_status_t ap_pass_brigade(ap_filter_t *filter, apr_bucket_brigade *bucket) */ AP_DECLARE(apr_status_t) ap_pass_brigade(ap_filter_t *filter, apr_bucket_brigade *bucket); @@ -309,7 +292,9 @@ * * @param name The name to attach to the filter function * @param filter_func The filter function to name - * @param ftype The type of filter function, either AP_FTYPE_CONTENT or AP_FTYPE_CONNECTION + * @param ftype The type of filter function, either ::AP_FTYPE_CONTENT or :: + * AP_FTYPE_CONNECTION + * @see add_input_filter() */ AP_DECLARE(void) ap_register_input_filter(const char *name, ap_in_filter_func filter_func, @@ -322,16 +307,15 @@ * * @param name The name to attach to the filter function * @param filter_func The filter function to name - * @param ftype The type of filter function, either AP_FTYPE_CONTENT or AP_FTYPE_CONNECTION - * @see ::ap_add_output_filter + * @param ftype The type of filter function, either ::AP_FTYPE_CONTENT or + * ::AP_FTYPE_CONNECTION + * @see ap_add_output_filter() */ AP_DECLARE(void) ap_register_output_filter(const char *name, ap_out_filter_func filter_func, ap_filter_type ftype); -/* - * ap_add_filter(): - * +/** * Adds a named filter into the filter chain on the specified request record. * The filter will be installed with the specified context pointer. * @@ -343,14 +327,10 @@ * * To re-iterate that last comment. This function is building a FIFO * list of filters. Take note of that when adding your filter to the chain. - */ -/** - * Add a filter to the current connection. Filters are added in a FIFO manner. - * The first filter added will be the first filter called. + * * @param name The name of the filter to add * @param r The request to add this filter for (or NULL if it isn't associated with a request) * @param c The connection to add the fillter for - * @deffunc void ap_add_input_filter(const char *name, void *ctx, request_rec *r, conn_rec *c) */ AP_DECLARE(ap_filter_t *) ap_add_input_filter(const char *name, void *ctx, request_rec *r, conn_rec *c); @@ -362,11 +342,16 @@ * @param ctx Context data to set in the filter * @param r The request to add this filter for (or NULL if it isn't associated with a request) * @param c The connection to add this filter for - * @deffunc void ap_add_output_filter(const char *name, void *ctx, request_rec *r, conn_rec *c) */ AP_DECLARE(ap_filter_t *) ap_add_output_filter(const char *name, void *ctx, request_rec *r, conn_rec *c); +/** + * Remove an output filter from either the request or connection stack + * it is associated with. + * @param f The filter to remove + */ + AP_DECLARE(void) ap_remove_output_filter(ap_filter_t *f); /* The next two filters are for abstraction purposes only. They could be @@ -390,7 +375,6 @@ * new bucket brigade is returned in this location. * @param b The bucket brigade to save aside. This brigade is always empty * on return - * @deffunc apr_status_t ap_save_brigade(ap_filter_t *f, apr_bucket_brigade **save_to, apr_bucket_brigade **b) */ AP_DECLARE(apr_status_t) ap_save_brigade(ap_filter_t *f, apr_bucket_brigade **save_to, apr_bucket_brigade **b); @@ -400,15 +384,13 @@ * to flush the brigade if the brigade buffer overflows. * @param bb The brigade to flush * @param ctx The filter to pass the brigade to - * @deffunc apr_status_t ap_filter_flush(apr_bucket_brigade *bb, void *ctx) */ AP_DECLARE_NONSTD(apr_status_t) ap_filter_flush(apr_bucket_brigade *bb, void *ctx); /** - * Flush the current brigade down the filter stack - * @param f the next filter in the stack + * Flush the current brigade down the filter stack. + * @param f The current filter * @param bb The brigade to flush - * @deffunc apr_status_t ap_fflush(ap_filter_t *f, apr_bucket_brigade *bb) */ AP_DECLARE(apr_status_t) ap_fflush(ap_filter_t *f, apr_bucket_brigade *bb); @@ -418,7 +400,6 @@ * @param bb The brigade to buffer into * @param data The data to write * @param nbyte The number of bytes in the data - * @deffunc int ap_fwrite(ap_filter_t *f, apr_bucket_brigade *bb, const char *data, apr_ssize_t nbyte) */ #define ap_fwrite(f, bb, data, nbyte) \ apr_brigade_write(bb, ap_filter_flush, (f)->next, data, nbyte) @@ -428,7 +409,6 @@ * @param f the filter doing the writing * @param bb The brigade to buffer into * @param str The string to write - * @deffunc int ap_fputs(ap_filter_t *f, apr_bucket_brigade *bb, const char *str) */ #define ap_fputs(f, bb, str) \ apr_brigade_puts(bb, ap_filter_flush, (f)->next, str) @@ -438,7 +418,6 @@ * @param f the filter doing the writing * @param bb The brigade to buffer into * @param c The character to write - * @deffunc int ap_fputc(ap_filter_t *f, apr_bucket_brigade *bb, char c) */ #define ap_fputc(f, bb, c) \ apr_brigade_putc(bb, ap_filter_flush, (f)->next, c) @@ -448,7 +427,6 @@ * @param f the filter doing the writing * @param bb The brigade to buffer into * @param ... The strings to write - * @deffunc int ap_fputstrs(ap_filter_t *f, apr_bucket_brigade *bb, ...) */ AP_DECLARE_NONSTD(int) ap_fputstrs(ap_filter_t *f, apr_bucket_brigade *bb, ...); @@ -458,7 +436,6 @@ * @param bb The brigade to buffer into * @param fmt The format string * @param ... The argumets to use to fill out the format string - * @deffunc int ap_fprintf(ap_filter_t *f, apr_bucket_brigade *bb, const char *fmt, ...) */ AP_DECLARE_NONSTD(int) ap_fprintf(ap_filter_t *f, apr_bucket_brigade *bb, const char *fmt, ...) __attribute__((format(printf,3,4))); 1.56 +2 -1 apr/include/apr_errno.h Index: apr_errno.h =================================================================== RCS file: /home/cvs/apr/include/apr_errno.h,v retrieving revision 1.55 retrieving revision 1.56 diff -u -r1.55 -r1.56 --- apr_errno.h 2001/03/15 18:27:53 1.55 +++ apr_errno.h 2001/03/17 15:58:10 1.56 @@ -66,7 +66,8 @@ #endif /* __cplusplus */ /** - * @package Error Codes + * @file apr_errno.h + * @brief Error Codes */ /** 1.97 +1 -0 apr/include/apr_file_io.h Index: apr_file_io.h =================================================================== RCS file: /home/cvs/apr/include/apr_file_io.h,v retrieving revision 1.96 retrieving revision 1.97 diff -u -r1.96 -r1.97 --- apr_file_io.h 2001/02/16 04:15:43 1.96 +++ apr_file_io.h 2001/03/17 15:58:10 1.97 @@ -379,6 +379,7 @@ * APR_SET -- set the offset to offset * APR_CUR -- add the offset to the current position * APR_END -- add the offset to the current file size + * * @param offset The offset to move the pointer to. * @tip The third argument is modified to be the offset the pointer was actually moved to.