- docs updated

Source/charon/queues/event_queue.c

@@ -90,7 +90,7 @@ static event_t *event_create(timeval_t time, job_t *job)
 typedef struct private_event_queue_t private_event_queue_t;
 
 /**
- * @brief Private Variables and Functions of event_queue_t class.
+ * Private Variables and Functions of event_queue_t class.
  *
  */
 struct private_event_queue_t {
@@ -342,7 +342,7 @@ event_queue_t *event_queue_create()
 	this->public.add_relative = (void (*) (event_queue_t *event_queue, job_t *job, u_int32_t ms)) add_relative;
 	this->public.destroy = (void (*) (event_queue_t *event_queue)) event_queue_destroy;
 
-	this->list = linked_list_create();;
+	this->list = linked_list_create();
 	pthread_mutex_init(&(this->mutex), NULL);
 	pthread_cond_init(&(this->condvar), NULL);
 

Source/charon/queues/event_queue.h

@@ -32,10 +32,18 @@ typedef struct event_queue_t event_queue_t;
 
 /**
  * @brief Event-Queue used to store timed events.
+ * 
+ * Added events are sorted. The get method blocks until
+ * the time is elapsed to process the next event. The get 
+ * method is called from the scheduler_t thread, which
+ * will add the jobs to to job_queue_t for further processing.
  *
  * Although the event-queue is based on a linked_list_t
  * all access functions are thread-save implemented.
  * 
+ * @b Constructors:
+ * - event_queue_create()
+ * 
  * @ingroup queues
  */
 struct event_queue_t {
@@ -93,15 +101,14 @@ struct event_queue_t {
 	 * after calling this function.
 	 *
 	 * @param event_queue 	calling object
-	 * @returns				always SUCCESS
 	 */
 	void (*destroy) (event_queue_t *event_queue);
 };
 
 /**
- * @brief Creates an empty event_queue
+ * @brief Creates an empty event_queue.
  *
- * @returns		event_queue
+ * @returns event_queue_t object
  * 
  * @ingroup queues
  */

Source/charon/queues/job_queue.c

@@ -36,12 +36,17 @@ typedef struct private_job_queue_t private_job_queue_t;
  *
  */
 struct private_job_queue_t {
+	
+	/**
+	 * public members
+	 */
  	job_queue_t public;
 
 	/**
 	 * The jobs are stored in a linked list
 	 */
 	linked_list_t *list;
+	
 	/**
 	 * access to linked_list is locked through this mutex
 	 */

Source/charon/queues/job_queue.h

@@ -29,17 +29,22 @@
 typedef struct job_queue_t job_queue_t;
 
 /**
- * @brief Job-Queue
+ * @brief The job queue stores jobs, which will be processed by the thread_pool_t.
  *
+ * Jobs are added from various sources, from the threads and 
+ * from the event_queue_t.
  * Although the job-queue is based on a linked_list_t
  * all access functions are thread-save implemented.
  * 
+ * @b Constructors:
+ * - job_queue_create()
+ * 
  * @ingroup queues
  */
 struct job_queue_t {
 
 	/**
-	 * @brief returns number of jobs in queue
+	 * @brief Returns number of jobs in queue.
 	 *
 	 * @param job_queue_t 	calling object
 	 * @returns 			number of items in queue
@@ -47,7 +52,7 @@ struct job_queue_t {
 	int (*get_count) (job_queue_t *job_queue);
 
 	/**
-	 * @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 a job can be returned.
 	 * After using, the returned job has to get destroyed by the caller.
@@ -59,7 +64,7 @@ struct job_queue_t {
 	job_t *(*get) (job_queue_t *job_queue);
 
 	/**
-	 * @brief adds a job to the queue
+	 * @brief Adds a job to the queue.
 	 *
 	 * 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
@@ -71,7 +76,7 @@ struct job_queue_t {
 	void (*add) (job_queue_t *job_queue, job_t *job);
 
 	/**
-	 * @brief destroys a job_queue object
+	 * @brief Destroys a job_queue object.
 	 *
 	 * @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
@@ -85,7 +90,7 @@ struct job_queue_t {
 /**
  * @brief Creates an empty job_queue.
  *
- * @return job_queue_t empty job_queue
+ * @return job_queue_t object
  * 
  * @ingroup queues
  */

Source/charon/queues/jobs/delete_established_ike_sa_job.h

@@ -33,6 +33,9 @@ typedef struct delete_established_ike_sa_job_t delete_established_ike_sa_job_t;
 /**
  * @brief Class representing an DELETE_ESTABLISHED_IKE_SA Job.
  * 
+ * This job initiates the deletion of an IKE_SA. The SA
+ * to delete is specified via an ike_sa_id_t.
+ * 
  * @b Constructors:
  *  - delete_established_ike_sa_job_create()
  * 
@@ -66,7 +69,7 @@ struct delete_established_ike_sa_job_t {
  * @brief Creates a job of type DELETE_ESTABLISHED_IKE_SA.
  * 
  * @param ike_sa_id		id of the IKE_SA to delete
- * @return				created delete_established_ike_sa_job_t object
+ * @return				delete_established_ike_sa_job_t object
  * 
  * @ingroup jobs
  */

Source/charon/queues/jobs/delete_half_open_ike_sa_job.h

@@ -33,6 +33,10 @@ typedef struct delete_half_open_ike_sa_job_t delete_half_open_ike_sa_job_t;
 /**
  * @brief Class representing an DELETE_HALF_OPEN_IKE_SA Job.
  * 
+ * This job is responsible for deleting of half open IKE_SAs. A half 
+ * open IKE_SA is every IKE_SA which hasn't reache the ike_sa_established
+ * state.
+ * 
  * @b Constructors:
  *  - delete_half_open_ike_sa_job_create()
  * 

Source/charon/queues/jobs/incoming_packet_job.h

@@ -31,7 +31,13 @@
 typedef struct incoming_packet_job_t incoming_packet_job_t;
 
 /**
- * @brief Object representing an INCOMING_PACKET Job.
+ * @brief Class representing an INCOMING_PACKET Job.
+ * 
+ * An incoming pack job is created from the receiver, which has
+ * read a packet to process from the socket.
+ * 
+ * @b Constructors:
+ * - incoming_packet_job_create()
  * 
  * @ingroup jobs
  */

Source/charon/queues/jobs/initiate_ike_sa_job.h

@@ -28,7 +28,13 @@
 typedef struct initiate_ike_sa_job_t initiate_ike_sa_job_t;
 
 /**
- * Object representing an INITIATE_IKE_SA Job
+ * @brief Class representing an INITIATE_IKE_SA Job.
+ * 
+ * This job is created if an IKE_SA should be iniated. This 
+ * happens form a user request, or via the kernel interface.
+ * 
+ * @b Constructors:
+ * - initiate_ike_sa_job_create()
  * 
  * @ingroup jobs
  */
@@ -39,14 +45,14 @@ struct initiate_ike_sa_job_t {
 	job_t job_interface;
 	
 	/**
-	 * @brief Returns the currently set configuration name for this job
+	 * @brief Returns the currently set configuration name for this job.
 	 * 	
 	 * @warning Returned name is not copied.
 	 * 
 	 * @param this 	calling initiate_ike_sa_job_t object
 	 * @return 		name of the configuration
 	 */
-	char * (*get_configuration_name) (initiate_ike_sa_job_t *this);
+	char *(*get_configuration_name) (initiate_ike_sa_job_t *this);
 
 	/**
 	 * @brief Destroys an initiate_ike_sa_job_t object.

Source/charon/queues/jobs/job.h

@@ -32,6 +32,8 @@ typedef enum job_type_t job_type_t;
 /**
  * @brief Definition of the various job types.
  * 
+ * @todo add more jobs, such as rekeying.
+ * 
  * @ingroup jobs
  */
 enum job_type_t {
@@ -52,8 +54,8 @@ enum job_type_t {
 	 * 
 	 * Job is implemented in class type initiate_ike_sa_job_t
 	 */
-	
 	INITIATE_IKE_SA,
+	
 	/** 
 	 * Delete an ike sa which is still not established.
 	 * 
@@ -67,13 +69,12 @@ enum job_type_t {
 	 * Job is implemented in class type delete_established_ike_sa_job_t
 	 */	
 	DELETE_ESTABLISHED_IKE_SA
-	
-	
-	/* more job types have to be inserted here */
 };
 
 /**
  * string mappings for job_type_t
+ * 
+ * @ingroup jobs
  */
 extern mapping_t job_type_m[];
 
@@ -85,6 +86,9 @@ typedef struct job_t job_t;
  * 
  * A job consists of a job-type and one or more assigned values.
  * 
+ * @b Constructors:
+ * - None, use specific implementation of the interface.
+ * 
  * @ingroup jobs
  */
 struct job_t {

Source/charon/queues/jobs/retransmit_request_job.h

@@ -31,7 +31,14 @@
 typedef struct retransmit_request_job_t retransmit_request_job_t;
 
 /**
- * Object representing an RETRANSMIT_REQUEST Job.
+ * @brief Class representing an RETRANSMIT_REQUEST Job.
+ * 
+ * This job is scheduled every time a request is sent over the
+ * wire. If the response to the request is not received at schedule
+ * time, the retransmission will be initiated.
+ * 
+ * @b Constructors:
+ * - retransmit_request_job_create()
  * 
  * @ingroup jobs
  */

Source/charon/queues/send_queue.c

@@ -30,7 +30,7 @@
 
 typedef struct private_send_queue_t private_send_queue_t;
 
- /**
+/**
  * @brief Private Variables and Functions of send_queue class
  *
  */
@@ -70,7 +70,7 @@ static int get_count(private_send_queue_t *this)
 	return count;
 }
 
- /**
+/**
  * implements send_queue_t.get
  */
 static packet_t *get(private_send_queue_t *this)
@@ -96,7 +96,7 @@ static packet_t *get(private_send_queue_t *this)
 	return packet;
 }
 
- /**
+/**
  * implements send_queue_t.add
  */
 static void add(private_send_queue_t *this, packet_t *packet)
@@ -107,7 +107,7 @@ static void add(private_send_queue_t *this, packet_t *packet)
 	pthread_mutex_unlock(&(this->mutex));
 }
 
- /**
+/**
  * implements send_queue_t.destroy
  */
 static void destroy (private_send_queue_t *this)
@@ -133,7 +133,7 @@ static void destroy (private_send_queue_t *this)
 	allocator_free(this);
 }
 
- /*
+/*
  *
  * Documented in header
  */

Source/charon/queues/send_queue.h

@@ -30,11 +30,15 @@
 typedef struct send_queue_t send_queue_t;
 
 /**
- * @brief Send-Queue
- *
+ * @brief The send queue stores packet for the sender_t instance.
+ * 
+ * The sender_t will send them consequently over the wire.
  * Although the send-queue is based on a linked_list_t
  * all access functions are thread-save implemented.
  * 
+ * @b Constructors:
+ * - send_queue_create()
+ * 
  * @ingroup queues
  */
 struct send_queue_t {
@@ -87,7 +91,7 @@ struct send_queue_t {
 /**
  * @brief Creates an empty send_queue_t.
  *
- * @return send_queue_t empty send_queue_t
+ * @return send_queue_t object
  * 
  * @ingroup queues
  */