doxygen documentation

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

4 files changed, 220 insertions, 143 deletions

diff --git a/src/attr.c b/src/attr.c
index d220652..9c17f4d 100644
--- a/src/attr.c
+++ b/src/attr.c
@@ -12,22 +12,26 @@
 #include <values.h>	/* for INT_MAX */
 #include <errno.h>
 
-/*
- * Netlink Type-Length-Value (TLV) attribute:
- *
- *  |<-- 2 bytes -->|<-- 2 bytes -->|<-- variable -->|
- *  -------------------------------------------------
- *  |     length    |      type     |      value     |
- *  -------------------------------------------------
- *  |<--------- header ------------>|<-- payload --->|
+/**
+ * \defgroup attr Netlink attribute helpers
  *
+ * Netlink Type-Length-Value (TLV) attribute:
+ * \verbatim
+	|<-- 2 bytes -->|<-- 2 bytes -->|<-- variable -->|
+	-------------------------------------------------
+	|     length    |      type     |      value     |
+	-------------------------------------------------
+	|<--------- header ------------>|<-- payload --->|
+\endverbatim
  * The payload of the Netlink message contains sequences of attributes that are
  * expressed in TLV format.
+ *
+ * @{
  */
 
 /**
  * mnl_attr_get_type - get type of netlink attribute
- * @attr: pointer to netlink attribute
+ * \param attr pointer to netlink attribute
  *
  * This function returns the attribute type.
  */
@@ -38,7 +42,7 @@ uint16_t mnl_attr_get_type(const struct nlattr *attr)
 
 /**
  * mnl_attr_get_len - get length of netlink attribute
- * @attr: pointer to netlink attribute
+ * \param attr pointer to netlink attribute
  *
  * This function returns the attribute length that is the attribute header
  * plus the attribute payload.
@@ -50,7 +54,7 @@ uint16_t mnl_attr_get_len(const struct nlattr *attr)
 
 /**
  * mnl_attr_get_payload_len - get the attribute payload-value length
- * @attr: pointer to netlink attribute
+ * \param attr pointer to netlink attribute
  *
  * This function returns the attribute payload-value length.
  */
@@ -71,8 +75,8 @@ void *mnl_attr_get_payload(const struct nlattr *attr)
 
 /**
  * mnl_attr_ok - check if there is room for an attribute in a buffer
- * @nattr: attribute that we want to check if there is room for
- * @len: remaining bytes in a buffer that contains the attribute
+ * \param nattr attribute that we want to check if there is room for
+ * \param len remaining bytes in a buffer that contains the attribute
  *
  * This function is used to check that a buffer, which is supposed to contain
  * an attribute, has enough room for the attribute that it stores, ie. this
@@ -82,7 +86,7 @@ void *mnl_attr_get_payload(const struct nlattr *attr)
  * This function does not set errno in case of error since it is intended
  * for iterations. Thus, it returns 1 on success and 0 on error.
  *
- * The @len parameter may be negative in the case of malformed messages during
+ * The len parameter may be negative in the case of malformed messages during
  * attribute iteration, that is why we use a signed integer.
  */
 int mnl_attr_ok(const struct nlattr *attr, int len)
