Fixed formatting in dnslib.

- mostly doxygen comments
- some alignment

closes #159

src/dnslib/consts.h

+/*!
+ * \file consts.h
+ *
+ * \author Lubos Slovak <lubos.slovak@nic.cz>
+ *
+ * \brief Contains some DNS-related constants.
+ *
+ * \addtogroup dnslib
+ * @{
+ */
+
 #ifndef _CUTEDNS_DNSLIB_CONSTS_H_
 #define _CUTEDNS_DNSLIB_CONSTS_H_
 
@@ -46,3 +57,5 @@ const unsigned int DNSLIB_MAX_DNAME_LENGTH = 255;
 const unsigned int DNSLIB_MAX_DNAME_LABELS = 127;	// 1-char labels
 
 #endif /* _CUTEDNS_DNSLIB_CONSTS_H_ */
+
+/*! @} */

src/dnslib/descriptor.h

@@ -21,7 +21,7 @@ enum mxrdtln {
 	DNSLIB_MAX_RDATA_ITEMS = 64,
 	DNSLIB_MAX_RDATA_ITEM_SIZE = 255,
 	DNSLIB_MAX_RDATA_WIRE_SIZE =
-	DNSLIB_MAX_RDATA_ITEMS * DNSLIB_MAX_RDATA_ITEM_SIZE
+	  DNSLIB_MAX_RDATA_ITEMS * DNSLIB_MAX_RDATA_ITEM_SIZE
 };
 //#define MAXRDATALEN 64
 

src/dnslib/dname.c

@@ -3,16 +3,17 @@
 #include <assert.h>
 #include <string.h>
 #include <ctype.h>	// tolower()
+
+#include "dname.h"
 #include "common.h"
 #include "consts.h"
