Improve doxygen documentation.

Doxyfile

@@ -61,7 +61,7 @@ OUTPUT_DIRECTORY       = doc
 # source files, where putting all generated files in the same directory would 
 # otherwise cause performance problems for the file system.
 
-CREATE_SUBDIRS         = YES
+CREATE_SUBDIRS         = NO
 
 # The OUTPUT_LANGUAGE tag is used to specify the language in which all 
 # documentation generated by doxygen is written. Doxygen will use this 
@@ -106,7 +106,7 @@ ABBREVIATE_BRIEF       =
 # Doxygen will generate a detailed section even if there is only a brief 
 # description.
 
-ALWAYS_DETAILED_SEC    = NO
+ALWAYS_DETAILED_SEC    = YES
 
 # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all 
 # inherited members of a class in the documentation of that class as if those 
@@ -119,7 +119,7 @@ INLINE_INHERITED_MEMB  = NO
 # path before files name in the file list and in the header files. If set 
 # to NO the shortest path that makes the file name unique will be used.
 
-FULL_PATH_NAMES        = NO
+FULL_PATH_NAMES        = YES
 
 # If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag 
 # can be used to strip a user-defined part of the path. Stripping is 
@@ -128,7 +128,7 @@ FULL_PATH_NAMES        = NO
 # If left blank the directory from which doxygen is run is used as the 
 # path to strip.
 
-STRIP_FROM_PATH        = 
+STRIP_FROM_PATH        = include
 
 # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of 
 # the path mentioned in the documentation of a class, which tells 
@@ -137,7 +137,7 @@ STRIP_FROM_PATH        =
 # definition is used. Otherwise one should specify the include paths that 
 # are normally passed to the compiler using the -I flag.
 
-STRIP_FROM_INC_PATH    = 
+STRIP_FROM_INC_PATH    = include
 
 # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter 
 # (but less readable) file names. This can be useful if your file system 
@@ -790,7 +790,7 @@ INLINE_SOURCES         = NO
 # doxygen to hide any special comment blocks from generated source code 
 # fragments. Normal C, C++ and Fortran comments will always remain visible.
 
-STRIP_CODE_COMMENTS    = YES
+STRIP_CODE_COMMENTS    = NO
 
 # If the REFERENCED_BY_RELATION tag is set to YES 
 # then for each documented function all documented 
@@ -1130,7 +1130,7 @@ GENERATE_TREEVIEW      = YES
 # documentation. Note that a value of 0 will completely suppress the enum 
 # values from appearing in the overview section.
 
-ENUM_VALUES_PER_LINE   = 4
+ENUM_VALUES_PER_LINE   = 1
 
 # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be 
 # used to set the initial width (in pixels) of the frame in which the tree 

include/ucore/atomic.h

@@ -1,7 +1,8 @@
 #ifndef UC_ATOMIC_H_
 #define UC_ATOMIC_H_
 
-/** Atomic functions (macros). The ptr argument must be a pointer to 
+/** @file
+ * Atomic functions (macros). The ptr argument must be a pointer to 
  * an integer type.
  * For gcc, see http://gcc.gnu.org/onlinedocs/gcc-4.8.1/gcc/_005f_005fsync-Builtins.html
  */

include/ucore/bitvec.h

@@ -13,19 +13,22 @@ typedef unsigned long uc_bv_integer;
 struct UCBitVec {
     //storage for the bits
     uc_bv_integer *vec;
-    //length in bytes of the above vec.
+    //number of elements int the above vec.
     size_t vec_len;
 };
 
 /**
- *  Evaluates the length required for a bitvec to store nbit bits.
+ *  Evaluates the number of uc_bv_integer elements  required for a bitvec to store nbit bits.
  */
 #define UC_BV_LEN(nbits)   ((nbits/(sizeof(uc_bv_integer)*CHAR_BIT)) + (nbits % (sizeof(uc_bv_integer)*CHAR_BIT) == 0 ? 0 : 1))
 
