Unify style of comments, improve function description

.gitignore

@@ -47,3 +47,7 @@ test/server.xml
 
 # patch files
 **/*.patch
+
+# doxygen
+doxygen-out
+

Doxyfile

@@ -0,0 +1,20 @@
+PROJECT_NAME           = mod_proxy_cluster
+PROJECT_NUMBER         = 2.0
+PROJECT_BRIEF          = An inteligent load-balancer for Apache httpd
+PROJECT_LOGO           =
+OUTPUT_DIRECTORY       = doxygen-out
+JAVADOC_AUTOBRIEF      = YES
+OPTIMIZE_OUTPUT_FOR_C  = YES
+EXTRACT_ALL            = YES
+INPUT                  = native README.md
+FILE_PATTERNS          = *.c \
+                         *.cc \
+                         *.cpp \
+                         *.h \
+                         *.hpp
+RECURSIVE              = YES
+EXCLUDE                = test native/build
+EXCLUDE_PATTERNS       = *CMake*
+USE_MDFILE_AS_MAINPAGE = README.md
+GENERATE_LATEX         = NO
+HTML_COLORSTYLE        = LIGHT

README.md

@@ -60,6 +60,12 @@ Tests
 
 The project contains some tests too. You can find them with a separate README in the `test` subdirectory.
 
+Doxygen documentation
+---------------------
+
+The project source files contain doxygen-style comments. To build doxygen doumentation, execute `doxygen` command.
+The output can be found in newly created `doxygen-out/` directory.
+
 License
 -------
 

native/balancers/mod_lbmethod_cluster.c

@@ -174,7 +174,7 @@ static const proxy_balancer_method cluster = {"cluster", &find_best, NULL, &rese
 
 /*
  * See if we could map the request.
- * first check is we have a balancer corresponding to the route.
+ * First check is we have a balancer corresponding to the route,
  * then search the balancer correspond to the context and host.
  */
 static int lbmethod_cluster_trans(request_rec *r)

native/common/common.c

@@ -1,7 +1,3 @@
-/*
- * Common routines
- */
-
 #include "common.h"
 
 #include "httpd.h"
@@ -21,7 +17,7 @@
 
 #include "mod_proxy_cluster.h"
 
