src: convert documentation from kerneldoc to doxygen format

Still missing several enumerations that should be documented.
You still have to look at libnetfilter_conntrack.h to check
conntrack object attributes.

Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>

1 files changed, 136 insertions, 82 deletions

diff --git a/src/expect/api.c b/src/expect/api.c
index 7a11f53..d560178 100644
--- a/src/expect/api.c
+++ b/src/expect/api.c
@@ -13,6 +13,11 @@
 #include "internal/internal.h"
 
 /**
+ * \defgroup exp Expect object handling
+ * @{
+ */
+
+/**
  * nfexp_new - allocate a new expectation
  *
  * In case of success, this function returns a valid pointer to a memory blob,
@@ -33,7 +38,7 @@ struct nf_expect *nfexp_new(void)
 
 /**
  * nfexp_destroy - release an expectation object
- * @exp: pointer to the expectation object
+ * \param exp pointer to the expectation object
  */
 void nfexp_destroy(struct nf_expect *exp)
 {
@@ -44,7 +49,7 @@ void nfexp_destroy(struct nf_expect *exp)
 
 /**
  * nfexp_sizeof - return the size in bytes of a certain expect object
- * @exp: pointer to the expect object
+ * \param exp pointer to the expect object
  */
 size_t nfexp_sizeof(const struct nf_expect *exp)
 {
@@ -57,11 +62,11 @@ size_t nfexp_sizeof(const struct nf_expect *exp)
  *
  * Use this function if you want to allocate a expect object in the stack
  * instead of the heap. For example:
- *
+ * 
  * char buf[nfexp_maxsize()];
  * struct nf_expect *exp = (struct nf_expect *) buf;
  * memset(exp, 0, nfexp_maxsize());
- *
+ * 
  * Note: As for now this function returns the same size that nfexp_sizeof(exp)
  * does although _this could change in the future_. Therefore, do not assume
  * that nfexp_sizeof(exp) == nfexp_maxsize().
@@ -73,7 +78,7 @@ size_t nfexp_maxsize(void)
 
 /**
  * nfexp_clone - clone a expectation object
- * @exp: pointer to a valid expectation object
+ * \param exp pointer to a valid expectation object
  *
  * On error, NULL is returned and errno is appropiately set. Otherwise,
  * a valid pointer to the clone expect is returned.
@@ -92,15 +97,24 @@ struct nf_expect *nfexp_clone(const struct nf_expect *exp)
 }
 
 /**
+ * @}
+ */
+
+/**
+ * \defgroup LibrarySetup Library setup
+ * @{
+ */
+
+/**
  * nfexp_callback_register - register a callback
- * @h: library handler
- * @cb: callback used to process expect received
- * @data: data used by the callback, if any.
+ * \param h library handler
+ * \param cb callback used to process expect received
+ * \param data data used by the callback, if any.
  *
  * This function register a callback to handle the expect received, 
  * in case of error -1 is returned and errno is set appropiately, otherwise
  * 0 is returned.
- *
+ * 
  * Note that the data parameter is optional, if you do not want to pass any
  * data to your callback, then use NULL.
  */
@@ -142,7 +156,7 @@ int nfexp_callback_register(struct nfct_handle *h,
 
 /**
  * nfexp_callback_unregister - unregister a callback
- * @h: library handler
+ * \param h library handler
  */
 void nfexp_callback_unregister(struct nfct_handle *h)
 {
@@ -161,20 +175,20 @@ void nfexp_callback_unregister(struct nfct_handle *h)
 
 /**
  * nfexp_callback_register2 - register a callback
- * @h: library handler
- * @cb: callback used to process expect received
- * @data: data used by the callback, if any.
+ * \param h library handler
+ * \param cb callback used to process expect received
+ * \param data data used by the callback, if any.
  *
  * This function register a callback to handle the expect received, 
  * in case of error -1 is returned and errno is set appropiately, otherwise
  * 0 is returned.
- *
+ * 
  * Note that the data parameter is optional, if you do not want to pass any
  * data to your callback, then use NULL.
- *
+ * 
  * NOTICE: The difference with nfexp_callback_register() is that this function
  * uses the new callback interface that includes the Netlink header.
- *
+ * 
  * WARNING: Don't mix nfexp_callback_register() and nfexp_callback_register2()
  * calls, use only once at a time.
  */
@@ -217,7 +231,7 @@ int nfexp_callback_register2(struct nfct_handle *h,
 
 /**
  * nfexp_callback_unregister2 - unregister a callback
- * @h: library handler
+ * \param h library handler
  */
 void nfexp_callback_unregister2(struct nfct_handle *h)
 {
@@ -235,10 +249,19 @@ void nfexp_callback_unregister2(struct nfct_handle *h)
 }
 
 /**
+ * @}
+ */
+
+/**
+ * \defgroup exp Expect object handling
+ * @{
+ */
+
+/**
  * nfexp_set_attr - set the value of a certain expect attribute
- * @exp: pointer to a valid expect 
- * @type: attribute type
- * @value: pointer to the attribute value
+ * \param exp pointer to a valid expect
+ * \param type attribute type
+ * \param value pointer to the attribute value
  *
  * Note that certain attributes are unsettable:
  * 	- ATTR_EXP_USE
@@ -264,9 +287,9 @@ void nfexp_set_attr(struct nf_expect *exp,
 
 /**
  * nfexp_set_attr_u8 - set the value of a certain expect attribute
- * @exp: pointer to a valid expect 
- * @type: attribute type
- * @value: unsigned 8 bits attribute value
+ * \param exp pointer to a valid expect
+ * \param type attribute type
+ * \param value unsigned 8 bits attribute value
  */
 void nfexp_set_attr_u8(struct nf_expect *exp,
 		       const enum nf_expect_attr type, 
@@ -277,9 +300,9 @@ void nfexp_set_attr_u8(struct nf_expect *exp,
 
 /**
  * nfexp_set_attr_u16 - set the value of a certain expect attribute
- * @exp: pointer to a valid expect 
- * @type: attribute type
- * @value: unsigned 16 bits attribute value
+ * \param exp pointer to a valid expect
+ * \param type attribute type
+ * \param value unsigned 16 bits attribute value
  */
 void nfexp_set_attr_u16(struct nf_expect *exp,
 			const enum nf_expect_attr type, 
@@ -290,9 +313,9 @@ void nfexp_set_attr_u16(struct nf_expect *exp,
 
 /**
  * nfexp_set_attr_u32 - set the value of a certain expect attribute
- * @exp: pointer to a valid expect 
- * @type: attribute type
- * @value: unsigned 32 bits attribute value
+ * \param exp pointer to a valid expect
+ * \param type attribute type
+ * \param value unsigned 32 bits attribute value
  */
 void nfexp_set_attr_u32(struct nf_expect *exp,
 			const enum nf_expect_attr type, 
@@ -303,8 +326,8 @@ void nfexp_set_attr_u32(struct nf_expect *exp,
 
 /**
  * nfexp_get_attr - get an expect attribute
- * exp: pointer to a valid expect
- * @type: attribute type
+ * \param exp pointer to a valid expect
+ * \param type attribute type
  *
  * In case of success a valid pointer to the attribute requested is returned,
  * on error NULL is returned and errno is set appropiately.
@@ -329,8 +352,8 @@ const void *nfexp_get_attr(const struct nf_expect *exp,
 
 /**
  * nfexp_get_attr_u8 - get attribute of unsigned 8-bits long
- * @exp: pointer to a valid expectation
- * @type: attribute type
+ * \param exp pointer to a valid expectation
+ * \param type attribute type
  *
  * Returns the value of the requested attribute, if the attribute is not 
  * set, 0 is returned. In order to check if the attribute is set or not,
@@ -345,8 +368,8 @@ u_int8_t nfexp_get_attr_u8(const struct nf_expect *exp,
 
 /**
  * nfexp_get_attr_u16 - get attribute of unsigned 16-bits long
- * @exp: pointer to a valid expectation
- * @type: attribute type
+ * \param exp pointer to a valid expectation
+ * \param type attribute type
  *
  * Returns the value of the requested attribute, if the attribute is not 
  * set, 0 is returned. In order to check if the attribute is set or not,
@@ -361,8 +384,8 @@ u_int16_t nfexp_get_attr_u16(const struct nf_expect *exp,
 
 /**
  * nfexp_get_attr_u32 - get attribute of unsigned 32-bits long
- * @exp: pointer to a valid expectation
- * @type: attribute type
+ * \param exp pointer to a valid expectation
+ * \param type attribute type
  *
  * Returns the value of the requested attribute, if the attribute is not 
  * set, 0 is returned. In order to check if the attribute is set or not,
@@ -377,8 +400,8 @@ u_int32_t nfexp_get_attr_u32(const struct nf_expect *exp,
 
 /**
  * nfexp_attr_is_set - check if a certain attribute is set
- * @exp: pointer to a valid expectation object
- * @type: attribute type
+ * \param exp pointer to a valid expectation object
+ * \param type attribute type
  *
  * On error, -1 is returned and errno is set appropiately, otherwise
  * the value of the attribute is returned.
@@ -397,9 +420,9 @@ int nfexp_attr_is_set(const struct nf_expect *exp,
 
 /**
  * nfexp_attr_unset - unset a certain attribute
- * @type: attribute type
- * @exp: pointer to a valid expectation object
- * 
+ * \param type attribute type
+ * \param exp pointer to a valid expectation object
+ *
  * On error, -1 is returned and errno is set appropiately, otherwise
  * 0 is returned.
  */
@@ -418,18 +441,27 @@ int nfexp_attr_unset(struct nf_expect *exp,
 }
 
 /**
+ * @}
+ */
+
+/**
+ * \defgroup nl Low level object to Netlink message
+ * @{
+ */
+
+/**
  * nfexp_build_expect - build a netlink message from a conntrack object
- * @ssh: nfnetlink subsystem handler
- * @req: buffer used to build the netlink message
- * @size: size of the buffer passed
- * @type: netlink message type
- * @flags: netlink flags
- * @exp: pointer to a conntrack object
+ * \param ssh nfnetlink subsystem handler
+ * \param req buffer used to build the netlink message
+ * \param size size of the buffer passed
+ * \param type netlink message type
+ * \param flags netlink flags
+ * \param exp pointer to a conntrack object
  *
  * This is a low level function for those that require to be close to
  * netlink details via libnfnetlink. If you do want to obviate the netlink
  * details then we suggest you to use nfexp_query.
- *
+ * 
  * On error, -1 is returned and errno is appropiately set.
  * On success, 0 is returned.
  */
@@ -449,31 +481,31 @@ static int nfexp_build_expect(struct nfnl_subsys_handle *ssh,
 
 /**
  * nfexp_build_query - build a query in netlink message format for ctnetlink
- * @ssh: nfnetlink subsystem handler
- * @qt: query type
- * @data: data required to build the query
- * @req: buffer to build the netlink message
- * @size: size of the buffer passed
+ * \param ssh nfnetlink subsystem handler
+ * \param qt query type
+ * \param data data required to build the query
+ * \param req buffer to build the netlink message
+ * \param size size of the buffer passed
  *
  * This is a low level function, use it if you want to require to work
  * with netlink details via libnfnetlink, otherwise we suggest you to
  * use nfexp_query.
- *
+ * 
  * The pointer to data can be a conntrack object or the protocol family
  * depending on the request.
- *
+ * 
  * For query types:
  * 	NFEXP_Q_CREATE
  * 	NFEXP_Q_DESTROY
- *
+ * 
  * Pass a valid pointer to an expectation object.
- *
+ * 
  * For query types:
  * 	NFEXP_Q_FLUSH
  * 	NFEXP_Q_DUMP
- *
+ * 
  * Pass a valid pointer to the protocol family (u_int8_t)
- *
+ * 
  * On success, 0 is returned. On error, -1 is returned and errno is set
  * appropiately.
  */
@@ -517,24 +549,24 @@ static int nfexp_build_query(struct nfnl_subsys_handle *ssh,
 
 /**
  * nfexp_parse_expect - translate a netlink message to a conntrack object
- * @type: do the translation iif the message type is of a certain type
- * @nlh: pointer to the netlink message
- * @exp: pointer to the conntrack object
+ * \param type do the translation iif the message type is of a certain type
+ * \param nlh pointer to the netlink message
+ * \param exp pointer to the conntrack object
  *
  * This is a low level function, use it in case that you require to work
  * with netlink details via libnfnetlink. Otherwise, we suggest you to
  * use the high level API.
- *
+ * 
  * The message types are:
- *
+ * 
  * NFEXP_T_NEW: parse messages with new conntracks
  * NFEXP_T_UPDATE: parse messages with conntrack updates
  * NFEXP_T_DESTROY: parse messages with conntrack destroy 
  * NFEXP_T_ALL: all message types
- *
+ * 
  * The message type is a flag, therefore the can be combined, ie.
  * NFEXP_T_NEW | NFEXP_T_DESTROY to parse only new and destroy messages
- *
+ * 
  * On error, NFEXP_T_ERROR is returned and errno is set appropiately. If 
  * the message received is not of the requested type then 0 is returned, 
  * otherwise this function returns the message type parsed.
@@ -569,10 +601,19 @@ static int nfexp_parse_expect(enum nf_conntrack_msg_type type,
 }
 
 /**
+ * @}
+ */
+
+/**
+ * \defgroup cmd Send commands to kernel-space and receive replies
+ * @{
+ */
+
+/**
  * nfexp_query - send a query to ctnetlink
- * @h: library handler
- * @qt: query type
- * @data: data required to send the query
+ * \param h library handler
+ * \param qt query type
+ * \param data data required to send the query
  *
  * On error, -1 is returned and errno is explicitely set. On success, 0
  * is returned.
@@ -598,7 +639,7 @@ int nfexp_query(struct nfct_handle *h,
 
 /**
  * nfexp_catch - catch events
- * @h: library handler
+ * \param h library handler
  *
  * On error, -1 is returned and errno is set appropiately. On success, 
  * a value greater or equal to 0 is returned indicating the callback
@@ -612,27 +653,36 @@ int nfexp_catch(struct nfct_handle *h)
 }
 
 /**
+ * @}
+ */
+
+/**
+ * \defgroup exp Expect object handling
+ * @{
+ */
+
+/**
  * nfexp_snprintf - print a conntrack object to a buffer
- * @buf: buffer used to build the printable conntrack
- * @size: size of the buffer
- * @exp: pointer to a valid expectation object
- * @message_type: print message type (NFEXP_T_UNKNOWN, NFEXP_T_NEW,...)
- * @output_type: print type (NFEXP_O_DEFAULT, NFEXP_O_XML, ...)
- * @flags: extra flags for the output type (NFEXP_OF_LAYER3)
- *
- * If you are listening to events, probably you want to display the message 
+ * \param buf buffer used to build the printable conntrack
+ * \param size size of the buffer
+ * \param exp pointer to a valid expectation object
+ * \param message_type print message type (NFEXP_T_UNKNOWN, NFEXP_T_NEW,...)
+ * \param output_type print type (NFEXP_O_DEFAULT, NFEXP_O_XML, ...)
+ * \param flags extra flags for the output type (NFEXP_OF_LAYER3)
+ *
+  * If you are listening to events, probably you want to display the message 
  * type as well. In that case, set the message type parameter to any of the
  * known existing types, ie. NFEXP_T_NEW, NFEXP_T_UPDATE, NFEXP_T_DESTROY.
  * If you pass NFEXP_T_UNKNOWN, the message type will not be output. 
- *
+ * 
  * Currently, the output available are:
  * 	- NFEXP_O_DEFAULT: default /proc-like output
  * 	- NFEXP_O_XML: XML output
- *
+ * 
  * The output flags are:
  * 	- NFEXP_O_LAYER: include layer 3 information in the output, this is
  * 			*only* required by NFEXP_O_DEFAULT.
- *
+ * 
  * On error, -1 is returned and errno is set appropiately. Otherwise,
  * 0 is returned.
  */
@@ -649,3 +699,7 @@ int nfexp_snprintf(char *buf,
 
 	return __snprintf_expect(buf, size, exp, msg_type, out_type, flags);
 }
+
+/**
+ * @}
+ */