-/**
+/** Initialize a bitvec with predefined backing array.
- * Use as :
+ * The backing array element type must be uc_bv_integer
+ * Use as
+ * @code
  * uc_bv_integer v[10];
  * struct UCBitVec v = BITVEC_STATIC_INIT(v);
+ * @endcode
  */
 #define UC_BV_STATIC_INIT(vec_data)\
 {\
@@ -47,13 +50,13 @@ void uc_bv_free(struct UCBitVec *v);
 //Note that accessing a bit beyond the nbits originally initialized
 //for the given bitvec is undedefined
 
-/** Sets bit no. b */
+/** Sets bit number b */
 void uc_bv_set_bit(struct UCBitVec *v,int b);
 
-/** Clears bit no. b*/
+/** Clears bit number b*/
 void uc_bv_clr_bit(struct UCBitVec *v,int b);
 
-/** Gets the current value (0 or 1) of bit no. b*/
+/** Gets the current value (0 or 1) of bit number @b*/
 int uc_bv_get_bit(const struct UCBitVec *v,int b);
 
 /** Sets all bits to zero */

include/ucore/dbuf.h

@@ -6,37 +6,38 @@
 extern "C" {
 #endif
 
-/**
+/** @file
  * dbuf is a generic buffer that will grow automatically.
- * call buf_ensure() to reserve space, and don't write more data
+ * call uc_buf_ensure() to reserve space, and don't write more data
- * than you told buf_ensure() to reserve.
+ * than you told uc_buf_ensure() to reserve.
  *
  * You write data to buf->end
  * When finished writing data
  * you call dbuf_added/( with the no. of bytes you've added.
  *
- * You read data from buf->start, the buffer has dbuf_len() bytes of data
+ * You read data from buf->start, the buffer has uc_dbuf_len() bytes of data
- * When you've read and processed the data, call dbuf_take()
+ * When you've read and processed the data, call uc_dbuf_take()
  * to indicate you're done with the data.
  *
  * typically(but add error checking)
  * @code
  * DBuf buf;
- * dbuf_init(&buf,4096);
+ * uc_dbuf_init(&buf,4096);
  * for(;;) {
- *   dbuf_ensure(buf,4096);
+ *   uc_dbuf_ensure(buf,4096);
  *   size_t len = fread(buf,4096,1,f);
- *   dbuf_added(&buf,len);
+ *   uc_dbuf_added(&buf,len);
  *   char *end;
- *   while((end = memchr(buf.start,'\n',dbuf_len(&dbuf))) != NULL) { //look for a newline
+ *   while((end = memchr(buf.start,'\n',uc_dbuf_len(&dbuf))) != NULL) { //look for a newline
  *      ++end;
  *      int linelen = end - buf.start;
  *      process_line(buf.start,linelen);
- *      dbuf_take(&dbuf,linelen);
+ *      uc_dbuf_take(&dbuf,linelen);
  *   }
  * }
  * @endcode
  */
+
 typedef struct DBuf DBuf;
 struct DBuf {
     /** Start of user data */

include/ucore/dstr.h

@@ -8,7 +8,7 @@
 extern "C" {
 #endif
 
-/** A managed C-string, using dynalically allocated memory for the string.
+/** A managed C-string, using dynamically allocated memory for the string.
  *
  * The .str member might not always be nul terminated,
  * Normally, use uc_dstr_str() to retreive the managed string
@@ -52,8 +52,11 @@ int uc_dstr_init_str_sz(struct DStr *str, const char *init, size_t len);
  */
 void uc_dstr_destroy(struct DStr *str);
 
-/** Copy a DStr
+/** Copy a DStr.
- *
+ *  The @dest string should not be an initialized string since it will be 
+ *  initialized by uc_dstr_copy, and would cause a memory leak if it's already
+ *  initialized.
+ * 
  * @param dest destination string to copy to, must not contain an existing string
  * @param src DStr to copy
  *

include/ucore/heapsort.h

@@ -6,13 +6,17 @@
 #ifdef __cplusplus
 extern "C" {
 #endif
-///compare function. Needs only to return < 0 if 
+/** Compare function. Needs only to return < 0 if 
-//a is less tan b
+* a is less than b
+*/
 typedef int (*uc_hs_cmp)(const void *a, const void *b, void *cookie);
-//swap function, must swap around element a and b
+/** Swap function, Must swap around element a and b
+ */
 typedef void (*uc_hs_swp)(void *a, void *b);
 
 /** Sort an array.
+ * As the name implies this sorts using the heapsort algorithm.
+ *
  * @param base start of array
  * @param count number of elements in array
  * @param width size of each element

include/ucore/htable.h

@@ -3,7 +3,8 @@
 
 #include <stddef.h>
 
-/** Building block for hash table.
+/** @file
+ * Building block for hash table.
  * The hash table is stored using a chained list of buckets.
  * Nodes with different hash value can be stored in the same bucket.
  *

include/ucore/iomux_waker.h

@@ -15,16 +15,19 @@ struct IOMuxSignaller {
     int fd;
 };
 
-/** These are primitives to wake up an IOMux.
+/** @file
+ * These are primitives to wake up an IOMux.
  * An IOMux event loop can be woken up from e.g. an unix signal handler
  * or another thread. The IOMuxWaker itself is not thread safe, it's members
- * must not be accessed from anything other than the loop it's connected to.
+ * except for the signaller must not be accessed from anything other than the 
+ * IOMux it's connected to.
  * Only uc_iomux_waker_signal() can be called from another thread/signal handler
  * than the IOMux it's connected to.
  * 
  * Note that several signals to wake up a loop can get merged, the callback
  * handler can be called only once for several signals.
  */
+
 struct IOMuxWaker {
     //private fields
     struct IOMuxFD read_fd;

include/ucore/logging.h

@@ -2,7 +2,8 @@
 #define UC_LOGGING_H_
 #include "utils.h"
 
-/** Logging functions. 
+/** @file
+ * Application logging framework.
  * All logging functions except uc_log_init are thread safe,
  * so logging can be performed from any thread after the logging 
  * system have been initialized.

include/ucore/mbuf.h

@@ -16,6 +16,41 @@
 #endif
 #endif
 
+/** @file
+ * mbuf - A managed message/memory buffer.
+ * 
+ * Concept: 
+   @verbatim
+   <--------- allocated ----------->
+             <--- len  -->
+   +--------------------------------+
+   |Headroom| Data        |Tailroom |
+   +--------------------------------+
+   ^        ^             ^
+   |        |             |
+   |        |            tail
+   |       head
+   bufstart
+  
+  @endverbatim
+ * 
+ * Initially when empty, head == tail, and the length is 0. 
+ * Data is added to the tail.
+ *
+ * If head == bufstart, there is no headroom
+ * if tail points one past the allocated space, there is no 
+ * tailroom (the buffer is full)
+ *
+ * Conventions:
+ * push - prepend data to the buffer (in the head room part)
+ *        (move head to the left)
+ * pull - remove data from the beginning of the message.
+ *        (move head to the right)
+ * put  - Add data to the buffer.
+ *        (move tail to the right)
+ */
+
+/** Flags used internally */
 enum UC_MBUF_FLAGS {
     UC_MBUF_FL_MALLOC        = 0x0001, //MBuf and MBuf->bufstart are seperatly malloc'd
     UC_MBUF_FL_MALLOC_BUF    = 0x0001, //MBuf is not malloc'd. MBuf->bufstart is malloc'd
@@ -51,34 +86,6 @@ struct MBuf {
     uint8_t inline_data[0];
 };
 
-/**
- * Concept: 
- * <--------- allocated ----------->
- *           <--- len  -->
- * +--------------------------------+
- * |Headroom| Data        |Tailroom |
- * +--------------------------------+
- * ^        ^             ^
- * |        |             |
- * |        |            tail
- * |       head
- * bufstart
- * 
- * Initially when empty, head == tail, and the length is 0. 
- * Data is added to the tail.
- *
- * If head == bufstart, there is no headroom
- * if tail points one past the allocated space, there is no 
- * tailroom (the buffer is full)
- *
- * Conventions:
- * push - prepend data to the buffer (in the head room part)
- *        (move head to the left)
- * pull - remove data from the beginning of the message.
- *        (move head to the right)
- * put  - Add data to the buffer.
- *        (move tail to the right)
- */
 
 /** Allocate an mbuf with a length and headroom,
  * the buffer will have the flag UC_MBUF_FL_MALLOC

include/ucore/mersenne_twister.h

@@ -5,8 +5,8 @@
 extern "C" {
 #endif
 
-/** Context used for the PRNG*/
 #define MT_RAND_N 624
+/** Context used for the PRNG*/
 typedef struct {
     unsigned int x[MT_RAND_N];
     int i;

include/ucore/pack.h

@@ -15,7 +15,8 @@
 #endif
 #endif
 
-/** Functions for serializing/de-serializing integers to and from
+/** @file
+ * Functions for serializing/de-serializing integers to and from
  * byte arrays.
  * These functions are independant of the host endian. Only
  * thing to care about is the endian format of the data in

include/ucore/rate_limit.h

@@ -1,7 +1,8 @@
 #ifndef UC_RATE_LIMIT_H_
 #define UC_RATE_LIMIT_H_
 
-/** This is a rate limiter, based on the token bucket principle.
+/** @file
+ * This is a rate limiter, based on the token bucket principle.
  * We have X amount of tickets(=our rate) per Y amount of time,
  *  
  * The allowed tickets increases with X per Y amount of time.

include/ucore/salloc.h

@@ -6,7 +6,8 @@
 #ifdef __cplusplus
 extern "C" {
 #endif
-/** Sequntial memory allocator
+/** @file
+ * Sequntial memory allocator
  *
  * Allocates bigger chunks of memory at a time, to save the amount of malloc call,
  * and enables you to free all that memory in one sweep.

include/ucore/saturating_math.h

@@ -2,7 +2,8 @@
 #define UC_SATMATH_H_
 #include <stdint.h>
 
-/** Implementation of saturated operation on uintxx_t. 
+/** @file
+ * Implementation of saturated operation on uintxx_t. 
  *
  * Operations are clamped between 0 and UINTxx_MAX instead of
  * wrapping around.

include/ucore/threadqueue.h

@@ -12,7 +12,47 @@ extern "C" {
  *
  * Little API for waitable queues, typically used for passing messages
  * between threads.
+ *
+ * The uc_thread_queue_ functions only deal with struct uc_threadmsg
+ * structs.
+ * In order for the message passing to be useful, more data needs to be
+ * associated with a message, it's up to the application to manage this.
+ * One way is to e.g. add the struct uc_threadmsg as the first member
+ * of a larger struct, and recover the larger struct after getting a 
+ * struct uc_threadmsg out of the queue. e.g.
+ *
+ * @code
+ * struct my_msg {
+ *   struct uc_threadmsg tmsg;
+ *   int foo;
+ *   char bar[32];
+ * };
+ *
+ * struct my_msg *msg = malloc(sizeof *msg);
+ * msg->tmsg.msgtype = MSGTYP1;
+ * ...
+ * uc_thread_queue_add(queue, &msg->tmsg);
+ *
+ * The receiver end does e.g.
+ *
+ * struct uc_threadmsg *tmsg;
+ * uc_thread_queue_get(queue, NULL, &tmsg);
+ * switch(tmsg->msgtype) {
+ *   case MYMSG1; {
+ *      struct my_msg *msg = (struct my_msg*)tmsg;
+ *      ...
+ *      free(msg);
+ *      break
+ *   ...
+ *   }
+ * }
+ *
+ * @endcode
+ *
+ * As such, a struct uc_threadmsg must live as long as it resides in a thread queue,
+ * and must be removed from the queue before the struct uc_threadmsg is destroyed/deallocated.
  * 
+ *
  * @author Nils O. Selåsdal <NOS@Utel.no>
  */
 
@@ -55,45 +95,6 @@ typedef void (*uc_thread_queue_walk_func) (struct uc_threadmsg *msg, void *cooki
  * the variables in this struct.
  * You have been warned.
  *
- * The uc_thread_queue_ functions only deal with struct uc_threadmsg
- * structs.
- * In order for the message passing to be useful, more data needs to be
- * associated with a message, it's up to the application to manage this.
- * One way is to e.g. add the struct uc_threadmsg as the first member
- * of a larger struct, and recover the larger struct after getting a 
- * struct uc_threadmsg out of the queue. e.g.
- *
- * @code
- * struct my_msg {
- *   struct uc_threadmsg tmsg;
- *   int foo;
- *   char bar[32];
- * };
- *
- * struct my_msg *msg = malloc(sizeof *msg);
- * msg->tmsg.msgtype = MSGTYP1;
- * ...
- * uc_thread_queue_add(queue, &msg->tmsg);
- *
- * The receiver end does e.g.
- *
- * struct uc_threadmsg *tmsg;
- * uc_thread_queue_get(queue, NULL, &tmsg);
- * switch(tmsg->msgtype) {
- *   case MYMSG1; {
- *      struct my_msg *msg = (struct my_msg*)tmsg;
- *      ...
- *      free(msg);
- *      break
- *   ...
- *   }
- * }
- *
- * @endcode
- *
- *
- *
- *
  */
 struct uc_threadqueue {
 /**
@@ -137,7 +138,7 @@ struct uc_threadqueue {
  * thread_queue_init initializes a new threadqueue. A new queue must always
  * be initialized before it is used.
  * A max number of elements the queue will hold must be given.
- * Adding more elements than a queue will hold will e.g. cause
+ * Adding more elements than a queue will hold will cause
  * uc_thread_queue_add to block until space becomes available.
  *
  * @param queue Pointer to the queue that should be initialized

include/ucore/val_str.h

@@ -3,11 +3,17 @@
 
 #include <stddef.h>
 
+/** @file
+ * Utility functions to map integers to strings and strings to strings.
+ */
+
+/** Mapping from an unsigned int to a string*/
 struct UCValStr {
     unsigned int val;
     const char *str;
 };
 
+/** Mapping from a string to another string*/
 struct UCStrStr {
     const char *val;
     const char *str;