Improve doxygen documentation.

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