-#include "dname.h"
 
 /*----------------------------------------------------------------------------*/
 /* Non-API functions                                                          */
 /*----------------------------------------------------------------------------*/
 /*!
- *	\brief Returns the size of the wire format of domain name which has
- *         \a str_size characters in presentation format.
+ * \brief Returns the size of the wire format of domain name which has
+ *        \a str_size characters in presentation format.
  */
 static inline uint dnslib_dname_wire_size(uint str_size)
 {
@@ -23,14 +24,14 @@ static inline uint dnslib_dname_wire_size(uint str_size)
 /*!
  * \brief Converts domain name from string representation to wire format.
  *
+ * This function also allocates the space for the wire format.
+ *
  * \param name Domain name in string representation (presentation format).
  * \param size Size of the given domain name in characters (not counting the
  *             terminating 0 character.
  * \param wire [in/out] Pointer to position where the wire format of the domain
  *             name will be stored.
  *
- * This function also allocates the space for the wire format.
- *
  * \return Size of the wire format of the domain name in octets. If 0, no
  *         space has been allocated.
  *
@@ -117,7 +118,7 @@ dnslib_dname_t *dnslib_dname_new()
 /*----------------------------------------------------------------------------*/
 
 dnslib_dname_t *dnslib_dname_new_from_str(char *name, uint size,
-                struct dnslib_node *node)
+                                          struct dnslib_node *node)
 {
 	if (name == NULL || size == 0) {
 		return NULL;
@@ -133,8 +134,7 @@ dnslib_dname_t *dnslib_dname_new_from_str(char *name, uint size,
 
 	dname->size = dnslib_dname_str_to_wire(name, size, &dname->name);
 	if (dname->size <= 0) {
-		log_warning("Could not parse domain name "
-			    "from string: '%.*s'\n",
+		log_warning("Could not parse domain name from string: '%.*s'\n",
 		            size, name);
 	}
 	assert(dname->name != NULL);
@@ -147,7 +147,7 @@ dnslib_dname_t *dnslib_dname_new_from_str(char *name, uint size,
 /*----------------------------------------------------------------------------*/
 
 dnslib_dname_t *dnslib_dname_new_from_wire(uint8_t *name, uint size,
-                struct dnslib_node *node)
+                                           struct dnslib_node *node)
 {
 	if (name == NULL && size != 0) {
 		debug_dnslib_dname("No name given!\n");

src/dnslib/dname.h

@@ -12,6 +12,7 @@
 #define _CUTEDNS_DNSLIB_DNAME_H_
 
 #include <stdint.h>
+
 #include "common.h"
 
 struct dnslib_node;
@@ -42,6 +43,7 @@ typedef struct dnslib_dname dnslib_dname_t;
  * \brief Creates empty dname structure (no name, no owner node).
  *
  * \return Newly allocated and initialized dname structure.
+ *
  * \todo Possibly useless.
  */
 dnslib_dname_t *dnslib_dname_new();
@@ -50,14 +52,14 @@ dnslib_dname_t *dnslib_dname_new();
  * \brief Creates a dname structure from domain name given in presentation
  *        format.
  *
+ * The resulting domain name is stored in wire format and ALWAYS ENDS WITH 0,
+ * e.g. is a FQDN even if the given domain name was not.
+ *
  * \param name Domain name in presentation format (labels separated by dots).
  * \param size Size of the domain name (count of characters with all dots).
  * \param node Zone node the domain name belongs to. Set to NULL if not
  *             applicable.
  *
- * The resulting domain name is stored in wire format and ALWAYS ENDS WITH 0,
- * e.g. is a FQDN even if the given domain name was not.
- *
  * \return Newly allocated and initialized dname structure representing the
  *         given domain name.
  *
@@ -69,6 +71,10 @@ dnslib_dname_t *dnslib_dname_new_from_str(char *name, uint size,
 /*!
  * \brief Creates a dname structure from domain name given in wire format.
  *
+ * \note The name is copied into the structure.
+ * \note If the given name is not a FQDN, the result will be neither. This
+ *       does not correspond to the behaviour of dnslib_dname_new_from_str().
+ *
  * \param name Domain name in wire format.
  * \param size Size of the domain name in octets.
  * \param node Zone node the domain name belongs to. Set to NULL if not
@@ -77,9 +83,6 @@ dnslib_dname_t *dnslib_dname_new_from_str(char *name, uint size,
  * \return Newly allocated and initialized dname structure representing the
  *         given domain name.
  *
- * \note The name is copied into the structure.
- * \note If the given name is not a FQDN, the result will be neither. This
- *       does not correspond to the behaviour of dnslib_dname_new_from_str().
  * \todo Address the FQDN issue.
  * \todo This function does not check if the given data is in correct wir
  *       format at all. It thus creates a invalid domain name, which if passed
@@ -93,11 +96,12 @@ dnslib_dname_t *dnslib_dname_new_from_wire(uint8_t *name, uint size,
 /*!
  * \brief Converts the given domain name to string representation.
  *
+ * \note Allocates new memory, remember to free it.
+ *
  * \param dname Domain name to be converted.
  *
  * \return 0-terminated string representing the given domain name in
  *         presentation format.
- * \note Allocates new memory, remember to free it.
  */
 char *dnslib_dname_to_str(const dnslib_dname_t *dname);
 
@@ -131,13 +135,13 @@ const struct dnslib_node *dnslib_dname_node(const dnslib_dname_t *dname);
 /*!
  * \brief Destroys the given domain name.
  *
- * \param dname Domain name to be destroyed.
- *
  * Frees also the data within the struct. This is somewhat different behaviour
  * than that of RDATA and RRSet structures which do not deallocate their
  * contents.
  *
  * Sets the given pointer to NULL.
+ *
+ * \param dname Domain name to be destroyed.
  */
 void dnslib_dname_free(dnslib_dname_t **dname);
 

src/dnslib/node.c

 #include <malloc.h>
 
-#include "common.h"
 #include "node.h"
+#include "common.h"
 #include "rrset.h"
 
 //void print_node(void *key, void *val)
 //{
-//    dnslib_rrset_t *rrset = (dnslib_node_t*) val;
-//    int *key_i = (int*)key;
-//    printf("key %d\n", key_i);
-//    printf("%d\n", rrset->type);
+//	dnslib_rrset_t *rrset = (dnslib_node_t*) val;
+//	int *key_i = (int*)key;
+//	printf("key %d\n", key_i);
+//	printf("%d\n", rrset->type);
 //}
 
-int compare_rrset_types(void *key1, void *key2)
+static int compare_rrset_types(void *key1, void *key2)
 {
 	return (*((uint16_t *)key1) == *((uint16_t *)key2) ?
 	        0 : *((uint16_t *)key1) < *((uint16_t *)key2) ? -1 : 1);
@@ -44,7 +44,7 @@ int dnslib_node_add_rrset(dnslib_node_t *node, dnslib_rrset_t *rrset)
 }
 
 const dnslib_rrset_t *dnslib_node_get_rrset(const dnslib_node_t *node,
-                uint16_t type)
+                                            uint16_t type)
 {
 	return (dnslib_rrset_t *)skip_find(node->rrsets, (void *)&type);
 }

src/dnslib/node.h

@@ -30,6 +30,7 @@
 struct dnslib_node {
 	dnslib_dname_t *owner; /*!< Domain name being the owner of this node. */
 	struct dnslib_node *parent; /*!< Parent node in the name hierarchy. */
+
 	/*! \brief Type-ordered list of RRSets belonging to this node. */
 	skip_list *rrsets;
 
@@ -86,9 +87,9 @@ const dnslib_node_t *dnslib_node_get_parent(const dnslib_node_t *node);
 /*!
  * \brief Destroys the node structure.
  *
- * \param node Node to be destroyed.
+ * Also sets the given pointer to NULL.
  *
- * Sets the given pointer to NULL.
+ * \param node Node to be destroyed.
  */
 void dnslib_node_free(dnslib_node_t **node);
 

src/dnslib/rdata.c

@@ -2,8 +2,9 @@
 #include <stdlib.h>
 #include <assert.h>
 #include <string.h>
-#include "common.h"
+
 #include "rdata.h"
+#include "common.h"
 #include "descriptor.h"
 #include "dname.h"
 
@@ -55,7 +56,7 @@ static int dnslib_rdata_compare_binary(const uint8_t *d1, const uint8_t *d2,
 dnslib_rdata_t *dnslib_rdata_new()
 {
 	dnslib_rdata_t *rdata =
-	(dnslib_rdata_t *)malloc(sizeof(dnslib_rdata_t));
+		(dnslib_rdata_t *)malloc(sizeof(dnslib_rdata_t));
 	if (rdata == NULL) {
 		ERR_ALLOC_FAILED;
 		return NULL;
@@ -94,7 +95,7 @@ int dnslib_rdata_set_items(dnslib_rdata_t *rdata,
 
 	assert(rdata->count == 0);
 	if ((rdata->items = (dnslib_rdata_item_t *)malloc(
-	                    count * sizeof(dnslib_rdata_item_t))) == NULL) {
+	                     count * sizeof(dnslib_rdata_item_t))) == NULL) {
 		ERR_ALLOC_FAILED;
 		return -2;
 	}
@@ -108,7 +109,7 @@ int dnslib_rdata_set_items(dnslib_rdata_t *rdata,
 /*----------------------------------------------------------------------------*/
 
 const dnslib_rdata_item_t *dnslib_rdata_get_item(const dnslib_rdata_t *rdata,
-                uint pos)
+                                                 uint pos)
 {
 	if (pos >= rdata->count) {
 		return NULL;
@@ -162,8 +163,8 @@ uint dnslib_rdata_wire_size(const dnslib_rdata_t *rdata,
 			size += 16;
 			break;
 		case DNSLIB_RDATA_WF_BINARY:
-		case DNSLIB_RDATA_WF_APL:		// saved as binary
-		case DNSLIB_RDATA_WF_IPSECGATEWAY:	// saved as binary
+		case DNSLIB_RDATA_WF_APL:            // saved as binary
+		case DNSLIB_RDATA_WF_IPSECGATEWAY:   // saved as binary
 			size += rdata->items[i].raw_data[0];
 			break;
 		case DNSLIB_RDATA_WF_TEXT:
@@ -222,8 +223,8 @@ int dnslib_rdata_to_wire(const dnslib_rdata_t *rdata, const uint8_t *format,
 			size = rdata->items[i].raw_data[0] + 1;
 			break;
 		case DNSLIB_RDATA_WF_BINARY:
-		case DNSLIB_RDATA_WF_APL:		// saved as binary
-		case DNSLIB_RDATA_WF_IPSECGATEWAY:	// saved as binary
+		case DNSLIB_RDATA_WF_APL:            // saved as binary
+		case DNSLIB_RDATA_WF_IPSECGATEWAY:   // saved as binary
 			// size stored in the first byte, first
 			// byte must not be copied
 			size = rdata->items[i].raw_data[0];
@@ -299,8 +300,8 @@ int dnslib_rdata_compare(const dnslib_rdata_t *r1, const dnslib_rdata_t *r2,
 			size2 = (int)item1->raw_data[0] + 1;
 			break;
 		case DNSLIB_RDATA_WF_BINARY:
-		case DNSLIB_RDATA_WF_APL:		// saved as binary
-		case DNSLIB_RDATA_WF_IPSECGATEWAY:	// saved as binary
+		case DNSLIB_RDATA_WF_APL:            // saved as binary
+		case DNSLIB_RDATA_WF_IPSECGATEWAY:   // saved as binary
 			size1 = -1;
 			size2 = -1;
 			break;

src/dnslib/rdata.h

 /*!
  * \file rdata.h
+ *
  * \author Lubos Slovak <lubos.slovak@nic.cz>
  *
  * \brief Structures representing RDATA and its items and API for manipulating
@@ -13,6 +14,7 @@
 #define _CUTEDNS_DNSLIB_RDATA_H_
 
 #include <stdint.h>
+
 #include "dname.h"
 #include "common.h"
 
@@ -56,14 +58,14 @@ typedef union dnslib_rdata_item dnslib_rdata_item_t;
  * of items. In such cases, the last item in the array will be set tu NULL
  * to distinguish the actual count of items.
  *
- * \todo Find out whether NULL is appropriate value. If it is a possible
- *       value for some of the items, we must find some other way to deal with
- *       this.
- *
  * This structure does not hold information about the RDATA items, such as
  * what type is which item or how long are they. This information should be
  * stored elsewhere (in descriptors) as it is RR-specific and given for each
  * RR type.
+ *
+ * \todo Find out whether NULL is appropriate value. If it is a possible
+ *       value for some of the items, we must find some other way to deal with
+ *       this.
  */
 struct dnslib_rdata {
 	dnslib_rdata_item_t *items; /*!< RDATA items comprising this RDATA. */
@@ -100,15 +102,15 @@ int dnslib_rdata_set_item(dnslib_rdata_t *rdata, uint pos,
 /*!
  * \brief Sets all RDATA items within the given RDATA structure.
  *
- * \param rdata RDATA structure to store the items in.
- * \param items An array of RDATA items to be stored in this RDATA structure.
- * \param count Count of RDATA items to be stored.
- *
  * \a rdata must be empty so far (\a rdata->count == 0). The necessary space
  * is allocated.
  *
  * This function copies the array of RDATA items from \a items to \a rdata.
  *
+ * \param rdata RDATA structure to store the items in.
+ * \param items An array of RDATA items to be stored in this RDATA structure.
+ * \param count Count of RDATA items to be stored.
+ *
  * \retval 0 if successful.
  * \retval 1 if \a rdata is NULL or \a items is NULL or \a count is 0.
  * \retval -1 if \a rdata was not empty.
@@ -120,14 +122,14 @@ int dnslib_rdata_set_items(dnslib_rdata_t *rdata,
 /*!
  * \brief Returns the RDATA item on position \a pos.
  *
+ * \note Although returning union would be OK (no overhead), we need to be able
+ *       to distinguish errors (in this case by returning NULL).
+ *
  * \param rdata RDATA structure to get the item from.
  * \param pos Position of the item to retrieve.
  *
  * \return The RDATA item on position \a pos, or NULL if such position does not
  *         exist within the given RDATA structure.
- *
- * \note Although returning union would be OK (no overhead), we need to be able
- *       to distinguish errors (in this case by returning NULL).
  */
 const dnslib_rdata_item_t *dnslib_rdata_get_item(const dnslib_rdata_t *rdata,
                 uint pos);
@@ -153,8 +155,8 @@ uint dnslib_rdata_wire_size(const dnslib_rdata_t *rdata,
  * \param buffer Place to put the wire format into.
  * \param buf_size Size of the buffer.
  *
- * \return 0 on success.
- * \return <> 0 otherwise.
+ * \retval 0 on success.
+ * \retval <> 0 otherwise.
  *
  * \todo Shouldn't we keep the size of the data always in the item? It would
  *       make the converting quicker.
@@ -165,31 +167,32 @@ int dnslib_rdata_to_wire(const dnslib_rdata_t *rdata, const uint8_t *format,
 /*!
  * \brief Destroys the RDATA structure.
  *
- * \param rdata RDATA structure to be destroyed.
- *
  * Contents of RDATA items are not deallocated, as it is not clear whether the
  * particular item is a domain name (which should not be deallocated here) or
  * raw data (which could be). But this is actually higher-level logic, so maybe
  * a parameter to decide whether to free the items or not would be better.
  *
  * Sets the given pointer to NULL.
+ *
+ * \param rdata RDATA structure to be destroyed.
  */
 void dnslib_rdata_free(dnslib_rdata_t **rdata);
 
 /*!
  * \brief Compares two RDATAs of the same type.
  *
+ * \note This function will probably be useless, no ordering will be needed
+ *       for our purposes.
+ *
  * \param r1 First RDATA.
  * \param r2 Second RDATA.
  * \param format Descriptor of the RDATA format.
  *
- * \return 0 if RDATAs are equal.
+ * \retval 0 if RDATAs are equal.
  * \retval -1 if \a r1 goes before \a r2 in canonical order.
  * \retval 1 if \a r1 goes after \a r2 in canonical order.
  *
  * \todo Domain names in certain types should be converted to lowercase.
- * \note This function will probably be useless, no ordering will be needed
- *       for our purposes.
  */
 int dnslib_rdata_compare(const dnslib_rdata_t *r1, const dnslib_rdata_t *r2,
                          const uint8_t *format);

src/dnslib/rrset.h

@@ -13,6 +13,7 @@
 #define _CUTEDNS_DNSLIB_RRSET_H_
 
 #include <stdint.h>
+
 #include "dname.h"
 #include "rdata.h"
 #include "common.h"
@@ -64,13 +65,13 @@ typedef struct dnslib_rrset dnslib_rrset_t;
 /*!
  * \brief Creates a new RRSet with the given properties.
  *
+ * The created RRSet contains no RDATAs (i.e. is actually empty).
+ *
  * \param owner OWNER of the RRSet.
  * \param type TYPE of the RRSet.
  * \param rclass CLASS of the RRSet.
  * \param ttl TTL of the RRset.
  *
- * The created RRSet contains no RDATAs (i.e. is actually empty).
- *
  * \return New RRSet structure with the given OWNER, TYPE, CLASS and TTL or NULL
  *         if an error occured.
  */
@@ -139,15 +140,15 @@ uint32_t dnslib_rrset_ttl(const dnslib_rrset_t *rrset);
 /*!
  * \brief Returns the first RDATA in the RRSet.
  *
- * \param rrset RRSet to get the RDATA from.
- *
  * RDATAs in a RRSet are stored in a ordered cyclic list.
  *
- * \return First RDATA in the given RRSet.
- *
  * \note If later a round-robin rotation of RRSets is employed, the RDATA
  *       returned by this function may not be the first RDATA in canonical
  *       order.
+ *
+ * \param rrset RRSet to get the RDATA from.
+ *
+ * \return First RDATA in the given RRSet.
  */
 const dnslib_rdata_t *dnslib_rrset_rdata(const dnslib_rrset_t *rrset);
 
@@ -181,8 +182,6 @@ uint dnslib_rrset_rrsig_count(const dnslib_rrset_t *rrset);
 /*!
  * \brief Destroys the RRSet structure.
  *
- * \param rrset RRset to be destroyed.
- *
  * Does not destroy the OWNER domain name structure, nor the signatures, as
  * these may be used elsewhere. This is however a higher-level logic, so maybe
  * a parameter for deciding what to destroy would be better.
@@ -191,7 +190,9 @@ uint dnslib_rrset_rrsig_count(const dnslib_rrset_t *rrset);
  * their items are not destroyed in dnslib_rdata_free(), so this would be
  * confusing.
  *
- * Sets the given pointer to NULL.
+ * Also sets the given pointer to NULL.
+ *
+ * \param rrset RRset to be destroyed.
  */
 void dnslib_rrset_free(dnslib_rrset_t **rrset);