Re: [PATCH] Improved doxygen output for http_connection.h

[Ian Holsman]

Hi Neale
what does removing the package line do?

doesn't it remove the function from their grouping on the modules page?
and the removal of the deffunc prototype... why?

Neale Ranns wrote:

hi,

I'm new to the project and have been reading the code to see how it all
works and i've been fixing the doxygen (version 1.4.4) tags as i go.

attached a patch for http_connection.h based on the version on the trunk
i checked out from subversion this morning.

If it's useful and you'd like more let me know. If someone else is
already working on this, then I'll just read.

thanks

neale



------------------------------------------------------------------------

Index: include/http_connection.h
===================================================================
--- include/http_connection.h   (revision 227319)
+++ include/http_connection.h   (working copy)
@@ -14,6 +14,11 @@
  * limitations under the License.
  */

+/**

+ * @file  http_connection.h
+ * @brief Apache connection library
+ */
+
 #ifndef APACHE_HTTP_CONNECTION_H
 #define APACHE_HTTP_CONNECTION_H

@@ -25,9 +30,6 @@

 extern "C" {
 #endif

-/**

- * @package Apache connection library
- */
 #ifdef CORE_PRIVATE
 /**
  * This is the protocol module driver.  This calls all of the
@@ -36,10 +38,13 @@

* @param csd The mechanism on which this connection is to be read. * Most times this will be a socket, but it is up to the module

  *            that accepts the request to determine the exact type.
- * @deffunc void ap_process_connection(conn_rec *c, void *csd)
  */
 AP_CORE_DECLARE(void) ap_process_connection(conn_rec *c, void *csd);

+/**

+ * Flushes all remain data in the client send buffer
+ * @param c The connection to flush
+ */
 AP_CORE_DECLARE(void) ap_flush_conn(conn_rec *c);

/**

@@ -70,10 +75,12 @@
  * if it encounters a fatal error condition.
  *
  * @param p The pool from which to allocate the connection record

+ * @param server The server record to create the connection too. * @param csd The socket that has been accepted

  * @param conn_id A unique identifier for this connection.  The ID only
  *                needs to be unique at that time, not forever.
  * @param sbh A handle to scoreboard information for this connection.
+ * @param alloc The bucket allocator to use for all bucket/brigade creations
  * @return An allocated connection record or NULL.
  */
 AP_DECLARE_HOOK(conn_rec *, create_connection,
@@ -89,7 +96,6 @@
  *            Most times this will be a socket, but it is up to the module
  *            that accepts the request to determine the exact type.
  * @return OK or DECLINED
- * @deffunc int ap_run_pre_connection(conn_rec *c, void *csd)
  */
 AP_DECLARE_HOOK(int,pre_connection,(conn_rec *c, void *csd))

@@ -100,12 +106,10 @@

  * 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 *c))

-/* End Of Connection (EOC) bucket */

-
+/** End Of Connection (EOC) bucket */
 AP_DECLARE_DATA extern const apr_bucket_type_t ap_bucket_type_eoc;

/**

@@ -119,7 +123,6 @@
  * Make the bucket passed in an End Of Connection (EOC) bucket
  * @param b The bucket to make into an EOC bucket
  * @return The new bucket, or NULL if allocation failed
- * @deffunc apr_bucket *ap_bucket_eoc_make(apr_bucket *b)
  */
 AP_DECLARE(apr_bucket *) ap_bucket_eoc_make(apr_bucket *b);

@@ -128,7 +131,6 @@

  * that the connection will be closed.
  * @param list The freelist from which this bucket should be allocated
  * @return The new bucket, or NULL if allocation failed
- * @deffunc apr_bucket *ap_bucket_eoc_create(apr_bucket_alloc_t *list)
  */
 AP_DECLARE(apr_bucket *) ap_bucket_eoc_create(apr_bucket_alloc_t *list);