- docs updated
[strongswan.git] / Source / charon / queues / job_queue.h
index b0a3066..9fcf080 100644 (file)
@@ -1,7 +1,7 @@
 /**
  * @file job_queue.h
  *
- * @brief Interface of job_queue_t-
+ * @brief Interface of job_queue_t.
  *
  */
 
 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
+ * 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
@@ -45,45 +52,47 @@ 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.
         *
         * @param job_queue_t   calling object
         * @param[out] job              pointer to a job pointer where to job is returned to
-        * @return                              job
+        * @return                              next job
         */
        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
         * removes the job.
         *
-        * @param job_queue_t calling object
-        * @param[in] job job to add to the queue (job is not copied)
+        * @param job_queue_t   calling object
+        * @param job                   job to add to the queue (job is not copied)
         */
        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
         * after calling this function.
         *
-        * @param job_queue_t calling object
+        * @param job_queue_t   calling object
         */
        void (*destroy) (job_queue_t *job_queue);
 };
 
 /**
- * @brief Creates an empty job_queue
+ * @brief Creates an empty job_queue.
  *
- * @return job_queue_t empty job_queue
+ * @return job_queue_t object
+ * 
+ * @ingroup queues
  */
 job_queue_t *job_queue_create();