-/* Read the virtual host table from shared memory */
+
 proxy_vhost_table *read_vhost_table(apr_pool_t *pool, struct host_storage_method *host_storage, int for_cache)
 {
     int i;
@@ -51,7 +47,6 @@ proxy_vhost_table *read_vhost_table(apr_pool_t *pool, struct host_storage_method
     return vhost_table;
 }
 
-/* Update the virtual host table from shared memory to populate a cached table */
 proxy_vhost_table *update_vhost_table_cached(proxy_vhost_table *vhost_table,
                                              const struct host_storage_method *host_storage)
 {
@@ -75,7 +70,6 @@ proxy_vhost_table *update_vhost_table_cached(proxy_vhost_table *vhost_table,
     return vhost_table;
 }
 
-/* Read the context table from shared memory */
 proxy_context_table *read_context_table(apr_pool_t *pool, const struct context_storage_method *context_storage,
                                         int for_cache)
 {
@@ -105,7 +99,6 @@ proxy_context_table *read_context_table(apr_pool_t *pool, const struct context_s
     return context_table;
 }
 
-/* Update the context table from shared memory to populate a cached table */
 proxy_context_table *update_context_table_cached(proxy_context_table *context_table,
                                                  const struct context_storage_method *context_storage)
 {
@@ -128,7 +121,6 @@ proxy_context_table *update_context_table_cached(proxy_context_table *context_ta
     return context_table;
 }
 
-/* Read the balancer table from shared memory */
 proxy_balancer_table *read_balancer_table(apr_pool_t *pool, const struct balancer_storage_method *balancer_storage,
                                           int for_cache)
 {
@@ -158,7 +150,6 @@ proxy_balancer_table *read_balancer_table(apr_pool_t *pool, const struct balance
     return balancer_table;
 }
 
-/* Update the balancer table from shared memory to populate a cached table */
 proxy_balancer_table *update_balancer_table_cached(proxy_balancer_table *balancer_table,
                                                    const struct balancer_storage_method *balancer_storage)
 {
@@ -181,7 +172,6 @@ proxy_balancer_table *update_balancer_table_cached(proxy_balancer_table *balance
     return balancer_table;
 }
 
-/* Read the node table from shared memory */
 proxy_node_table *read_node_table(apr_pool_t *pool, const struct node_storage_method *node_storage, int for_cache)
 {
     int i;
@@ -219,7 +209,6 @@ proxy_node_table *read_node_table(apr_pool_t *pool, const struct node_storage_me
     return node_table;
 }
 
-/* Update the node table from shared memory to populate a cached table*/
 proxy_node_table *update_node_table_cached(proxy_node_table *node_table, const struct node_storage_method *node_storage)
 {
     int i;
@@ -248,13 +237,6 @@ proxy_node_table *update_node_table_cached(proxy_node_table *node_table, const s
     return node_table;
 }
 
-/*
- * Read the cookie corresponding to name
- * @param r request.
- * @param name name of the cookie
- * @param in tells if cookie should read from the request or the response
- * @return the value of the cookie
- */
 char *get_cookie_param(request_rec *r, const char *name, int in)
 {
     const char *cookies;
@@ -302,12 +284,6 @@ char *get_cookie_param(request_rec *r, const char *name, int in)
     return NULL;
 }
 
-/**
- * Retrieve the parameter with the given name
- * Something like 'JSESSIONID=12345...N'
- *
- * TODO: Should use the mod_proxy_balancer one
- */
 char *get_path_param(apr_pool_t *pool, char *url, const char *name)
 {
     char *path = NULL;
@@ -334,13 +310,6 @@ char *get_path_param(apr_pool_t *pool, char *url, const char *name)
     return NULL;
 }
 
-/**
- * Check that the request has a sessionid with a route
- * @param r the request_rec.
- * @param stickyval the cookie or/and parameter name.
- * @param uri part of the URL to for the session parameter.
- * @param sticky_used the string that was used to find the route
- */
 char *cluster_get_sessionid(request_rec *r, const char *stickyval, char *uri, char **sticky_used)
 {
     char *sticky, *sticky_path;
@@ -362,13 +331,6 @@ char *cluster_get_sessionid(request_rec *r, const char *stickyval, char *uri, ch
     return route;
 }
 
-/**
- * Check that the request has a sessionid (even invalid)
- * @param r the request_rec.
- * @param nodeid the node id.
- * @param route (if received)
- * @return 1 is it finds a sessionid 0 otherwise.
- */
 int hassession_byname(request_rec *r, int nodeid, const char *route, const proxy_node_table *node_table)
 {
     proxy_balancer *balancer = NULL;
@@ -433,14 +395,6 @@ int hassession_byname(request_rec *r, int nodeid, const char *route, const proxy
     return 0;
 }
 
-/**
- * Find the best nodes for a request (check host and context (and balancer))
- * @param r the request_rec
- * @param balancer the balancer (balancer to use in that case we check it).
- * @param route from the sessionid if we have one.
- * @param use_alias compare alias with server_name
- * @return a pointer to a list of nodes.
- */
 node_context *find_node_context_host(request_rec *r, const proxy_balancer *balancer, const char *route, int use_alias,
                                      const proxy_vhost_table *vhost_table, const proxy_context_table *context_table,
                                      const proxy_node_table *node_table)
@@ -604,7 +558,9 @@ node_context *find_node_context_host(request_rec *r, const proxy_balancer *balan
     return best;
 }
 
-/* Given the route find the corresponding domain (if there is a domain) */
+/**
+ * Given the route find the corresponding domain (if there is a domain)
+ */
 static apr_status_t find_nodedomain(request_rec *r, const char **domain, char *route, const char *balancer,
                                     const proxy_node_table *node_table)
 {
@@ -640,9 +596,6 @@ static apr_status_t find_nodedomain(request_rec *r, const char **domain, char *r
     return APR_NOTFOUND;
 }
 
-/**
- * Find the balancer corresponding to the node information
- */
 const char *get_route_balancer(request_rec *r, const proxy_server_conf *conf, const proxy_vhost_table *vhost_table,
                                const proxy_context_table *context_table, const proxy_balancer_table *balancer_table,
                                const proxy_node_table *node_table, int use_alias)
@@ -720,7 +673,6 @@ const char *get_route_balancer(request_rec *r, const proxy_server_conf *conf, co
     return NULL;
 }
 
-/* Read a node from the table using its it */
 const nodeinfo_t *table_get_node(const proxy_node_table *node_table, int id)
 {
     int i;
@@ -732,7 +684,6 @@ const nodeinfo_t *table_get_node(const proxy_node_table *node_table, int id)
     return NULL;
 }
 
-/* Get a node from the table using the route */
 nodeinfo_t *table_get_node_route(proxy_node_table *node_table, char *route, int *id)
 {
     int i;
@@ -745,13 +696,6 @@ nodeinfo_t *table_get_node_route(proxy_node_table *node_table, char *route, int
     return NULL;
 }
 
-/**
- * Search the balancer that corresponds to the pair context/host
- * @param r the request_rec.
- * @vhost_table table of host virtual hosts.
- * @context_table table of contexts.
- * @return the balancer name or NULL if not found.
- */
 const char *get_context_host_balancer(request_rec *r, proxy_vhost_table *vhost_table,
                                       proxy_context_table *context_table, proxy_node_table *node_table, int use_alias)
 {
@@ -794,13 +738,6 @@ apr_status_t loc_get_id(void *mem, void *data, apr_pool_t *pool)
     return APR_SUCCESS;
 }
 
-/*
- * Return the node cotenxt Check that the worker will handle the host/context.
- * de
- * The id of the worker is used to find the (slot) node in the shared
- * memory.
- * (See get_context_host_balancer too).
- */
 const node_context *context_host_ok(request_rec *r, const proxy_balancer *balancer, int node, int use_alias,
                                     const proxy_vhost_table *vhost_table, const proxy_context_table *context_table,
                                     const proxy_node_table *node_table)