From 92a253dc8902572417f34f3e44f7ecb30aabaebc Mon Sep 17 00:00:00 2001
From: Ryan Bloom <rbb@apache.org>
Date: Mon, 31 Jul 2000 03:14:36 +0000
Subject: [PATCH] Document http_connection.h using ScanDoc

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@85959 13f79535-47bb-0310-9956-ffa450edef68
---
 include/http_connection.h | 66 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/include/http_connection.h b/include/http_connection.h
index 4bda0a95d2..cf19ea7506 100644
--- a/include/http_connection.h
+++ b/include/http_connection.h
@@ -63,18 +63,84 @@ extern "C" {
 #endif
 
 #ifdef CORE_PRIVATE
+/**
+ * Create a new connection. 
+ * @param p Pool to allocate data structures out of
+ * @param server The server to create the connection for
+ * @param inout The BUFF to use for all communication with the client
+ * @param remaddr The remote address
+ * @param addr The server's local address
+ * @param id ID of this connection; unique at any point in time.
+ */
 conn_rec *ap_new_connection(ap_pool_t *p, server_rec *server, BUFF *inout,
 			    const struct sockaddr_in *remaddr,
 			    const struct sockaddr_in *saddr, long id);
+
+/**
+ * Create a new connection using APR primitives.  This is basically a
+ * wrapper around ap_new_connection
+ * @param p Pool to allocate data structures out of.
+ * @param server The server to create the connection for
+ * @param inout The BUFF to use for all communication with the client
+ * @param conn_socket The socket we are creating the connection on.
+ * @param id ID of this connection; unique at any point in time.
+ */
 conn_rec *ap_new_apr_connection(ap_pool_t *p, server_rec *server, BUFF *inout,
                                 ap_socket_t *conn_socket, long id);
+
+/**
+ * This is the protocol module driver.  This calls all of the
+ * pre-connection and connection hooks for all protocol modules.
+ * @param c The connection on which the request is read
+ * @deffunc void ap_process_connection(conn_rec *)
+ */
 CORE_EXPORT(void) ap_process_connection(conn_rec *);
+
+/**
+ * The http protocol handler.  This makes Apache server http requests
+ * @param c The connection on which the request is read
+ * @return OK or DECLINED
+ */
 int ap_process_http_connection(conn_rec *);
+
+/**
+ * This function is responsible for the following cases:
+ * <PRE>
+ * we now proceed to read from the client until we get EOF, or until
+ * MAX_SECS_TO_LINGER has passed.  the reasons for doing this are
+ * documented in a draft:
+ *
+ * http://www.ics.uci.edu/pub/ietf/http/draft-ietf-http-connection-00.txt
+ *
+ * in a nutshell -- if we don't make this effort we risk causing
+ * TCP RST packets to be sent which can tear down a connection before
+ * all the response data has been sent to the client.
+ * </PRE>
+ * @param c The connection we are closing
+ */
 void ap_lingering_close(conn_rec *);
 #endif
 
   /* Hooks */
+/**
+ * This hook gives protocol modules an opportunity to set everything up
+ * before calling the protocol handler.  ALL pre-connection hooks are
+ * always run.
+ * @param c The connection on which the request has been received.
+ * @return OK or DECLINED
+ * @deffunc int ap_run_pre_connection(conn_rec *c)
+ */
 AP_DECLARE_HOOK(int,pre_connection,(conn_rec *))
+
+/**
+ * This hook implements different protocols.  After a connection has been
+ * established, the protocol module must read and serve the request.  This
+ * function does that for each protocol module.  The first protocol module
+ * to handle the request is the last module run.
+ * @param c The connection on which the request has been received.
+ * @return OK or DECLINED
+ * @deffunc int ap_run_process_connection(conn_rec *c)
+ */
 AP_DECLARE_HOOK(int,process_connection,(conn_rec *))
 
 #ifdef __cplusplus
-- 
2.40.0