- code documentation improved and made fully compatible with doxygen

2 files changed, 61 insertions, 47 deletions

diff --git a/Source/charon/event_queue.c b/Source/charon/event_queue.c
index f1b682812..120efd2a3 100644
--- a/Source/charon/event_queue.c
+++ b/Source/charon/event_queue.c
@@ -34,29 +34,29 @@
 
 
 /**
- * @brief represents an event as it is stored in the event queue
+ * @brief Represents an event as it is stored in the event queue.
  *
- * A event consists of a event time and an assigned job object
+ * A event consists of a event time and an assigned job object.
  *
  */
 typedef struct event_s event_t;
 
 struct event_s{
 	/**
-	 * Time to fire the event
+	 * Time to fire the event.
 	 */
 	timeval_t time;
 
 	/**
-	 * Every event has its assigned job
+	 * Every event has its assigned job.
 	 */
 	job_t * job;
 
 	/**
-	 * @brief Destroys a event_t object
+	 * @brief Destroys a event_t object.
 	 *
-	 * @param event_t calling object
-	 * @returns SUCCESS if succeeded, FAILED otherwise
+	 * @param event_t 	calling object
+	 * @returns 			always SUCCESS
 	 */
 	status_t (*destroy) (event_t *event);
 };
@@ -67,10 +67,6 @@ struct event_s{
  */
 static status_t event_destroy(event_t *event)
 {
-	if (event == NULL)
-	{
-		return FAILED;
-	}
 	allocator_free(event);
 	return SUCCESS;
 }
@@ -78,17 +74,22 @@ static status_t event_destroy(event_t *event)
 /**
  * @brief Creates a event for a specific time
  *
- * @param time to fire the event
- * @param job job to add to job-queue at specific time
+ * @param time	absolute time to fire the event
+ * @param job 	job to add to job-queue at specific time
  *
- * @return event_t event object
+ * @returns
+ * 				- created event_t object 
+ * 				- NULL if memory allocation failed
  */
 static event_t *event_create(timeval_t time, job_t *job)
 {
 	event_t *this = allocator_alloc_thing(event_t);
+	if (this == NULL)
+	{
+		return this;
+	}
 
 	this->destroy = event_destroy;
-
 	this->time = time;
 	this->job = job;
 
@@ -97,29 +98,33 @@ static event_t *event_create(timeval_t time, job_t *job)
 
 
 /**
- * @brief Private Variables and Functions of event_queue class
+ * @brief Private Variables and Functions of event_queue_t class.
  *
  */
 typedef struct private_event_queue_s private_event_queue_t;
 
 
 struct private_event_queue_s {
+	/**
+	 * Public part.
+	 */
  	event_queue_t public;
 
 	/**
-	 * The events are stored in a linked list
+	 * The events are stored in a linked list of type linked_list_t.
 	 */
 	linked_list_t *list;
 
 	/**
-	 * access to linked_list is locked through this mutex
+	 * Access to linked_list is locked through this mutex.
 	 */
 	pthread_mutex_t mutex;
 
 	/**
 	 * If the queue is empty or an event has not to be fired
-	 * a thread has to wait
-	 * This condvar is used to wake up such a thread
+	 * a thread has to wait.
+	 * 
+	 * This condvar is used to wake up such a thread.
 	 */
 	pthread_cond_t condvar;
 };
@@ -127,14 +132,14 @@ struct private_event_queue_s {
 /**
  * Returns the difference of to timeval structs in microseconds
  *
- * @param end_time end time
- * @param start_time start time
+ * @param end_time 		end time
+ * @param start_time 	start time
  *
  * @warning this function is also defined in the tester class
  * 			In later improvements, this function can be added to a general
  *          class type!
  *
- * @return difference in microseconds
+ * @return 	difference in microseconds (end time - start time)
  */
 static long time_difference(struct timeval *end_time, struct timeval *start_time)
 {
@@ -147,7 +152,8 @@ static long time_difference(struct timeval *end_time, struct timeval *start_time
 
 
 /**
- * @brief implements function get_count of event_queue_t
+ * Implements function get_count of event_queue_t.
+ * See #event_queue_s.get_count for description.
  */
 static int get_count (private_event_queue_t *this)
 {
@@ -159,7 +165,8 @@ static int get_count (private_event_queue_t *this)
 }
 
 /**
- * @brief implements function get of event_queue_t
+ * Implements function get of event_queue_t.
+ * See #event_queue_s.get for description.
  */
 static status_t get(private_event_queue_t *this, job_t **job)
 {
@@ -216,7 +223,8 @@ static status_t get(private_event_queue_t *this, job_t **job)
 }
 
 /**
- * @brief implements function add of event_queue_t
+ * Implements function add_absolute of event_queue_t.
+ * See #event_queue_s.add_absolute for description.
  */
 static status_t add_absolute(private_event_queue_t *this, job_t *job, timeval_t time)
 {
@@ -297,7 +305,8 @@ static status_t add_absolute(private_event_queue_t *this, job_t *job, timeval_t
 }
 
 /**
- * @brief implements function add of event_queue_t
+ * Implements function add_relative of event_queue_t.
+ * See #event_queue_s.add_relative for description.
  */
 static status_t add_relative(event_queue_t *this, job_t *job, u_int32_t ms)
 {
@@ -315,7 +324,8 @@ static status_t add_relative(event_queue_t *this, job_t *job, u_int32_t ms)
 
 
 /**
- * @brief implements function destroy of event_queue_t
+ * Implements function destroy of event_queue_t.
+ * See #event_queue_s.destroy for description.
  */
 static status_t event_queue_destroy(private_event_queue_t *this)
 {
@@ -342,7 +352,6 @@ static status_t event_queue_destroy(private_event_queue_t *this)
 }
 
 /*
- *
  * Documented in header
  */
 event_queue_t *event_queue_create()
diff --git a/Source/charon/event_queue.h b/Source/charon/event_queue.h
index 32e483bae..c517fcdfb 100644
--- a/Source/charon/event_queue.h
+++ b/Source/charon/event_queue.h
@@ -41,14 +41,13 @@ struct event_queue_s {
 	/**
 	 * @brief Returns number of events in queue.
 	 * 
-	 * @param event_queue calling object
- 	 * @param[out] count integer pointer to store the event count in
-	 * @return	number of events in queue
+	 * @param event_queue 	calling object
+	 * @return 				number of events in queue
 	 */
 	int (*get_count) (event_queue_t *event_queue);
 
 	/**
-	 * @brief get the next job from the event-queue
+	 * @brief Get the next job from the event-queue.
 	 * 
 	 * If no event is pending, this function blocks until a job can be returned.
 	 * 
@@ -60,42 +59,46 @@ struct event_queue_s {
 	status_t (*get) (event_queue_t *event_queue, job_t **job);
 	
 	/**
-	 * @brief adds a event to the queue, using a relative time
+	 * @brief Adds a event to the queue, using a relative time.
 	 * 
 	 * This function is non blocking and adds a job_t at a specific time to the list.
 	 * The specific job-object has to get destroyed by the thread which 
 	 * removes the job.
 	 * 
-	 * @param event_queue calling object
- 	 * @param[in] job job to add to the queue (job is not copied)
-  	 * @param[in] time time, when the event has to get fired
-	 * @returns SUCCESS if succeeded, FAILED otherwise
+	 * @param event_queue 	calling object
+ 	 * @param[in] job 		job to add to the queue (job is not copied)
+  	 * @param[in] time 		relative time, when the event has to get fired
+	 * @returns 
+	 * 						- SUCCESS if succeeded
+	 * 						- FAILED otherwise
 	 */
 	status_t (*add_relative) (event_queue_t *event_queue, job_t *job, u_int32_t ms);
 	
 	/**
-	 * @brief adds a event to the queue, using an absolute time
+	 * @brief Adds a event to the queue, using an absolute time.
 	 * 
 	 * This function is non blocking and adds a job_t at a specific time to the list.
 	 * The specific job-object has to get destroyed by the thread which 
 	 * removes the job.
 	 * 
-	 * @param event_queue calling object
- 	 * @param[in] job job to add to the queue (job is not copied)
-  	 * @param[in] time time, when the event has to get fired
-	 * @returns SUCCESS if succeeded, FAILED otherwise
+	 * @param event_queue 	calling object
+ 	 * @param[in] 			job job to add to the queue (job is not copied)
+  	 * @param[in] 			absolute time time, when the event has to get fired
+	 * @returns
+	 * 						- SUCCESS if succeeded
+	 * 						- FAILED otherwise
 	 */
 	status_t (*add_absolute) (event_queue_t *event_queue, job_t *job, timeval_t time);
 
 	/**
-	 * @brief destroys a event_queue object
+	 * @brief Destroys a event_queue object.
 	 * 
 	 * @warning The caller of this function has to make sure
 	 * that no thread is going to add or get an event from the event_queue
 	 * after calling this function.
 	 * 
-	 * @param event_queue calling object
-	 * @returns SUCCESS if succeeded, FAILED otherwise
+	 * @param event_queue 	calling object
+	 * @returns				always SUCCESS
 	 */
 	status_t (*destroy) (event_queue_t *event_queue);
 };
@@ -103,7 +106,9 @@ struct event_queue_s {
 /**
  * @brief Creates an empty event_queue
  * 
- * @return empty event_queue object
+ * @returns 
+ * 			- Empty event_queue_t object
+ * 			- NULL if memory allocation failed
  */
 event_queue_t *event_queue_create();
 #endif /*EVENT_QUEUE_H_*/