started fixing documentation

Doxyfile

@@ -838,7 +838,7 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           = server/etc/
+EXAMPLE_PATH           = etc/
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and

doc/Hooks.md

@@ -21,39 +21,39 @@ Example applications for hooks might be:
 Each path is allowed to have multiple active hooks.
 Those can be configured in the path section using the `hooks` setting:
 
-```
-paths = [
-  {
-    in = "input_node",
-    out = "output_node",
-    hooks = [ "fir", "print" ]
-#   hooks = "decimate"    // alternative syntax for a single hook
-  }
-]
-```
+	paths = [
+		{
+			in = "input_node",
+			out = "output_node",
+			hooks = [ "fir", "print" ]
+	#		hooks = "decimate"    // alternative syntax for a single hook
+		}
+	]
 
 **Please note:** the hooks will be executed in the order they are given in the configuration file!
 
 ## API
 
-The interface for user-defined hook functions is defined in (server/include/hooks.h):
+The interface for user-defined hook functions is defined in (`server/include/hooks.h`):
 
-```c
-typedef int (*hook_cb_t)(struct path *p);
+```
+typedef int (*hook_cb_t)(struct path *p, struct hook *h, int when);
 ```
 
 There are several occasions when a hook can be executed in the program flow (@see hook_type).
-There is a dedicated queue for each occasion:
+There is a dedicated queue for each occasion.
 
-| Queue               | Desciption                                                     |
-| ------------------- | -------------------------------------------------------------- |
-| `HOOK_PATH_START`   | Called whenever a path is started; before threads are created. |
-| `HOOK_PATH_STOP`		| Called whenever a path is stopped; after threads are destoyed. |
+The queue for which a hook can be called is encoded as a mask and specified during registration of that hook. 
+
+| Queue			| Desciption								|
+| --------------------- | --------------------------------------------------------------------- |
+| `HOOK_PATH_START`	| Called whenever a path is started; before threads are created.	|
+| `HOOK_PATH_STOP`	| Called whenever a path is stopped; after threads are destoyed.	|
 | `HOOK_PATH_RESTART`	| Called whenever a new simulation case is started. This is detected by a sequence no equal to zero. |
-| `HOOK_PRE`		      | Called when a new packet of messages (samples) was received.   |
-| `HOOK_POST`		      | Called after each message (sample) of a packet was processed.  |
-| `HOOK_MSG`          | Called for each message (sample) in a packet. |
-| `HOOK_PERIODIC`     | Called periodically. Period is set by global 'stats' option in the configuration file. |
+| `HOOK_PRE`		| Called when a new packet of messages (samples) was received.		|
+| `HOOK_POST`		| Called after each message (sample) of a packet was processed.		|
+| `HOOK_MSG`		| Called for each message (sample) in a packet.				|
+| `HOOK_PERIODIC`	| Called periodically. Period is set by global 'stats' option in the configuration file. |
 
 ## Examples
 
@@ -62,11 +62,9 @@ Use one of those as a starting point for your own hook.
 
 A typical hook function might look like this one:
 
-```c
-int my_super_hook_function(struct path *p)
-{
-  struct msg *last_received_msg = p->current;
-  
-  printf("The last message contained %u values\n", last_received_msg->length);
-}
-```
+	int my_super_hook_function(struct path *p, struct hook *h, int when)
+	{
+		struct msg *last_received_msg = p->current;
+	
+		printf("The last message contained %u values\n", last_received_msg->length);
+	}

include/list.h

@@ -1,6 +1,10 @@
-/** A generic linked list
+/** A generic list implementation.
  *
- * Linked lists a used for several data structures in the code.
+ * This is a generic implementation of a list which can store void pointers to
+ * arbitrary data. The data itself is not stored or managed by the list.
+ *
+ * Internally, an array of pointers is used to store the pointers.
+ * If needed, this array will grow by realloc().
  *
  * @file
  * @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
@@ -42,6 +46,7 @@ typedef void (*dtor_cb_t)(void *);
 /** Callback to search or sort a list. */	
 typedef int (*cmp_cb_t)(const void *, const void *);
 
+/* The list data structure. */
 struct list {
 	void **array;		/**< Array of pointers to list elements */
 	size_t capacity;	/**< Size of list::array in elements */
@@ -50,7 +55,11 @@ struct list {
 	pthread_mutex_t lock;	/**< A mutex to allow thread-safe accesses */
 };
 
-/** Initialize a list */
+/** Initialize a list.
+ *
+ * @param l A pointer to the list data structure.
+ * @param dtor A function pointer to a desctructor which will be called for every list item when the list is destroyed.
+ */
 void list_init(struct list *l, dtor_cb_t dtor);
 
 /** Destroy a list and call destructors for all list elements */
@@ -62,9 +71,9 @@ void list_push(struct list *l, void *p);
 /** Remove all occurences of a list item */
 void list_remove(struct list *l, void *p);
 
-/** Search the list for an element whose first element is a character array which matches name.
+/** Return the first list element which is identified by a string in its first member variable.
  *
- * List elements should be of the following form:
+ * List elements are pointers to structures of the following form:
  *
  * struct obj {
  *    char *name;

include/msg.h

@@ -51,7 +51,8 @@ int msg_verify(struct msg *m);
 
 /** Print a raw message in human readable form to a file stream.
  *
- * @param f The file handle from fopen() or stdout, stderr.
+ * @param buf A character buffer of len bytes.
+ * @param len The size of buf.
  * @param m A pointer to the message.
  * @param flags See msg_flags.
  * @param offset A optional offset in seconds. Only used if flags contains MSG_PRINT_OFFSET.
@@ -61,7 +62,7 @@ int msg_print(char *buf, size_t len, struct msg *m, int flags, double offset);
 
 /** Read a message from a character buffer.
  *
- * @param f The file handle from fopen() or stdin.
+ * @param line A string which should be parsed.
  * @param m A pointer to the message.
  * @param flags et MSG_PRINT_* flags for each component found in sample if not NULL. See msg_flags.
  * @param offset Write offset to this pointer if not NULL.
@@ -73,12 +74,18 @@ int msg_scan(const char *line, struct msg *m, int *fl, double *off);
 /** Print a raw message in human readable form to a file stream.
  *
  * @see msg_print()
+ * @param f The file handle from fopen() or stdout, stderr.
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
  */
 int msg_fprint(FILE *f, struct msg *m, int flags, double offset);
 
 /** Read a message from a file stream.
  *
  * @see msg_scan()
+ * @param f The file handle from fopen() or stdin.
+ * @retval 0 Success. Everything went well.
+ * @retval <0 Error. Something went wrong.
  */
 int msg_fscan(FILE *f, struct msg *m, int *flags, double *offset);