- code-documentation improved

Source/charon/job_queue.h

@@ -26,36 +26,43 @@
 #include "linked_list.h"
 
 /**
- * Type of Jobs
+ * Type of Jobs in Job-Queue
  */
 typedef enum job_type_e job_type_t;
 
 enum job_type_e{
 	/** 
-	 * Job is to process an incoming IKEv2-Message
+	 * process an incoming IKEv2-Message
 	 */
 	INCOMING_PACKET,
 	/** 
-	 * Job is to retransmit an IKEv2-Message
+	 * retransmit an IKEv2-Message
 	 */
 	RETRANSMIT_REQUEST,
 	/** 
-	 * Job is to establish an ike sa as initiator
+	 * establish an ike sa as initiator
 	 */
 	ESTABLISH_IKE_SA
+	/* more job types have to be inserted here */
 };
 
 
 /**
- * @brief Job like it is represented in the job queue
+ * @brief Job as it is stored in the job queue
+ * 
+ * A job consists of a job-type and an assigned value
+ * 
+ * The value-type for a specific job is not discussed here
  */
 typedef struct job_s job_t;
 
-
 struct job_s{
+	/**
+	 * Type of job
+	 */
 	job_type_t type;
 	/**
-	 * Every job has its assigned_data
+	 * Every job has its assigned_data based on the job type
 	 */
 	void * assigned_data;
 
@@ -80,48 +87,55 @@ job_t *job_create(job_type_t type, void *assigned_data);
 
 /**
  * @brief Job-Queue
+ *
+ * Despite the job-queue is based on a linked_list_t 
+ * all access functions are thread-save implemented
  */
 typedef struct job_queue_s job_queue_t;
 
 struct job_queue_s {
 	
 	/**
-	 * @brief Returns number of jobs in queue
+	 * @brief returns number of jobs in queue
 	 * 
 	 * @param job_queue_t calling object
- 	 * @param count integer pointer to store the job count in
+ 	 * @param[out] count integer pointer to store the job count in
 	 * @returns SUCCESS if succeeded, FAILED otherwise
 	 */
 	status_t (*get_count) (job_queue_t *job_queue, int *count);
 
 	/**
-	 * @brief Get the next job from the queue
+	 * @brief get the next job from the queue
 	 * 
-	 * If the queue is empty, this function blocks until job can be returned.
+	 * If the queue is empty, this function blocks until a job can be returned.
 	 * 
-	 * After using, the returned job has to get destroyed.
+	 * After using, the returned job has to get destroyed by the caller.
 	 * 
 	 * @param job_queue_t calling object
- 	 * @param job pointer to a job pointer where to job is returned to
+ 	 * @param[out] job pointer to a job pointer where to job is returned to
 	 * @returns SUCCESS if succeeded, FAILED otherwise
 	 */
 	status_t (*get) (job_queue_t *job_queue, job_t **job);
 	
 	/**
-	 * @brief Adds a job to the queue
+	 * @brief adds a job to the queue
 	 * 
-	 * This function is non blocking
+	 * This function is non blocking and adds a job_t to the list.
+	 * The specific job-object has to get destroyed by the thread which 
+	 * removes the job.
 	 * 
 	 * @param job_queue_t calling object
- 	 * @param job job to add to the queue (job is not copied)
+ 	 * @param[in] job job to add to the queue (job is not copied)
 	 * @returns SUCCESS if succeeded, FAILED otherwise
 	 */
 	status_t (*add) (job_queue_t *job_queue, job_t *job);
 
 	/**
-	 * @brief Destroys a job_queue object
+	 * @brief destroys a job_queue object
 	 * 
-	 * @warning Has only to be called if no other thread is accessing the queue
+	 * @warning The caller of this function has to make sure
+	 * that no thread is going to add or get a job from the job_queue
+	 * after calling this function.
 	 * 
 	 * @param job_queue_t calling object
 	 * @returns SUCCESS if succeeded, FAILED otherwise
@@ -130,8 +144,8 @@ struct job_queue_s {
 };
 
 /**
- * @brief Creates a job_queue
+ * @brief Creates an empty job_queue
- * * 
+ * 
  * @return job_queue_t empty job_queue
  */
 job_queue_t *job_queue_create();

Source/charon/linked_list.c

@@ -34,17 +34,26 @@
 static status_t linked_list_element_destroy(linked_list_element_t *linked_list_element)
 {
 	linked_list_element_t * this = 	linked_list_element;
+	if (this == NULL)
+	{
+		return FAILED;
+	}
 	pfree(this);
 	return SUCCESS;
 }
 
 /*
- * Creates a linked list (documented in header-file)
+ * Creates an empty linked list (described in header-file)
  */
 linked_list_element_t *linked_list_element_create(void *value)
 {
 	linked_list_element_t *this = alloc_thing(linked_list_element_t, "linked_list_element_t");
 	
+	if (this == NULL)
+	{
+		return NULL;
+	}
+	
 	this->destroy = linked_list_element_destroy;
 	
 	this->previous=NULL;
@@ -63,6 +72,11 @@ static status_t insert_first(linked_list_t *linked_list, void *item)
 	
 	linked_list_element_t *element = linked_list_element_create(item);
 	
+	if (element == NULL)
+	{
+		return FAILED;
+	}
+	
 	if (this->count == 0)
 	{
 		/* first entry in list */
@@ -70,7 +84,8 @@ static status_t insert_first(linked_list_t *linked_list, void *item)
 		this->last = element;
 		element->previous = NULL;
 		element->next = NULL;
-	}else
+	}
+	else
 	{
 		if ((this->first == NULL) || (this->last == NULL))
 		{
@@ -118,7 +133,7 @@ static status_t remove_first(linked_list_t *linked_list, void **item)
 
 	this->count--;
 	
-	return	(element->destroy(element));
+	return	/element->destroy(element));
 }
 
 /**
@@ -152,6 +167,11 @@ static status_t insert_last(linked_list_t *linked_list, void *item)
 	
 	linked_list_element_t *element = linked_list_element_create(item);
 	
+	if (element == NULL)
+	{
+		return FAILED;
+	}
+	
 	if (this->count == 0)
 	{
 		/* first entry in list */
@@ -207,7 +227,7 @@ static status_t remove_last(linked_list_t *linked_list, void **item)
 
 	this->count--;
 	
-	return	element->destroy(element);
+	return	(element->destroy(element));
 }
 
 /**
@@ -239,10 +259,12 @@ static status_t linked_list_destroy(linked_list_t *linked_list)
 {
 	linked_list_t *this = linked_list;
 
-	/* Delete all list items before deleting list */
+	/* Remove all list items before destroying list */
 	while (this->count > 0)
 	{
 		void * value;
+		/* values are not destroyed so memory leaks are possible
+		 * if list is not empty when deleting */
 		if (this->remove_first(this,&value) != SUCCESS)
 		{
 			pfree(this);
@@ -254,8 +276,7 @@ static status_t linked_list_destroy(linked_list_t *linked_list)
 }
  
 /*
- * 
+ * Described in header
- * Documented in header
  */
 linked_list_t *linked_list_create() 
 {

Source/charon/linked_list.h

@@ -25,16 +25,27 @@
 
 #include "types.h"
 
-
 /**
- * @brief Double Linked List Element type
+ * @brief Element of the linked_list.
+ * 
+ * This element holds a pointer to the value of the list item itself.
  */
 typedef struct linked_list_element_s linked_list_element_t;
 
 struct linked_list_element_s {
+	/**
+	 * previous list element 
+	 * NULL if first element in list
+	 */
 	linked_list_element_t *previous;
+	/**
+	 * next list element
+	 * NULL if last element in list
+	 */
 	linked_list_element_t *next;
-	/* value of a list item */
+	/**
+	 * value of a list item
+	 */
 	void *value;
 	
 	/**
@@ -49,7 +60,9 @@ struct linked_list_element_s {
 /**
  * @brief Creates an empty linked list object
  *
- * @param value value of item
+ * @param[in] value value of item to be set
+ * 
+ * @warning only the pointer to the value is stored
  * 
  * @return linked_list_element object
  */
@@ -57,22 +70,38 @@ linked_list_element_t *linked_list_element_create(void *value);
 
 
 /**
- * @brief Double Linked List type
+ * @brief Double Linked List (named only as linked list)
+ *
+ * @warning Access to an object of this type is not thread-save
+ * 
+ * @see job_queue_t
+ * @see event_queue_t
+ * @see send_queue_t
  */
 typedef struct linked_list_s linked_list_t;
 
 
 struct linked_list_s {
-	/* item count */
+	/**
+	 * number of items in the list
+	 */
 	int count;
+	/**
+	 * First element in list
+	 * NULL if no elements in list
+	 */
 	linked_list_element_t *first;
+	/**
+	 * Last element in list
+	 * NULL if no elements in list
+	 */
 	linked_list_element_t *last;
 	
 	/**
 	 * @brief inserts a new item at the beginning of the list
 	 * 
 	 * @param linked_list calling object
-	 * @param item value to insert in list
+	 * @param[in] item value to insert in list
 	 * @returns SUCCESS if succeeded, FAILED otherwise
 	 */
 	status_t (*insert_first) (linked_list_t *linked_list, void *item);
@@ -81,16 +110,16 @@ struct linked_list_s {
 	 * @brief removes the first item in the list and returns its value
 	 * 
 	 * @param linked_list calling object
-	 * @param item returned value of first item
+	 * @param[in] item returned value of first item
 	 * @returns SUCCESS if succeeded, FAILED otherwise
 	 */
 	status_t (*remove_first) (linked_list_t *linked_list, void **item);
 
 	/**
-	 * @brief Returns the value of the first list item without removing it
+	 * @brief returns the value of the first list item without removing it
 	 * 
 	 * @param linked_list calling object
-	 * @param item returned value of first item
+	 * @param[out] item returned value of first item
 	 * @returns SUCCESS if succeeded, FAILED otherwise
 	 */
 	status_t (*get_first) (linked_list_t *linked_list, void **item);
@@ -99,7 +128,7 @@ struct linked_list_s {
 	 * @brief inserts a new item at the end of the list
 	 * 
 	 * @param linked_list calling object
-	 * @param item value to insert in list
+	 * @param[in] item value to insert into list
 	 * @returns SUCCESS if succeeded, FAILED otherwise
 	 */
 	status_t (*insert_last) (linked_list_t *linked_list, void *item);
@@ -108,7 +137,7 @@ struct linked_list_s {
 	 * @brief removes the last item in the list and returns its value
 	 * 
 	 * @param linked_list calling object
-	 * @param item returned value of last item
+	 * @param[out] item returned value of last item
 	 * @returns SUCCESS if succeeded, FAILED otherwise
 	 */
 	status_t (*remove_last) (linked_list_t *linked_list, void **item);
@@ -117,7 +146,7 @@ struct linked_list_s {
 	 * @brief Returns the value of the last list item without removing it
 	 * 
 	 * @param linked_list calling object
-	 * @param item returned value of last item
+	 * @param[out] item returned value of last item
 	 * @returns SUCCESS if succeeded, FAILED otherwise
 	 */
 	status_t (*get_last) (linked_list_t *linked_list, void **item);
@@ -125,6 +154,11 @@ struct linked_list_s {
 	/**
 	 * @brief Destroys a linked_list object
 	 * 
+	 * @warning all items are removed before deleting the list. The
+	 *          associated values are NOT destroyed. 
+	 * 			Destroying an list which is not empty may cause
+	 * 			memory leaks!
+	 * 
 	 * @param linked_list calling object
 	 * @returns SUCCESS if succeeded, FAILED otherwise
 	 */
@@ -132,9 +166,7 @@ struct linked_list_s {
 };
 
 /**
- * @brief
+ * @brief Creates an empty linked list object
- * 
- * Creates an empty linked list object
  */
 linked_list_t *linked_list_create(void);