@@ -94,8 +98,8 @@ int mnl_attr_ok(const struct nlattr *attr, int len)
 
 /**
  * mnl_attr_next - get the next attribute in the payload of a netlink message
- * @attr: pointer to the current attribute
- * @len: length of the remaining bytes in the buffer (passed by reference).
+ * \param attr pointer to the current attribute
+ * \param len length of the remaining bytes in the buffer (passed by reference).
  *
  * This function returns a pointer to the next attribute after the one passed
  * as parameter. You have to use mnl_attr_ok() to ensure that the next
@@ -109,8 +113,8 @@ struct nlattr *mnl_attr_next(const struct nlattr *attr, int *len)
 
 /**
  * mnl_attr_type_valid - check if the attribute type is valid
- * @attr: pointer to attribute to be checked
- * @max: maximum attribute type
+ * \param attr pointer to attribute to be checked
+ * \param max maximum attribute type
  *
  * This function allows to check if the attribute type is higher than the
  * maximum supported type. If the attribute type is invalid, this function
@@ -184,15 +188,6 @@ static int __mnl_attr_validate(const struct nlattr *attr,
 	return 0;
 }
 
-/**
- * mnl_attr_validate - validate netlink attribute (simplified version)
- * @attr: pointer to netlink attribute that we want to validate
- * @type: data type (see enum mnl_attr_data_type)
- *
- * The validation is based on the data type. Specifically, it checks that
- * integers (u8, u16, u32 and u64) have enough room for them. This function
- * returns -1 in case of error and errno is explicitly set.
- */
 static size_t mnl_attr_data_type_len[MNL_TYPE_MAX] = {
 	[MNL_TYPE_U8]		= sizeof(uint8_t),
 	[MNL_TYPE_U16]		= sizeof(uint16_t),
@@ -200,6 +195,15 @@ static size_t mnl_attr_data_type_len[MNL_TYPE_MAX] = {
 	[MNL_TYPE_U64]		= sizeof(uint64_t),
 };
 
+/**
+ * mnl_attr_validate - validate netlink attribute (simplified version)
+ * \param attr pointer to netlink attribute that we want to validate
+ * \param type data type (see enum mnl_attr_data_type)
+ *
+ * The validation is based on the data type. Specifically, it checks that
+ * integers (u8, u16, u32 and u64) have enough room for them. This function
+ * returns -1 in case of error and errno is explicitly set.
+ */
 int mnl_attr_validate(const struct nlattr *attr, enum mnl_attr_data_type type)
 {
 	int exp_len;
@@ -214,9 +218,9 @@ int mnl_attr_validate(const struct nlattr *attr, enum mnl_attr_data_type type)
 
 /**
  * mnl_attr_validate2 - validate netlink attribute (extended version)
- * @attr: pointer to netlink attribute that we want to validate
- * @type: attribute type (see enum mnl_attr_data_type)
- * @exp_len: expected attribute data size
+ * \param attr pointer to netlink attribute that we want to validate
+ * \param type attribute type (see enum mnl_attr_data_type)
+ * \param exp_len expected attribute data size
  *
  * This function allows to perform a more accurate validation for attributes
  * whose size is variable. If the size of the attribute is not what we expect,
@@ -234,10 +238,10 @@ int mnl_attr_validate2(const struct nlattr *attr,
 
 /**
  * mnl_attr_parse - parse attributes
- * @nlh: pointer to netlink message
- * @offset: offset to start parsing from (if payload is after any extra header)
- * @cb: callback function that is called for each attribute
- * @data: pointer to data that is passed to the callback function
+ * \param nlh pointer to netlink message
+ * \param offset offset to start parsing from (if payload is after any header)
+ * \param cb callback function that is called for each attribute
+ * \param data pointer to data that is passed to the callback function
  *
  * This function allows to iterate over the sequence of attributes that compose
  * the Netlink message. You can then put the attribute in an array as it
@@ -264,9 +268,9 @@ int mnl_attr_parse(const struct nlmsghdr *nlh, unsigned int offset,
 
 /**
  * mnl_attr_parse_nested - parse attributes inside a nest
- * @nested: pointer to netlink attribute that contains a nest
- * @cb: callback function that is called for each attribute in the nest
- * @data: pointer to data passed to the callback function
+ * \param nested pointer to netlink attribute that contains a nest
+ * \param cb callback function that is called for each attribute in the nest
+ * \param data pointer to data passed to the callback function
  *
  * This function allows to iterate over the sequence of attributes that compose
  * the Netlink message. You can then put the attribute in an array as it
@@ -293,7 +297,7 @@ int mnl_attr_parse_nested(const struct nlattr *nested,
 
 /**
  * mnl_attr_get_u8 - returns 8-bit unsigned integer attribute payload
- * @attr: pointer to netlink attribute
+ * \param attr pointer to netlink attribute
  *
  * This function returns the 8-bit value of the attribute payload.
  */
@@ -304,7 +308,7 @@ uint8_t mnl_attr_get_u8(const struct nlattr *attr)
 
 /**
  * mnl_attr_get_u16 - returns 16-bit unsigned integer attribute payload
- * @attr: pointer to netlink attribute
+ * \param attr pointer to netlink attribute
  *
  * This function returns the 16-bit value of the attribute payload.
  */
@@ -315,7 +319,7 @@ uint16_t mnl_attr_get_u16(const struct nlattr *attr)
 
 /**
  * mnl_attr_get_u32 - returns 32-bit unsigned integer attribute payload
- * @attr: pointer to netlink attribute
+ * \param attr pointer to netlink attribute
  *
  * This function returns the 32-bit value of the attribute payload.
  */
@@ -326,7 +330,7 @@ uint32_t mnl_attr_get_u32(const struct nlattr *attr)
 
 /**
  * mnl_attr_get_u64 - returns 64-bit unsigned integer attribute.
- * @attr: pointer to netlink attribute
+ * \param attr pointer to netlink attribute
  *
  * This function returns the 64-bit value of the attribute payload. This
  * function is align-safe since accessing 64-bit Netlink attributes is a
@@ -341,7 +345,7 @@ uint64_t mnl_attr_get_u64(const struct nlattr *attr)
 
 /**
  * mnl_attr_get_str - returns pointer to string attribute.
- * @attr: pointer to netlink attribute
+ * \param attr pointer to netlink attribute
  *
  * This function returns the payload of string attribute value.
  */
@@ -352,10 +356,10 @@ const char *mnl_attr_get_str(const struct nlattr *attr)
 
 /**
  * mnl_attr_put - add an attribute to netlink message
- * @nlh: pointer to the netlink message
- * @type: netlink attribute type that you want to add
- * @len: netlink attribute payload length
- * @data: pointer to the data that will be stored by the new attribute
+ * \param nlh pointer to the netlink message
+ * \param type netlink attribute type that you want to add
+ * \param len netlink attribute payload length
+ * \param data pointer to the data that will be stored by the new attribute
  *
  * This function updates the length field of the Netlink message (nlmsg_len)
  * by adding the size (header + payload) of the new attribute.
@@ -374,10 +378,10 @@ void mnl_attr_put(struct nlmsghdr *nlh, uint16_t type,
 
 /**
  * mnl_attr_put_u8 - add 8-bit unsigned integer attribute to netlink message
- * @nlh: pointer to the netlink message
- * @type: netlink attribute type
- * @len: netlink attribute payload size
- * @data: 8-bit unsigned integer data that is stored by the new attribute
+ * \param nlh pointer to the netlink message
+ * \param type netlink attribute type
+ * \param len netlink attribute payload size
+ * \param data 8-bit unsigned integer data that is stored by the new attribute
  *
  * This function updates the length field of the Netlink message (nlmsg_len)
  * by adding the size (header + payload) of the new attribute.
@@ -389,9 +393,9 @@ void mnl_attr_put_u8(struct nlmsghdr *nlh, uint16_t type, uint8_t data)
 
 /**
  * mnl_attr_put_u16 - add 16-bit unsigned integer attribute to netlink message
- * @nlh: pointer to the netlink message
- * @type: netlink attribute type
- * @data: 16-bit unsigned integer data that is stored by the new attribute
+ * \param nlh pointer to the netlink message
+ * \param type netlink attribute type
+ * \param data 16-bit unsigned integer data that is stored by the new attribute
  *
  * This function updates the length field of the Netlink message (nlmsg_len)
  * by adding the size (header + payload) of the new attribute.
@@ -403,9 +407,9 @@ void mnl_attr_put_u16(struct nlmsghdr *nlh, uint16_t type, uint16_t data)
 
 /**
  * mnl_attr_put_u32 - add 32-bit unsigned integer attribute to netlink message
- * @nlh: pointer to the netlink message
- * @type: netlink attribute type
- * @data: 32-bit unsigned integer data that is stored by the new attribute
+ * \param nlh pointer to the netlink message
+ * \param type netlink attribute type
+ * \param data 32-bit unsigned integer data that is stored by the new attribute
  *
  * This function updates the length field of the Netlink message (nlmsg_len)
  * by adding the size (header + payload) of the new attribute.
@@ -417,9 +421,9 @@ void mnl_attr_put_u32(struct nlmsghdr *nlh, uint16_t type, uint32_t data)
 
 /**
  * mnl_attr_put_u64 - add 64-bit unsigned integer attribute to netlink message
- * @nlh: pointer to the netlink message
- * @type: netlink attribute type
- * @data: 64-bit unsigned integer data that is stored by the new attribute
+ * \param nlh pointer to the netlink message
+ * \param type netlink attribute type
+ * \param data 64-bit unsigned integer data that is stored by the new attribute
  *
  * This function updates the length field of the Netlink message (nlmsg_len)
  * by adding the size (header + payload) of the new attribute.
@@ -431,9 +435,9 @@ void mnl_attr_put_u64(struct nlmsghdr *nlh, uint16_t type, uint64_t data)
 
 /**
  * mnl_attr_put_str - add string attribute to netlink message
- * @nlh: pointer to the netlink message
- * @type: netlink attribute type
- * @data: pointer to string data that is stored by the new attribute
+ * \param nlh  pointer to the netlink message
+ * \param type netlink attribute type
+ * \param data pointer to string data that is stored by the new attribute
  *
  * This function updates the length field of the Netlink message (nlmsg_len)
  * by adding the size (header + payload) of the new attribute.
@@ -445,9 +449,9 @@ void mnl_attr_put_str(struct nlmsghdr *nlh, uint16_t type, const void *data)
 
 /**
  * mnl_attr_put_str_null - add string attribute to netlink message
- * @nlh: pointer to the netlink message
- * @type: netlink attribute type
- * @data: pointer to string data that is stored by the new attribute
+ * \param nlh pointer to the netlink message
+ * \param type netlink attribute type
+ * \param data pointer to string data that is stored by the new attribute
  *
  * This function is similar to mnl_attr_put_str but it includes the NULL
  * terminator at the end of the string.
@@ -462,8 +466,8 @@ void mnl_attr_put_str_null(struct nlmsghdr *nlh, uint16_t type, const void *data
 
 /**
  * mnl_attr_nest_start - start an attribute nest
- * @nlh: pointer to the netlink message
- * @type: netlink attribute type
+ * \param nlh pointer to the netlink message
+ * \param type netlink attribute type
  *
  * This function adds the attribute header that identifies the beginning of
  * an attribute nest. This function always returns a valid pointer to the
@@ -482,8 +486,8 @@ struct nlattr *mnl_attr_nest_start(struct nlmsghdr *nlh, uint16_t type)
 
 /**
  * mnl_attr_nest_end - end an attribute nest
- * @nlh: pointer to the netlink message
- * @start: pointer to the attribute nest returned by mnl_attr_nest_start()
+ * \param nlh pointer to the netlink message
+ * \param start pointer to the attribute nest returned by mnl_attr_nest_start()
  *
  * This function updates the attribute header that identifies the nest.
  */
@@ -491,3 +495,7 @@ void mnl_attr_nest_end(struct nlmsghdr *nlh, struct nlattr *start)
 {
 	start->nla_len = mnl_nlmsg_get_payload_tail(nlh) - (void *)start;
 }
+
+/**
+ * @}
+ */
diff --git a/src/callback.c b/src/callback.c
index ded22aa..e1599ff 100644
--- a/src/callback.c
+++ b/src/callback.c
@@ -45,15 +45,20 @@ static mnl_cb_t default_cb_array[NLMSG_MIN_TYPE] = {
 };
 
 /**
+ * \defgroup callback Callback helpers
+ * @{
+ */
+
+/**
  * mnl_cb_run2 - callback runqueue for netlink messages
- * @buf: buffer that contains the netlink messages
- * @numbytes: number of bytes stored in the buffer
- * @seq: sequence number that we expect to receive
- * @portid: Netlink PortID that we expect to receive
- * @cb_data: callback handler for data messages
- * @data: pointer to data that will be passed to the data callback handler
- * @cb_ctl_array: array of custom callback handlers from control messages
- * @cb_ctl_array_len: length of the array of custom control callback handlers
+ * \param buf buffer that contains the netlink messages
+ * \param numbytes number of bytes stored in the buffer
+ * \param seq sequence number that we expect to receive
+ * \param portid Netlink PortID that we expect to receive
+ * \param cb_data callback handler for data messages
+ * \param data pointer to data that will be passed to the data callback handler
+ * \param cb_ctl_array array of custom callback handlers from control messages
+ * \param cb_ctl_array_len array length of custom control callback handlers
  *
  * You can set the cb_ctl_array to NULL if you want to use the default control
  * callback handlers, in that case, the parameter cb_ctl_array_len is not
@@ -62,7 +67,7 @@ static mnl_cb_t default_cb_array[NLMSG_MIN_TYPE] = {
  * Your callback may return three possible values:
  * 	- MNL_CB_ERROR (<=-1): an error has occurred. Stop callback runqueue.
  * 	- MNL_CB_STOP (=0): stop callback runqueue.
- *	- MNL_CB_OK (>=1): no problems has occurred.
+ * 	- MNL_CB_OK (>=1): no problem has occurred.
  *
  * This function propagates the callback return value. On error, it returns
  * -1 and errno is explicitly set. If the portID is not the expected, errno
@@ -114,12 +119,12 @@ out:
 
 /**
  * mnl_cb_run - callback runqueue for netlink messages (simplified version)
- * @buf: buffer that contains the netlink messages
- * @numbytes: number of bytes stored in the buffer
- * @seq: sequence number that we expect to receive
- * @portid: Netlink PortID that we expect to receive
- * @cb_data: callback handler for data messages
- * @data: pointer to data that will be passed to the data callback handler
+ * \param buf buffer that contains the netlink messages
+ * \param numbytes number of bytes stored in the buffer
+ * \param seq sequence number that we expect to receive
+ * \param portid Netlink PortID that we expect to receive
+ * \param cb_data callback handler for data messages
+ * \param data pointer to data that will be passed to the data callback handler
  *
  * This function is like mnl_cb_run2() but it does not allow you to set
  * the control callback handlers.
@@ -127,7 +132,7 @@ out:
  * Your callback may return three possible values:
  * 	- MNL_CB_ERROR (<=-1): an error has occurred. Stop callback runqueue.
  * 	- MNL_CB_STOP (=0): stop callback runqueue.
- *	- MNL_CB_OK (>=1): no problems has occurred.
+ * 	- MNL_CB_OK (>=1): no problems has occurred.
  *
  * This function propagates the callback return value.
  */
@@ -136,3 +141,7 @@ int mnl_cb_run(const char *buf, size_t numbytes, unsigned int seq,
 {
 	return mnl_cb_run2(buf, numbytes, seq, portid, cb_data, data, NULL, 0);
 }
+
+/**
+ * @}
+ */
diff --git a/src/nlmsg.c b/src/nlmsg.c
index 9b2f457..af08671 100644
--- a/src/nlmsg.c
+++ b/src/nlmsg.c
@@ -13,34 +13,38 @@
 #include <string.h>
 #include <libmnl/libmnl.h>
 
-/*
- * Netlink message:
- *
- *  |<----------------- 4 bytes ------------------->|
- *  |<----- 2 bytes ------>|<------- 2 bytes ------>|
+/**
+ * \defgroup nlmsg Netlink message helpers
  *
- *  |-----------------------------------------------|
- *  |      Message length (including header)        |
- *  |-----------------------------------------------|
- *  |     Message type     |     Message flags      |
- *  |-----------------------------------------------|
- *  |           Message sequence number             |
- *  |-----------------------------------------------|
- *  |                 Netlink PortID                |
- *  |-----------------------------------------------|
- *  |                                               |
- *  .                   Payload                     .
- *  |_______________________________________________|
+ * Netlink message:
+ * \verbatim
+	|<----------------- 4 bytes ------------------->|
+	|<----- 2 bytes ------>|<------- 2 bytes ------>|
+	|-----------------------------------------------|
+	|      Message length (including header)        |
+	|-----------------------------------------------|
+	|     Message type     |     Message flags      |
+	|-----------------------------------------------|
+	|           Message sequence number             |
+	|-----------------------------------------------|
+	|                 Netlink PortID                |
+	|-----------------------------------------------|
+	|                                               |
+	.                   Payload                     .
+	|_______________________________________________|
+\endverbatim
  *
  * There is usually an extra header after the the Netlink header (at the
  * beginning of the payload). This extra header is specific of the Netlink
  * subsystem. After this extra header, it comes the sequence of attributes
  * that are expressed in Type-Length-Value (TLV) format.
+ *
+ * @{
  */
 
 /**
  * mnl_nlmsg_size - calculate the size of Netlink message (without alignment)
- * @len: length of the Netlink payload
+ * \param len length of the Netlink payload
  *
  * This function returns the size of a netlink message (header plus payload)
  * without alignment.
@@ -52,7 +56,7 @@ size_t mnl_nlmsg_size(size_t len)
 
 /**
  * mnl_nlmsg_aligned_size - calculate the aligned size of Netlink messages
- * @len: length of the Netlink payload
+ * \param len length of the Netlink payload
  *
  * This function returns the size of a netlink message (header plus payload)
  * with alignment.
@@ -64,7 +68,7 @@ size_t mnl_nlmsg_aligned_size(size_t len)
 
 /**
  * mnl_nlmsg_get_payload_len - get the length of the Netlink payload
- * @nlh: pointer to the header of the Netlink message
+ * \param nlh pointer to the header of the Netlink message
  *
  * This function returns the Length of the netlink payload, ie. the length
  * of the full message minus the size of the Netlink header.
@@ -76,7 +80,7 @@ size_t mnl_nlmsg_get_payload_len(const struct nlmsghdr *nlh)
 
 /**
  * mnl_nlmsg_put_header - reserve and prepare room for Netlink header
- * @buf: memory already allocated to store the Netlink header
+ * \param buf memory already allocated to store the Netlink header
  *
  * This function sets to zero the room that is required to put the Netlink
  * header in the memory buffer passed as parameter. This function also
@@ -95,8 +99,8 @@ struct nlmsghdr *mnl_nlmsg_put_header(void *buf)
 
 /**
  * mnl_nlmsg_put_extra_header - reserve and prepare room for an extra header
- * @nlh: pointer to Netlink header
- * @size: size of the extra header that we want to put
+ * \param nlh pointer to Netlink header
+ * \param size size of the extra header that we want to put
  *
  * This function sets to zero the room that is required to put the extra
  * header after the initial Netlink header. This function also increases
@@ -114,7 +118,7 @@ void *mnl_nlmsg_put_extra_header(struct nlmsghdr *nlh, size_t size)
 
 /**
  * mnl_nlmsg_get_payload - get a pointer to the payload of the netlink message
- * @nlh: pointer to a netlink header
+ * \param nlh pointer to a netlink header
  *
  * This function returns a pointer to the payload of the netlink message.
  */
@@ -125,8 +129,8 @@ void *mnl_nlmsg_get_payload(const struct nlmsghdr *nlh)
 
 /**
  * mnl_nlmsg_get_payload_offset - get a pointer to the payload of the message
- * @nlh: pointer to a netlink header
- * @offset: offset to the payload of the attributes TLV set
+ * \param nlh pointer to a netlink header
+ * \param offset offset to the payload of the attributes TLV set
  *
  * This function returns a pointer to the payload of the netlink message plus
  * a given offset.
@@ -138,8 +142,8 @@ void *mnl_nlmsg_get_payload_offset(const struct nlmsghdr *nlh, size_t offset)
 
 /**
  * mnl_nlmsg_ok - check a there is room for netlink message
- * @nlh: netlink message that we want to check
- * @len: remaining bytes in a buffer that contains the netlink message
+ * \param nlh netlink message that we want to check
+ * \param len remaining bytes in a buffer that contains the netlink message
  *
  * This function is used to check that a buffer that contains a netlink
  * message has enough room for the netlink message that it stores, ie. this
@@ -149,7 +153,7 @@ void *mnl_nlmsg_get_payload_offset(const struct nlmsghdr *nlh, size_t offset)
  * This function does not set errno in case of error since it is intended
  * for iterations. Thus, it returns 1 on success and 0 on error.
  *
- * The @len parameter may become negative in malformed messages during message
+ * The len parameter may become negative in malformed messages during message
  * iteration, that is why we use a signed integer.
  */
 int mnl_nlmsg_ok(const struct nlmsghdr *nlh, int len)
@@ -161,8 +165,8 @@ int mnl_nlmsg_ok(const struct nlmsghdr *nlh, int len)
 
 /**
  * mnl_nlmsg_next - get the next netlink message in a multipart message
- * @nlh: current netlink message that we are handling
- * @len: length of the remaining bytes in the buffer (passed by reference).
+ * \param nlh current netlink message that we are handling
+ * \param len length of the remaining bytes in the buffer (passed by reference).
  *
  * This function returns a pointer to the next netlink message that is part
  * of a multi-part netlink message. Netlink can batch several messages into
@@ -180,7 +184,7 @@ struct nlmsghdr *mnl_nlmsg_next(const struct nlmsghdr *nlh, int *len)
 
 /**
  * mnl_nlmsg_get_payload_tail - get the ending of the netlink message
- * @nlh: pointer to netlink message
+ * \param nlh pointer to netlink message
  *
  * This function returns a pointer to the netlink message tail. This is useful
  * to build a message since we continue adding attributes at the end of the
@@ -193,8 +197,8 @@ void *mnl_nlmsg_get_payload_tail(const struct nlmsghdr *nlh)
 
 /**
  * mnl_nlmsg_seq_ok - perform sequence tracking
- * @nlh: current netlink message that we are handling
- * @seq: last sequence number used to send a message
+ * \param nlh current netlink message that we are handling
+ * \param seq last sequence number used to send a message
  *
  * This functions returns 1 if the sequence tracking is fulfilled, otherwise
  * 0 is returned. We skip the tracking for netlink messages whose sequence
@@ -212,8 +216,8 @@ int mnl_nlmsg_seq_ok(const struct nlmsghdr *nlh, unsigned int seq)
 
 /**
  * mnl_nlmsg_portid_ok - perform portID origin check
- * @nlh: current netlink message that we are handling
- * @seq: netlink portid that we want to check
+ * \param nlh current netlink message that we are handling
+ * \param seq netlink portid that we want to check
  *
  * This functions return 1 if the origin is fulfilled, otherwise
  * 0 is returned.  We skip the tracking for netlink message whose portID 
@@ -231,7 +235,7 @@ int mnl_nlmsg_portid_ok(const struct nlmsghdr *nlh, unsigned int portid)
 
 /**
  * mnl_nlmsg_fprintf - print netlink message to file
- * @nlh: pointer to netlink message that we want to print
+ * \param nlh pointer to netlink message that we want to print
  *
  * This function prints the netlink header to a file. This function may be
  * useful for debugging purposes.
@@ -262,3 +266,7 @@ void mnl_nlmsg_fprintf(FILE *fd, const struct nlmsghdr *nlh)
 			isalnum(b[i+3]) ? b[i+3] : 0);
 	}
 }
+
+/**
+ * @}
+ */
diff --git a/src/socket.c b/src/socket.c
index cf8f251..de1424c 100644
--- a/src/socket.c
+++ b/src/socket.c
@@ -15,14 +15,62 @@
 #include <time.h>
 #include <errno.h>
 
+/**
+ * \mainpage
+ *
+ * libmnl is a minimalistic user-space library oriented to Netlink developers.
+ * There are a lot of common tasks in parsing, validating, constructing of
+ * both the Netlink header and TLVs that are repetitive and easy to get wrong.
+ * This library aims to provide simple helpers that allows you to avoid
+ * re-inventing the wheel in common Netlink tasks.
+ *
+ * The acronim libmnl stands for LIBrary Minimalistic NetLink.
+ *
+ * (temporary) libmnl homepage is:
+ *      http://1984.lsi.us.es/projects/libmnl/
+ *
+ * \section features Main Features
+ * - Small: the shared library requires around 30KB in a x86-based computer.
+ * - Simple: this library avoids complex abstractions that tend to hide Netlink
+ *   details. It avoids elaborated object-oriented infrastructure and complex
+ *   callback-based workflow.
+ * - Easy to use: the library simplifies the work for Netlink-wise developers.
+ *   It provides functions to make socket handling, message building,
+ *   validating, parsing, and sequence tracking, easier.
+ * - Easy to re-use: you can use this library to build your own abstraction
+ *   layer upon this library, if you want to provide another library that
+ *   hides Netlink details to your users.
+ * - Decoupling: the interdependency of the main bricks that compose this
+ *   library is reduced, ie. the library provides many helpers but the
+ *   programmer is not forced to use them.
+ *
+ * \section Dependencies
+ * You have to install the Linux kernel headers that you want to use to develop
+ * your application. Moreover, this library requires that you have some basics
+ * on Netlink.
+ *
+ * \section scm Git Tree
+ * The current development version of libmnl can be accessed at:
+ * http://1984.lsi.us.es/git/?p=libmnl/.git;a=summary
+ *
+ * \section using Using libmnl
+ * You can access several examples files under examples/ in the libmnl source
+ * code tree.
+ */
+
 struct mnl_socket {
 	int 			fd;
 	struct sockaddr_nl	addr;
 };
 
 /**
+ * \defgroup socket Netlink socket helpers
+ * @{
+ */
+
+/**
  * mnl_socket_get_fd - obtain file descriptor from netlink socket
- * @nl: netlink socket obtained via mnl_socket_open()
+ * \param nl netlink socket obtained via mnl_socket_open()
  *
  * This function returns the file descriptor of a given netlink socket.
  */
@@ -33,7 +81,7 @@ int mnl_socket_get_fd(const struct mnl_socket *nl)
 
 /**
  * mnl_socket_get_portid - obtain Netlink PortID from netlink socket
- * @nl: netlink socket obtained via mnl_socket_open()
+ * \param nl netlink socket obtained via mnl_socket_open()
  *
  * This function returns the Netlink PortID of a given netlink socket.
  * It's a common mistake to assume that this PortID equals the process ID
@@ -47,7 +95,7 @@ unsigned int mnl_socket_get_portid(const struct mnl_socket *nl)
 
 /**
  * mnl_socket_open - open a netlink socket
- * @unit: the netlink socket bus ID (see NETLINK_* constants)
+ * \param unit the netlink socket bus ID (see NETLINK_* constants)
  *
  * On error, it returns -1 and errno is appropriately set. Otherwise, it
  * returns a valid pointer to the mnl_socket structure.
@@ -71,9 +119,9 @@ struct mnl_socket *mnl_socket_open(int bus)
 
 /**
  * mnl_socket_bind - bind netlink socket
- * @nl: netlink socket obtained via mnl_socket_open()
- * @groups: the group of message you're interested in
- * @pid: the port ID you want to use (use zero for automatic selection)
+ * \param nl netlink socket obtained via mnl_socket_open()
+ * \param groups the group of message you're interested in
+ * \param pid the port ID you want to use (use zero for automatic selection)
  *
  * On error, this function returns -1 and errno is appropriately set. On
  * success, 0 is returned. You can use MNL_SOCKET_AUTOPID which is 0 for
@@ -110,9 +158,9 @@ int mnl_socket_bind(struct mnl_socket *nl, int groups, int pid)
 
 /**
  * mnl_socket_sendto - send a netlink message of a certain size
- * @nl: netlink socket obtained via mnl_socket_open()
- * @buf: buffer containing the netlink message to be sent
- * @bufsiz: number of bytes in the buffer that you want to send
+ * \param nl netlink socket obtained via mnl_socket_open()
+ * \param buf buffer containing the netlink message to be sent
+ * \param bufsiz number of bytes in the buffer that you want to send
  *
  * On error, it returns -1 and errno is appropriately set. Otherwise, it 
  * returns the number of bytes sent.
@@ -128,9 +176,9 @@ int mnl_socket_sendto(const struct mnl_socket *nl, const void *buf, size_t len)
 
 /**
  * mnl_socket_recvfrom - receive a netlink message
- * @nl: netlink socket obtained via mnl_socket_open()
- * @buf: buffer that you want to use to store the netlink message
- * @bufsiz: size of the buffer passed to store the netlink message
+ * \param nl netlink socket obtained via mnl_socket_open()
+ * \param buf buffer that you want to use to store the netlink message
+ * \param bufsiz size of the buffer passed to store the netlink message
  *
  * On error, it returns -1 and errno is appropriately set. If errno is set
  * to ENOSPC, it means that the buffer that you have passed to store the
@@ -171,7 +219,7 @@ int mnl_socket_recvfrom(const struct mnl_socket *nl, void *buf, size_t bufsiz)
 
 /**
  * mnl_socket_close - close a given netlink socket
- * @nl: netlink socket obtained via mnl_socket_open()
+ * \param nl netlink socket obtained via mnl_socket_open()
  *
  * On error, this function returns -1 and errno is appropriately set.
  * On success, it returns 0.
@@ -186,10 +234,10 @@ int mnl_socket_close(struct mnl_socket *nl)
 
 /**
  * mnl_socket_setsockopt - set Netlink socket option
- * @nl: netlink socket obtained via mnl_socket_open()
- * @type: type of Netlink socket options
- * @buf: the buffer that contains the data about this option
- * @len: the size of the buffer passed
+ * \param nl netlink socket obtained via mnl_socket_open()
+ * \param type type of Netlink socket options
+ * \param buf the buffer that contains the data about this option
+ * \param len the size of the buffer passed
  *
  * This function allows you to set some Netlink socket option. As of writing
  * this, the existing options are:
@@ -217,10 +265,10 @@ int mnl_socket_setsockopt(const struct mnl_socket *nl, int type,
 
 /**
  * mnl_socket_getsockopt - get a Netlink socket option
- * @nl: netlink socket obtained via mnl_socket_open()
- * @type: type of Netlink socket options
- * @buf: pointer to the buffer to store the value of this option
- * @len: size of the information written in the buffer
+ * \param nl netlink socket obtained via mnl_socket_open()
+ * \param type type of Netlink socket options
+ * \param buf pointer to the buffer to store the value of this option
+ * \param len size of the information written in the buffer
  *
  * On error, this function returns -1 and errno is appropriately set.
  */
@@ -229,3 +277,7 @@ int mnl_socket_getsockopt(const struct mnl_socket *nl, int type,
 {
 	return getsockopt(nl->fd, SOL_NETLINK, type, buf, len);
 }
+
+/**
+ * @}
+ */