Misc fixes to doxygen comments

server/core/buffer.c

@@ -298,11 +298,13 @@ int	rval = 0;
 }
 
 /**
- * Trim bytes form the end of a GWBUF structure
+ * Trim bytes form the end of a GWBUF structure. If the
+ * buffer has n_bytes or less then it will be freed and
+ * NULL will be returned.
  *
  * @param buf		The buffer to trim
- * @param nbytes	The number of bytes to trim off
+ * @param n_bytes	The number of bytes to trim off
- * @return 		The buffer chain
+ * @return 		The buffer chain or NULL if buffer has <= n_bytes
  */
 GWBUF *
 gwbuf_trim(GWBUF *buf, unsigned int n_bytes)

server/core/dcb.c

@@ -1703,14 +1703,15 @@ int gw_write(
 /**
  * Add a callback
  *
- * Duplicate registrations are not allowed, therefore an error will be returned if
+ * Duplicate registrations are not allowed, therefore an error will be
- * the specific function, reason and userdata triple are already registered.
+ * returned if the specific function, reason and userdata triple
+ * are already registered.
  * An error will also be returned if the is insufficient memeory available to
  * create the registration.
  *
  * @param dcb		The DCB to add the callback to
  * @param reason	The callback reason
- * @param cb		The callback function to call
+ * @param callback	The callback function to call
  * @param userdata	User data to send in the call
  * @return		Non-zero (true) if the callback was added
  */
@@ -1766,7 +1767,7 @@ int		rval = 1;
  *
  * @param dcb		The DCB to add the callback to
  * @param reason	The callback reason
- * @param cb		The callback function to call
+ * @param callback	The callback function to call
  * @param userdata	User data to send in the call
  * @return		Non-zero (true) if the callback was removed
  */
@@ -1839,7 +1840,7 @@ DCB_CALLBACK	*cb, *nextcb;
 /**
  * Check the passed DCB to ensure it is in the list of allDCBS
  *
- * @param	DCB	The DCB to check
+ * @param	dcb	The DCB to check
  * @return	1 if the DCB is in the list, otherwise 0
  */
 int
@@ -1936,8 +1937,8 @@ void dcb_call_foreach (
  * Null protocol write routine used for cloned dcb's. It merely consumes
  * buffers written on the cloned DCB.
  *
- * @params dcb		The descriptor control block
+ * @param dcb		The descriptor control block
- * @params buf		The buffer beign written
+ * @param buf		The buffer being written
  * @return	Always returns a good write operation result
  */
 static int

server/core/filter.c

@@ -39,8 +39,8 @@
 
 extern int lm_enabled_logfiles_bitmask;
 
-static SPINLOCK	filter_spin = SPINLOCK_INIT;
+static SPINLOCK	filter_spin = SPINLOCK_INIT;	/**< Protects the list of all filters */
-static FILTER_DEF *allFilters = NULL;
+static FILTER_DEF *allFilters = NULL;		/**< The list of all filters */
 
 /**
  * Allocate a new filter within MaxScale
@@ -79,7 +79,7 @@ FILTER_DEF 	*filter;
 /**
  * Deallocate the specified filter
  *
- * @param server	The service to deallocate
+ * @param filter	The filter to deallocate
  * @return	Returns true if the server was freed
  */
 void
@@ -243,7 +243,7 @@ int	i;
 /**
  * Add a router option to a service
  *
- * @param service       The service to add the router option to
+ * @param filter	The filter to add the option to
  * @param option	The option string
  */
 void
@@ -273,7 +273,7 @@ int     i;
 /**
  * Add a router parameter to a service
  *
- * @param service       The service to add the router option to
+ * @param filter	The filter to add the parameter to
  * @param name		The parameter name
  * @param value		The parameter value
  */

server/core/load_utils.c

@@ -281,6 +281,7 @@ MODULES	*mod = registered;
  * @param dlhandle	The handle returned by dlopen
  * @param version	The version string returned by the module
  * @param modobj	The module object
+ * @param mod_info	The module information
  */
 static void
 register_module(const char *module, const char *type, void *dlhandle, char *version, void *modobj, MODULE_INFO *mod_info)

server/core/maxpasswd.c

@@ -34,7 +34,7 @@
  * Encrypt a password for storing in the MaxScale.cnf file
  *
  * @param argc	Argument count
- * @param arv	Argument vector
+ * @param argv	Argument vector
  */
 int
 main(int argc, char **argv)

server/core/monitor.c

@@ -208,6 +208,7 @@ MONITOR	*ptr;
  * Show a single monitor
  *
  * @param dcb		DCB for printing output
+ * @param monitor	The monitor to print information regarding
  */
 void
 monitorShow(DCB *dcb, MONITOR *monitor)
@@ -303,7 +304,7 @@ monitorSetInterval (MONITOR *mon, unsigned long interval)
  * Enable Replication Heartbeat support in monitor.
  *
  * @param mon		The monitor instance
- * @param interval	The sampling interval in milliseconds
+ * @param replication_heartbeat	The replication heartbeat
  */
 void
 monitorSetReplicationHeartbeat(MONITOR *mon, int replication_heartbeat)

server/core/server.c

@@ -148,8 +148,7 @@ server_set_unique_name(SERVER *server, char *name)
  * Find an existing server using the unique section name in
  * configuration file
  *
- * @param	servname	The Server name or address
+ * @param	name	The Server name defined in the header file
- * @param	port		The server port
  * @return	The server or NULL if not found
  */
 SERVER *

server/core/utils.c

@@ -204,7 +204,7 @@ void gw_sha1_2_str(const uint8_t *in, int in_len, const uint8_t *in2, int in2_le
 
 
 /** 
- * @node Gets errno corresponding to latest socket error 
+ * node Gets errno corresponding to latest socket error 
  *
  * Parameters:
  * @param fd - in, use

server/include/filter.h

@@ -61,7 +61,7 @@ typedef struct {
  *				filter pipline
  * 	routeQuery		Called on each query that requires
  * 				routing
- *	clientReply
+ *	clientReply		Called for each reply packet
  * 	diagnostics		Called to force the filter to print
  * 				diagnostic output
  *
@@ -88,21 +88,21 @@ typedef struct filter_object {
  */
 #define FILTER_VERSION	{1, 1, 0}
 /**
- * The definition of a filter form the configuration file.
+ * The definition of a filter from the configuration file.
  * This is basically the link between a plugin to load and the
  * optons to pass to that plugin.
  */
 typedef struct filter_def {
-	char		*name;		/*< The Filter name */
+	char		*name;		/**< The Filter name */
-	char		*module;	/*< The module to load */
+	char		*module;	/**< The module to load */
-	char		**options;	/*< The options set for this filter */
+	char		**options;	/**< The options set for this filter */
 	FILTER_PARAMETER
-			**parameters;	/*< The filter parameters */
+			**parameters;	/**< The filter parameters */
-	FILTER		filter;
+	FILTER		filter;		/**< The runtime filter */
-	FILTER_OBJECT	*obj;
+	FILTER_OBJECT	*obj;		/**< The "MODULE_OBJECT" for the filter */
-	SPINLOCK	spin;
+	SPINLOCK	spin;		/**< Spinlock to protect the filter definition */
 	struct	filter_def
-			*next;		/*< Next filter in the chain of all filters */
+			*next;		/**< Next filter in the chain of all filters */
 } FILTER_DEF;
 
 FILTER_DEF	*filter_alloc(char *, char *);

server/modules/filter/qlafilter.c

@@ -17,6 +17,9 @@
  */
 
 /**
+ * @file qlafilter.c - Quary Log All Filter
+ * @verbatim
+ *
  * QLA Filter - Query Log All. A primitive query logging filter, simply
  * used to verify the filter mechanism for downstream filters. All queries
  * that are passed through the filter will be written to file.
@@ -33,6 +36,7 @@
  * 11/06/2014	Mark Riddoch	Addition of source and match parameters
  * 19/06/2014	Mark Riddoch	Addition of user parameter
  *
+ * @endverbatim
  */
 #include <stdio.h>
 #include <fcntl.h>
@@ -154,6 +158,7 @@ GetModuleObject()
  * within MaxScale.
  * 
  * @param options	The options for this filter
+ * @param params	The array of name/value pair parameters for the filter
  *
  * @return The instance data for this new instance
  */

server/modules/filter/regexfilter.c

@@ -27,7 +27,8 @@
 extern int lm_enabled_logfiles_bitmask; 
 
 /**
- * regexfilter.c - a very simple regular expression rewrite filter.
+ * @file regexfilter.c - a very simple regular expression rewrite filter.
+ * @verbatim
  *
  * A simple regular expression query rewrite filter.
  * Two parameters should be defined in the filter configuration
@@ -39,6 +40,7 @@ extern int lm_enabled_logfiles_bitmask;
  *
  * Date		Who		Description
  * 19/06/2014	Mark Riddoch	Addition of source and user parameters
+ * @endverbatim
  */
 
 MODULE_INFO 	info = {
@@ -132,6 +134,7 @@ GetModuleObject()
  * within MaxScale.
  * 
  * @param options	The options for this filter
+ * @param params	The array of name/value pair parameters for the filter
  *
  * @return The instance data for this new instance
  */

server/modules/filter/tee.c

@@ -18,6 +18,7 @@
 
 /**
  * @file tee.c	A filter that splits the processing pipeline in two
+ * @verbatim
  *
  * Conditionally duplicate requests and send the duplicates to another service
  * within MaxScale.
@@ -41,6 +42,7 @@
  * 20/06/2014	Mark Riddoch	Initial implementation
  * 24/06/2014	Mark Riddoch	Addition of support for multi-packet queries
  *
+ * @endverbatim
  */
 #include <stdio.h>
 #include <fcntl.h>
@@ -162,6 +164,7 @@ GetModuleObject()
  * within MaxScale.
  * 
  * @param options	The options for this filter
+ * @param params	The array of name/value pair parameters for the filter
  *
  * @return The instance data for this new instance
  */

server/modules/filter/testfilter.c

@@ -21,13 +21,15 @@
 #include <modutil.h>
 
 /**
- * testfilter.c - a very simple test filter.
+ * @file testfilter.c - a very simple test filter.
+ * @verbatim
  *
  * This filter is a very simple example used to test the filter API,
  * it merely counts the number of statements that flow through the
  * filter pipeline.
  *
  * Reporting is done via the diagnostics print routine.
+ * @endverbatim
  */
 
 MODULE_INFO 	info = {
@@ -114,6 +116,7 @@ GetModuleObject()
  * within MaxScale.
  * 
  * @param options	The options for this filter
+ * @param params	The array of name/value pair parameters for the filter
  *
  * @return The instance data for this new instance
  */

server/modules/filter/topfilter.c

@@ -17,6 +17,9 @@
  */
 
 /**
+ * @file topfilter.c - Top N Longest Running Queries
+ * @verbatim
+ *
  * TOPN Filter - Query Log All. A primitive query logging filter, simply
  * used to verify the filter mechanism for downstream filters. All queries
  * that are passed through the filter will be written to file.
@@ -30,6 +33,8 @@
  *
  * Date		Who		Description
  * 18/06/2014	Mark Riddoch	Addition of source and user filters
+ *
+ * @endverbatim
  */
 #include <stdio.h>
 #include <fcntl.h>
@@ -172,6 +177,7 @@ GetModuleObject()
  * within MaxScale.
  * 
  * @param options	The options for this filter
+ * @param params	The array of name/value pair parameters for the filter
  *
  * @return The instance data for this new instance
  */