-playing with doxygen groups

1 files changed, 47 insertions, 43 deletions

diff --git a/src/include/gnunet_scheduler_lib.h b/src/include/gnunet_scheduler_lib.h
index c482a000c..110c0ce77 100644
--- a/src/include/gnunet_scheduler_lib.h
+++ b/src/include/gnunet_scheduler_lib.h
@@ -22,6 +22,8 @@
  * @file include/gnunet_scheduler_lib.h
  * @brief API to schedule computations using continuation passing style
  * @author Christian Grothoff
+ * @defgroup scheduler Event loop (scheduler)
+ * @{
  */
 
 #ifndef GNUNET_SCHEDULER_LIB_H
@@ -198,29 +200,29 @@ typedef void (*GNUNET_SCHEDULER_Task) (void *cls,
 
 /**
  * Signature of the select function used by the scheduler.
- * GNUNET_NETWORK_socket_select matches it.
+ * #GNUNET_NETWORK_socket_select matches it.
  *
  * @param cls closure
  * @param rfds set of sockets to be checked for readability
  * @param wfds set of sockets to be checked for writability
  * @param efds set of sockets to be checked for exceptions
  * @param timeout relative value when to return
- * @return number of selected sockets, GNUNET_SYSERR on error
+ * @return number of selected sockets, #GNUNET_SYSERR on error
  */
 typedef int (*GNUNET_SCHEDULER_select) (void *cls,
-                                        struct GNUNET_NETWORK_FDSet * rfds,
-                                        struct GNUNET_NETWORK_FDSet * wfds,
-                                        struct GNUNET_NETWORK_FDSet * efds,
+                                        struct GNUNET_NETWORK_FDSet *rfds,
+                                        struct GNUNET_NETWORK_FDSet *wfds,
+                                        struct GNUNET_NETWORK_FDSet *efds,
                                         struct GNUNET_TIME_Relative timeout);
 
 
 /**
  * Initialize and run scheduler.  This function will return when all
  * tasks have completed.  On systems with signals, receiving a SIGTERM
- * (and other similar signals) will cause "GNUNET_SCHEDULER_shutdown"
+ * (and other similar signals) will cause #GNUNET_SCHEDULER_shutdown
  * to be run after the active task is complete.  As a result, SIGTERM
  * causes all active tasks to be scheduled with reason
- * "GNUNET_SCHEDULER_REASON_SHUTDOWN".  (However, tasks added
+ * #GNUNET_SCHEDULER_REASON_SHUTDOWN.  (However, tasks added
  * afterwards will execute normally!).  Note that any particular
  * signal will only shut down one scheduler; applications should
  * always only create a single scheduler.
@@ -249,7 +251,7 @@ GNUNET_SCHEDULER_shutdown (void);
  * dropped (if the decision should be made based on the number of
  * tasks ready to run).
  *
- * * @param p priority-level to query, use KEEP to query the level
+ * @param p priority-level to query, use KEEP to query the level
  *          of the current task, use COUNT to get the sum over
  *          all priority levels
  * @return number of tasks pending right now
@@ -263,7 +265,7 @@ GNUNET_SCHEDULER_get_load (enum GNUNET_SCHEDULER_Priority p);
  * started.  Will return the same value as
  * the GNUNET_SCHEDULER_TaskContext's reason field.
  *
- * * @return reason(s) why the current task is run
+ * @return reason(s) why the current task is run
  */
 enum GNUNET_SCHEDULER_Reason
 GNUNET_SCHEDULER_get_reason (void);
@@ -273,7 +275,7 @@ GNUNET_SCHEDULER_get_reason (void);
  * Cancel the task with the specified identifier.
  * The task must not yet have run.
  *
- * * @param task id of the task to cancel
+ * @param task id of the task to cancel
  * @return the closure of the callback of the cancelled task
  */
 void *
@@ -285,7 +287,7 @@ GNUNET_SCHEDULER_cancel (GNUNET_SCHEDULER_TaskIdentifier task);
  * similar to the other "add" functions except that there is no delay
  * and the reason code can be specified.
  *
- * * @param task main function of the task
+ * @param task main function of the task
  * @param task_cls closure of task
  * @param reason reason for task invocation
  */
@@ -300,7 +302,7 @@ GNUNET_SCHEDULER_add_continuation (GNUNET_SCHEDULER_Task task, void *task_cls,
  * and the reason code can be specified.
  *
  * @param task main function of the task
- * @param task_cls closure for 'main'
+ * @param task_cls closure for @a task
  * @param reason reason for task invocation
  * @param priority priority to use for the task
  */
@@ -313,11 +315,11 @@ GNUNET_SCHEDULER_add_continuation_with_priority (GNUNET_SCHEDULER_Task task, voi
 /**
  * Schedule a new task to be run with a specified priority.
  *
- * * @param prio how important is the new task?
+ * @param prio how important is the new task?
  * @param task main function of the task
- * @param task_cls closure of task
+ * @param task_cls closure of @a task
  * @return unique task identifier for the job
- *         only valid until "task" is started!
+ *         only valid until @a task is started!
  */
 GNUNET_SCHEDULER_TaskIdentifier
 GNUNET_SCHEDULER_add_with_priority (enum GNUNET_SCHEDULER_Priority prio,
@@ -328,10 +330,10 @@ GNUNET_SCHEDULER_add_with_priority (enum GNUNET_SCHEDULER_Priority prio,
  * Schedule a new task to be run as soon as possible. The task
  * will be run with the DEFAULT priority.
  *
- * * @param task main function of the task
- * @param task_cls closure of task
+ * @param task main function of the task
+ * @param task_cls closure of @a task
  * @return unique task identifier for the job
- *         only valid until "task" is started!
+ *         only valid until @a task is started!
  */
 GNUNET_SCHEDULER_TaskIdentifier
 GNUNET_SCHEDULER_add_now (GNUNET_SCHEDULER_Task task, void *task_cls);
@@ -345,11 +347,11 @@ GNUNET_SCHEDULER_add_now (GNUNET_SCHEDULER_Task task, void *task_cls);
  * not count for the 'lifeness' of the process.  This API is only
  * useful in a few special cases.
  *
- * @param lifeness GNUNET_YES if the task counts for lifeness, GNUNET_NO if not.
+ * @param lifeness #GNUNET_YES if the task counts for lifeness, #GNUNET_NO if not.
  * @param task main function of the task
- * @param task_cls closure of task
+ * @param task_cls closure of @a task
  * @return unique task identifier for the job
- *         only valid until "task" is started!
+ *         only valid until @a task is started!
  */
 GNUNET_SCHEDULER_TaskIdentifier
 GNUNET_SCHEDULER_add_now_with_lifeness (int lifeness,
@@ -363,11 +365,11 @@ GNUNET_SCHEDULER_add_now_with_lifeness (int lifeness,
  * will be run with the DEFAULT priority.
  *
  * * @param delay when should this operation time out? Use
- *        GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
+ *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
  * @param task main function of the task
- * @param task_cls closure of task
+ * @param task_cls closure of @a task
  * @return unique task identifier for the job
- *         only valid until "task" is started!
+ *         only valid until @a task is started!
  */
 GNUNET_SCHEDULER_TaskIdentifier
 GNUNET_SCHEDULER_add_delayed (struct GNUNET_TIME_Relative delay,
@@ -379,12 +381,12 @@ GNUNET_SCHEDULER_add_delayed (struct GNUNET_TIME_Relative delay,
  * will be scheduled for execution once the delay has expired.
  *
  * @param delay when should this operation time out? Use
- *        GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
+ *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
  * @param priority priority to use for the task
  * @param task main function of the task
- * @param task_cls closure of task
+ * @param task_cls closure of @a task
  * @return unique task identifier for the job
- *         only valid until "task" is started!
+ *         only valid until @a task is started!
  */
 GNUNET_SCHEDULER_TaskIdentifier
 GNUNET_SCHEDULER_add_delayed_with_priority (struct GNUNET_TIME_Relative delay,
@@ -400,12 +402,12 @@ GNUNET_SCHEDULER_add_delayed_with_priority (struct GNUNET_TIME_Relative delay,
  * socket operation is ready.  It will be run with the DEFAULT priority.
  *
  * * @param delay when should this operation time out? Use
- *        GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
+ *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
  * @param rfd read file-descriptor
  * @param task main function of the task
- * @param task_cls closure of task
+ * @param task_cls closure of @a task
  * @return unique task identifier for the job
- *         only valid until "task" is started!
+ *         only valid until @a task is started!
  */
 GNUNET_SCHEDULER_TaskIdentifier
 GNUNET_SCHEDULER_add_read_net (struct GNUNET_TIME_Relative delay,
@@ -422,13 +424,13 @@ GNUNET_SCHEDULER_add_read_net (struct GNUNET_TIME_Relative delay,
  * will be run with the DEFAULT priority.
  *
  * @param delay when should this operation time out? Use
- *        GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
+ *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
  * @param priority priority to use for the task
  * @param rfd read file-descriptor
  * @param task main function of the task
- * @param task_cls closure of task
+ * @param task_cls closure of @a task
  * @return unique task identifier for the job
- *         only valid until "task" is started!
+ *         only valid until @a task is started!
  */
 GNUNET_SCHEDULER_TaskIdentifier
 GNUNET_SCHEDULER_add_read_net_with_priority (struct GNUNET_TIME_Relative delay,
@@ -445,12 +447,12 @@ GNUNET_SCHEDULER_add_read_net_with_priority (struct GNUNET_TIME_Relative delay,
  * socket operation is ready.  It will be run with the DEFAULT priority.
  *
  * * @param delay when should this operation time out? Use
- *        GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
+ *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
  * @param wfd write file-descriptor
  * @param task main function of the task
- * @param task_cls closure of task
+ * @param task_cls closure of @a task
  * @return unique task identifier for the job
- *         only valid until "task" is started!
+ *         only valid until @a task is started!
  */
 GNUNET_SCHEDULER_TaskIdentifier
 GNUNET_SCHEDULER_add_write_net (struct GNUNET_TIME_Relative delay,
@@ -466,10 +468,10 @@ GNUNET_SCHEDULER_add_write_net (struct GNUNET_TIME_Relative delay,
  * socket operation is ready. It will be run with the DEFAULT priority.
  *
  * * @param delay when should this operation time out? Use
- *        GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
+ *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
  * @param rfd read file-descriptor
  * @param task main function of the task
- * @param task_cls closure of task
+ * @param task_cls closure of @a task
  * @return unique task identifier for the job
  *         only valid until "task" is started!
  */
@@ -487,12 +489,12 @@ GNUNET_SCHEDULER_add_read_file (struct GNUNET_TIME_Relative delay,
  * socket operation is ready. It will be run with the DEFAULT priority.
  *
  * * @param delay when should this operation time out? Use
- *        GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
+ *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
  * @param wfd write file-descriptor
  * @param task main function of the task
- * @param task_cls closure of task
+ * @param task_cls closure of @a task
  * @return unique task identifier for the job
- *         only valid until "task" is started!
+ *         only valid until @a task is started!
  */
 GNUNET_SCHEDULER_TaskIdentifier
 GNUNET_SCHEDULER_add_write_file (struct GNUNET_TIME_Relative delay,
@@ -518,12 +520,12 @@ GNUNET_SCHEDULER_add_write_file (struct GNUNET_TIME_Relative delay,
  * </code>
  *
  * @param prio how important is this task?
- * @param delay how long should we wait? Use GNUNET_TIME_UNIT_FOREVER_REL for "forever",
+ * @param delay how long should we wait? Use #GNUNET_TIME_UNIT_FOREVER_REL for "forever",
  *        which means that the task will only be run after we receive SIGTERM
  * @param rs set of file descriptors we want to read (can be NULL)
  * @param ws set of file descriptors we want to write (can be NULL)
  * @param task main function of the task
- * @param task_cls closure of task
+ * @param task_cls closure of @a task
  * @return unique task identifier for the job
  *         only valid until "task" is started!
  */
@@ -545,6 +547,8 @@ GNUNET_SCHEDULER_set_select (GNUNET_SCHEDULER_select new_select,
                              void *new_select_cls);
 
 
+/** @} */ /* end of group scheduler */
+
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
 #endif