Convert existing documentation to doxygen format.

This patch modifies most of the existing comments in header files to be
in a format that doxygen can interpret.  This provides another
significant improvement to the web/pdf/etc generated documentation
without having to add new content.

Signed-off-by: Russell Bryant <russell@russellbryant.net>
Reviewed-by: Angus Salkeld <asalkeld@redhat.com>

exec/main.h

@@ -32,6 +32,13 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  * THE POSSIBILITY OF SUCH DAMAGE.
  */
+
+/**
+ * @file
+ *
+ * @warning DO NOT USE SYMBOLS IN THIS FILE
+ */
+
 #ifndef MAIN_H_DEFINED
 #define MAIN_H_DEFINED
 
@@ -45,9 +52,6 @@
 #include <corosync/engine/config.h>
 #include <corosync/engine/coroapi.h>
 
-/*
- * DO NOT USE SYMBOLS IN THIS FILE
- */
 extern unsigned long long *(*main_clm_get_by_nodeid) (unsigned int node_id);
 
 extern void main_get_config_modules(struct config_iface_ver0 ***modules, int *num);

exec/mainconfig.h

@@ -40,7 +40,7 @@
 #include <corosync/list.h>
 #include <corosync/engine/coroapi.h>
 
-/*
+/**
  * All service handlers in the AIS
  */
 struct dynamic_service {
@@ -51,7 +51,7 @@ struct dynamic_service {
 };
 #define MAX_DYNAMIC_SERVICES 128
 
-/*
+/**
  * Structure describing cached uidgid item
  */
 struct uidgid_item {

exec/service.h

@@ -36,17 +36,18 @@
 #define COROSYNC_SERVICE_H_DEFINED
 
 #include <corosync/hdb.h>
-/*
- * Link and initialize a service
- */
+
 struct corosync_api_v1;
 
+/**
+ * Link and initialize a service
+ */
 extern unsigned int corosync_service_link_and_init (
 	struct corosync_api_v1 *objdb,
 	const char *service_name,
 	unsigned int service_ver);
 
-/*
+/**
  * Unlink and exit a service
  */
 extern unsigned int corosync_service_unlink_and_exit (
@@ -54,14 +55,14 @@ extern unsigned int corosync_service_unlink_and_exit (
 	const char *service_name,
 	unsigned int service_ver);
 
-/*
+/**
  * Unlink and exit all corosync services
  */
 extern void corosync_service_unlink_all (
 	struct corosync_api_v1 *api,
 	void (*unlink_all_complete) (void));
 
-/*
+/**
  * Load all of the default services
  */
 extern unsigned int corosync_service_defaults_link_and_init (

exec/tlist.h

@@ -243,7 +243,7 @@ static inline void timerlist_post_dispatch (struct timerlist *timerlist, timer_h
 	free (timer);
 }
 
-/*
+/**
  * returns the number of msec until the next timer will expire for use with poll
  */
 static inline unsigned long long timerlist_msec_duration_to_expire (struct timerlist *timerlist)
@@ -280,7 +280,7 @@ static inline unsigned long long timerlist_msec_duration_to_expire (struct timer
 	return (msec_duration_to_expire);
 }
 
-/*
+/**
  * Expires any timers that should be expired
  */
 static inline void timerlist_expire (struct timerlist *timerlist)

exec/totemiba.h

@@ -40,7 +40,7 @@
 
 #include <corosync/totem/totem.h>
 
-/*
+/**
  * Create an instance
  */
 extern int totemiba_initialize (

exec/totemmrp.h

@@ -32,16 +32,20 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  * THE POSSIBILITY OF SUCH DAMAGE.
  */
+
+/**
+ * @file
+ * Totem Single Ring Protocol
+ *
+ * depends on poll abstraction, POSIX, IPV4
+ */
+
 #ifndef TOTEMMRP_H_DEFINED
 #define TOTEMMRP_H_DEFINED
 
 #include <corosync/totem/totem.h>
 
-/*
- * Totem Single Ring Protocol
- * depends on poll abstraction, POSIX, IPV4
- */
-/*
+/**
  * Initialize the logger
  */
 extern void totemmrp_log_printf_init (
@@ -52,7 +56,7 @@ extern void totemmrp_log_printf_init (
 	int log_level_notice,
 	int log_level_debug);
 
-/*
+/**
  * Initialize the group messaging interface
  */
 extern int totemmrp_initialize (
@@ -74,7 +78,7 @@ extern int totemmrp_initialize (
 
 extern void totemmrp_finalize (void);
 
-/*
+/**
  * Multicast a message
  */
 extern int totemmrp_mcast (
@@ -82,7 +86,7 @@ extern int totemmrp_mcast (
 	unsigned int iov_len,
 	int priority);
 
-/*
+/**
  * Return number of available messages that can be queued
  */
 extern int totemmrp_avail (void);

exec/totemnet.h

@@ -32,6 +32,14 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  * THE POSSIBILITY OF SUCH DAMAGE.
  */
+
+/**
+ * @file
+ * Totem Network interface - also does encryption/decryption
+ *
+ * depends on poll abstraction, POSIX, IPV4
+ */
+
 #ifndef TOTEMNET_H_DEFINED
 #define TOTEMNET_H_DEFINED
 
@@ -42,12 +50,8 @@
 
 #define TOTEMNET_NOFLUSH	0
 #define TOTEMNET_FLUSH		1
-/*
- * Totem Network interface - also does encryption/decryption
- * depends on poll abstraction, POSIX, IPV4
- */
 
-/*
+/**
  * Create an instance
  */
 extern int totemnet_initialize (

exec/totemrrp.h

@@ -32,6 +32,14 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  * THE POSSIBILITY OF SUCH DAMAGE.
  */
+
+/**
+ * @file
+ * Totem Network interface - also does encryption/decryption
+ *
+ * depends on poll abstraction, POSIX, IPV4
+ */
+
 #ifndef TOTEMRRP_H_DEFINED
 #define TOTEMRRP_H_DEFINED
 
@@ -43,12 +51,7 @@
 #define TOTEMRRP_NOFLUSH	0
 #define TOTEMRRP_FLUSH		1
 
-/*
- * Totem Network interface - also does encryption/decryption
- * depends on poll abstraction, POSIX, IPV4
- */
-
-/*
+/**
  * Create an instance
  */
 extern int totemrrp_initialize (

exec/totemsrp.h

@@ -32,18 +32,21 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  * THE POSSIBILITY OF SUCH DAMAGE.
  */
+
+/**
+ * @file
+ * Totem Single Ring Protocol
+ *
+ * depends on poll abstraction, POSIX, IPV4
+ */
+
 #ifndef TOTEMSRP_H_DEFINED
 #define TOTEMSRP_H_DEFINED
 
 #include <corosync/totem/totem.h>
 #include <corosync/totem/coropoll.h>
 
-/*
- * Totem Single Ring Protocol
- * depends on poll abstraction, POSIX, IPV4
- */
-
-/*
+/**
  * Create a protocol instance
  */
 int totemsrp_initialize (
@@ -66,7 +69,7 @@ int totemsrp_initialize (
 
 void totemsrp_finalize (void *srp_context);
 
-/*
+/**
  * Multicast a message
  */
 int totemsrp_mcast (
@@ -75,7 +78,7 @@ int totemsrp_mcast (
 	unsigned int iov_len,
 	int priority);
 
-/*
+/**
  * Return number of available messages that can be queued
  */
 int totemsrp_avail (void *srp_context);

exec/totemudp.h

@@ -41,7 +41,7 @@
 
 #include <corosync/totem/totem.h>
 
-/*
+/**
  * Create an instance
  */
 extern int totemudp_initialize (

exec/totemudpu.h

@@ -41,7 +41,7 @@
 
 #include <corosync/totem/totem.h>
 
-/*
+/**
  * Create an instance
  */
 extern int totemudpu_initialize (

exec/util.h

@@ -38,7 +38,7 @@
 #include <sys/time.h>
 #include <corosync/corotypes.h>
 
-/*
+/**
  * Get the time of day and convert to nanoseconds
  */
 extern cs_time_t clust_time_now(void);
@@ -86,7 +86,7 @@ static inline cs_error_t hdb_error_to_cs (int res)		\
 	}							\
 }
 
-/*
+/**
  * Compare two names.  returns non-zero on match.
  */
 extern int name_match(cs_name_t *name1, cs_name_t *name2);

exec/vsf.h

@@ -37,7 +37,7 @@
 struct corosync_api_v1;
 struct corosync_vsf_iface_ver0 {
 
-	/*
+	/**
 	 * Executes a callback whenever component changes
 	 */
 	int (*init) (
@@ -48,8 +48,9 @@ struct corosync_vsf_iface_ver0 {
 		int primary_designated,
 		struct memb_ring_id *ring_id));
 
-	/*
-	 * Returns 1 if we are primary component, 0 if not
+	/**
+	 * @retval 1 if we are primary component
+	 * @retval 0 if not primary component
 	 */
 	int (*primary) (void);
 };

include/corosync/cfg.h

@@ -82,14 +82,23 @@ typedef enum {
 	COROSYNC_CFG_STATETYPE_PRESENCE = 4
 } corosync_cfg_state_type_t;
 
-/* Shutdown types.
-   REQUEST is the normal shutdown. other daemons will be consulted
-   REGARDLESS will tell other daemons but ignore their opinions
-   IMMEDIATE will shut down straight away (but still tell other nodes)
-*/
+/**
+ * Shutdown types.
+ */
 typedef enum {
+	/**
+	 * REQUEST is the normal shutdown.
+	 *        Other daemons will be consulted.
+	 */
 	COROSYNC_CFG_SHUTDOWN_FLAG_REQUEST = 0,
+	/**
+	 * REGARDLESS will tell other daemons but ignore their opinions.
+	 */
 	COROSYNC_CFG_SHUTDOWN_FLAG_REGARDLESS = 1,
+	/**
+	 * IMMEDIATE will shut down straight away
+	 *        (but still tell other nodes).
+	 */
 	COROSYNC_CFG_SHUTDOWN_FLAG_IMMEDIATE = 2,
 } corosync_cfg_shutdown_flags_t;
 
@@ -122,8 +131,9 @@ typedef struct {
 	corosync_cfg_shutdown_callback_t corosync_cfg_shutdown_callback;
 } corosync_cfg_callbacks_t;
 
-/*
+/**
  * A node address. This is a complete sockaddr_in[6]
+ *
  * To explain:
  *  If you cast cna_address to a 'struct sockaddr', the sa_family field
  *  will be AF_INET or AF_INET6. Armed with that knowledge you can then
@@ -133,7 +143,7 @@ typedef struct {
  */
 typedef struct
 {
-	int address_length; /* FIXME: set but never used */
+	int address_length; /**< @todo FIXME: set but never used */
 	char address[sizeof(struct sockaddr_in6)];
 } corosync_cfg_node_address_t;
 

include/corosync/confdb.h

@@ -118,21 +118,21 @@ typedef struct {
 
 /** @} */
 
-/*
+/**
  * Create a new confdb connection
  */
 cs_error_t confdb_initialize (
 	confdb_handle_t *handle,
 	confdb_callbacks_t *callbacks);
 
-/*
+/**
  * Close the confdb handle
  */
 cs_error_t confdb_finalize (
 	confdb_handle_t handle);
 
 
-/*
+/**
  * Write back the configuration
  */
 cs_error_t confdb_write (
@@ -140,7 +140,7 @@ cs_error_t confdb_write (
 	char *error_text,
 	size_t errbuf_len);
 
-/*
+/**
  * Reload the configuration
  */
 cs_error_t confdb_reload (
@@ -149,22 +149,23 @@ cs_error_t confdb_reload (
 	char *error_text,
 	size_t errbuf_len);
 
-/*
- * Get a file descriptor on which to poll.  confdb_handle_t is NOT a
- * file descriptor and may not be used directly.
+/**
+ * Get a file descriptor on which to poll.
+ *
+ * confdb_handle_t is NOT a file descriptor and may not be used directly.
  */
 cs_error_t confdb_fd_get (
 	confdb_handle_t handle,
 	int *fd);
 
-/*
+/**
  * Dispatch configuration changes
  */
 cs_error_t confdb_dispatch (
 	confdb_handle_t handle,
 	cs_dispatch_flags_t dispatch_types);
 
-/*
+/**
  * Change notification
  */
 cs_error_t confdb_track_changes (
@@ -175,7 +176,7 @@ cs_error_t confdb_track_changes (
 cs_error_t confdb_stop_track_changes (
 	confdb_handle_t handle);
 
-/*
+/**
  * Manipulate objects
  */
 cs_error_t confdb_object_create (
@@ -200,7 +201,7 @@ cs_error_t confdb_object_name_get (
 	char *object_name,
 	size_t *object_name_len);
 
-/*
+/**
  * Manipulate keys
  */
 cs_error_t confdb_key_create (
@@ -227,7 +228,7 @@ cs_error_t confdb_key_delete (
 	const void *value,
 	size_t value_len);
 
-/*
+/**
  * Key queries
  */
 cs_error_t confdb_key_get (
@@ -270,10 +271,12 @@ cs_error_t confdb_key_decrement (
 	size_t key_name_len,
 	unsigned int *value);
 
-/*
+/**
  * Object queries
+ *
  * "find" loops through all objects of a given name and is also
  * a quick way of finding a specific object,
+ *
  * "iter" returns each object in sequence.
  */
 cs_error_t confdb_object_find_start (
@@ -306,7 +309,7 @@ cs_error_t confdb_object_iter_destroy(
 	confdb_handle_t handle,
 	hdb_handle_t parent_object_handle);
 
-/*
+/**
  * Key iterator
  */
 cs_error_t confdb_key_iter_start (
@@ -329,14 +332,16 @@ cs_error_t confdb_key_iter_typed (
 	size_t *value_len,
 	confdb_value_types_t *type);
 
-/*
- * Get/set context variable
+/**
+ * Get context variable
  */
-
 cs_error_t confdb_context_get (
 	confdb_handle_t handle,
 	const void **context);
 
+/**
+ * Set context variable
+ */
 cs_error_t confdb_context_set (
 	confdb_handle_t handle,
 	const void *context);

include/corosync/cpg.h

@@ -52,15 +52,15 @@ typedef uint64_t cpg_handle_t;
 typedef uint64_t cpg_iteration_handle_t;
 
 typedef enum {
-	CPG_TYPE_UNORDERED, /* not implemented */
-	CPG_TYPE_FIFO,		/* same as agreed */
+	CPG_TYPE_UNORDERED, /**< not implemented */
+	CPG_TYPE_FIFO,      /**< same as agreed */
 	CPG_TYPE_AGREED,
-	CPG_TYPE_SAFE		/* not implemented */
+	CPG_TYPE_SAFE       /**< not implemented */
 } cpg_guarantee_t;
 
 typedef enum {
-	CPG_FLOW_CONTROL_DISABLED,	/* flow control is disabled - new messages may be sent */
-	CPG_FLOW_CONTROL_ENABLED	/* flow control is enabled - new messages should not be sent */
+	CPG_FLOW_CONTROL_DISABLED, /**< flow control is disabled - new messages may be sent */
+	CPG_FLOW_CONTROL_ENABLED   /**< flow control is enabled - new messages should not be sent */
 } cpg_flow_control_state_t;
 
 
@@ -112,7 +112,7 @@ typedef void (*cpg_deliver_fn_t) (
 	const struct cpg_name *group_name,
 	uint32_t nodeid,
 	uint32_t pid,
-	/*
+	/**
 	 * Unlike many "msg" pointers, this one is deliberately *not*
 	 * declared const in order to permit in-place endian conversion.
 	 */
@@ -154,14 +154,14 @@ typedef struct {
 
 /** @} */
 
-/*
+/**
  * Create a new cpg connection
  */
 cs_error_t cpg_initialize (
 	cpg_handle_t *handle,
 	cpg_callbacks_t *callbacks);
 
-/*
+/**
  * Create a new cpg connection, initialize with model
  */
 cs_error_t cpg_model_initialize (
@@ -170,41 +170,46 @@ cs_error_t cpg_model_initialize (
 	cpg_model_data_t *model_data,
 	void *context);
 
-/*
+/**
  * Close the cpg handle
  */
 cs_error_t cpg_finalize (
 	cpg_handle_t handle);
 
-/*
- * Get a file descriptor on which to poll.  cpg_handle_t is NOT a
- * file descriptor and may not be used directly.
+/**
+ * Get a file descriptor on which to poll.
+ *
+ * cpg_handle_t is NOT a file descriptor and may not be used directly.
  */
 cs_error_t cpg_fd_get (
 	cpg_handle_t handle,
 	int *fd);
 
-/*
- * Get and set contexts for a CPG handle
+/**
+ * Get contexts for a CPG handle
  */
 cs_error_t cpg_context_get (
 	cpg_handle_t handle,
 	void **context);
 
+/**
+ * Set contexts for a CPG handle
+ */
 cs_error_t cpg_context_set (
 	cpg_handle_t handle,
 	void *context);
 
 
-/*
+/**
  * Dispatch messages and configuration changes
  */
 cs_error_t cpg_dispatch (
 	cpg_handle_t handle,
 	cs_dispatch_flags_t dispatch_types);
 
-/*
+/**
  * Join one or more groups.
+ *
  * messages multicasted with cpg_mcast_joined will be sent to every
  * group that has been joined on handle handle.  Any message multicasted
  * to a group that has been previously joined will be delivered in cpg_dispatch
@@ -213,17 +218,21 @@ cs_error_t cpg_join (
 	cpg_handle_t handle,
 	const struct cpg_name *group);
 
-/*
+/**
  * Leave one or more groups
  */
 cs_error_t cpg_leave (
 	cpg_handle_t handle,
 	const struct cpg_name *group);
 
-/*
+/**
  * Multicast to groups joined with cpg_join.
- * The iovec described by iovec will be multicasted to all groups joined with
- * the cpg_join interface for handle.
+ *
+ * @param handle
+ * @param guarantee
+ * @param iovec This iovec will be multicasted to all groups joined with
+ *              the cpg_join interface for handle.
+ * @param iov_len
  */
 cs_error_t cpg_mcast_joined (
 	cpg_handle_t handle,
@@ -231,7 +240,7 @@ cs_error_t cpg_mcast_joined (
 	const struct iovec *iovec,
 	unsigned int iov_len);
 
-/*
+/**
  * Get membership information from cpg
  */
 cs_error_t cpg_membership_get (
@@ -263,7 +272,7 @@ cs_error_t cpg_zcb_mcast_joined (
 	void *msg,
 	size_t msg_len);
 
-/*
+/**
  * Iteration
  */
 cs_error_t cpg_iteration_initialize(

include/corosync/evs.h

@@ -92,47 +92,52 @@ typedef struct {
 
 /** @} */
 
-/*
+/**
  * Create a new evs connection
  */
 cs_error_t evs_initialize (
 	evs_handle_t *handle,
 	evs_callbacks_t *callbacks);
 
-/*
+/**
  * Close the evs handle
  */
 cs_error_t evs_finalize (
 	evs_handle_t handle);
 
-/*
- * Get a file descriptor on which to poll.  evs_handle_t is NOT a
- * file descriptor and may not be used directly.
+/**
+ * Get a file descriptor on which to poll.
+ *
+ * evs_handle_t is NOT a file descriptor and may not be used directly.
  */
 cs_error_t evs_fd_get (
 	evs_handle_t handle,
 	int *fd);
 
-/*
- * Get and set contexts for a EVS handle
+/**
+ * Get contexts for a EVS handle
  */
 cs_error_t evs_context_get (
 	evs_handle_t handle,
 	void **context);
 
+/**
+ * Set contexts for a EVS handle
+ */
 cs_error_t evs_context_set (
 	evs_handle_t handle,
 	void *context);
 
-/*
+/**
  * Dispatch messages and configuration changes
  */
 cs_error_t evs_dispatch (
 	evs_handle_t handle,
 	cs_dispatch_flags_t dispatch_types);
 
-/*
+/**
  * Join one or more groups.
+ *
  * messages multicasted with evs_mcast_joined will be sent to every
  * group that has been joined on handle handle.  Any message multicasted
  * to a group that has been previously joined will be delivered in evs_dispatch
@@ -142,7 +147,7 @@ cs_error_t evs_join (
 	const struct evs_group *groups,
 	size_t group_cnt);
 
-/*
+/**
  * Leave one or more groups
  */
 cs_error_t evs_leave (
@@ -150,10 +155,14 @@ cs_error_t evs_leave (
 	const struct evs_group *groups,
 	size_t group_cnt);
 
-/*
+/**
  * Multicast to groups joined with evs_join.
- * The iovec described by iovec will be multicasted to all groups joined with
- * the evs_join interface for handle.
+ *
+ * @param handle
+ * @param guarantee
+ * @param iovec This iovec will be multicasted to all groups joined with
+ *              the evs_join interface for handle.
+ * @param iov_len
  */
 cs_error_t evs_mcast_joined (
 	evs_handle_t handle,
@@ -161,8 +170,9 @@ cs_error_t evs_mcast_joined (
 	const struct iovec *iovec,
 	unsigned int iov_len);
 
-/*
+/**
  * Multicast to specified groups.
+ *
  * Messages will be multicast to groups specified in the api call and not those
  * that have been joined (unless they are in the groups parameter).
  */
@@ -174,7 +184,7 @@ cs_error_t evs_mcast_groups (
 	const struct iovec *iovec,
 	unsigned int iov_len);
 
-/*
+/**
  * Get membership information from evs
  */
 cs_error_t evs_membership_get (

include/corosync/ipc_cpg.h

@@ -222,7 +222,9 @@ struct res_lib_cpg_mcast {
 	coroipc_response_header_t header __attribute__((aligned(8)));
 };
 
-/* Message from another node */
+/**
+ * Message from another node
+ */
 struct res_lib_cpg_deliver_callback {
 	coroipc_response_header_t header __attribute__((aligned(8)));
 	mar_cpg_name_t group_name __attribute__((aligned(8)));

include/corosync/lcr/lcr_ckpt.h

@@ -31,25 +31,26 @@
 #ifndef LCR_CKPT_H_DEFINED
 #define LCR_CKPT_H_DEFINED
 
-/*
+/**
  * Write data of length data_len into the section name for ckpt_handle
  */
 int lcr_ckpt_section_write (void *ckpt_handle, const char *name,
 			    const void *data, size_t data_len);
 
-/*
- * Read the section name into data with data len.  Returned in data_len is the
- * actual data read from ckpt_handle.
+/**
+ * Read the section name into data with data len.
+ *
+ * @retval Returned in data_len is the actual data read from ckpt_handle.
  */
 int lcr_ckpt_section_read (void *ckpt_handle, const char *name,
 			   void *data, size_t *data_len);
 
-/*
+/**
  * Initialize the section iterator to the first section
  */
 int lcr_ckpt_section_iterator_first (void *ckpt_handle);
 
-/*
+/**
  * Get the current section, return it in name, and advance to next section
  */
 int lcr_ckpt_section_iterator_next (void *ckpt_handle, char **name);

include/corosync/lcr/lcr_comp.h

@@ -31,27 +31,27 @@
 #ifndef LCR_COMP_H_DEFINED
 #define LCR_COMP_H_DEFINED
 
-/*
+/**
  * LCR Interface
  */
 struct lcr_iface {
-	const char *name;			/* Name of the interface */
-	int version;			/* Version of this interface */
-	int *versions_replace;		/* Versions that this interface can replace */
-	int versions_replace_count;	/* Count of entries in version_replace */
-	char **dependencies;		/* Dependent interfaces */
-	size_t dependency_count;	/* Count of entires in dependencies */
-	int (*constructor) (void *context);	/* Constructor for this interface */
-	void (*destructor) (void *context);	/* Constructor for this interface */
-	void **interfaces;		/* List of functions in interface */
+	const char *name;                   /**< Name of the interface */
+	int version;                        /**< Version of this interface */
+	int *versions_replace;              /**< Versions that this interface can replace */
+	int versions_replace_count;         /**< Count of entries in version_replace */
+	char **dependencies;                /**< Dependent interfaces */
+	size_t dependency_count;            /**< Count of entires in dependencies */
+	int (*constructor) (void *context); /**< Constructor for this interface */
+	void (*destructor) (void *context); /**< Constructor for this interface */
+	void **interfaces;                  /**< List of functions in interface */
 };
 
-/*
+/**
  * LCR Component
  */
 struct lcr_comp {
-	struct lcr_iface *ifaces;	/* List of interfaces in this component */
-	size_t iface_count;		/* size of ifaces list */
+	struct lcr_iface *ifaces; /**< List of interfaces in this component */
+	size_t iface_count;       /**< size of ifaces list */
 };
 
 extern void lcr_component_register (struct lcr_comp *comp);

include/corosync/list.h

@@ -31,10 +31,15 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  * THE POSSIBILITY OF SUCH DAMAGE.
  */
-/*
+
+/**
+ * @file
+ * Linked list API
+ *
  * This implementation uses the same API as the linux kernel to
  * help us kernel developers easily use the list primatives
  */
+
 #ifndef LIST_H_DEFINED
 #define LIST_H_DEFINED
 

include/corosync/pload.h

@@ -74,22 +74,23 @@ typedef struct {
 
 /** @} */
 
-/*
+/**
  * Create a new pload connection
  */
 pload_error_t pload_initialize (
 	pload_handle_t *handle,
 	pload_callbacks_t *callbacks);
 
-/*
+/**
  * Close the pload handle
  */
 pload_error_t pload_finalize (
 	pload_handle_t handle);
 
-/*
- * Get a file descriptor on which to poll.  pload_handle_t is NOT a
- * file descriptor and may not be used directly.
+/**
+ * Get a file descriptor on which to poll.
+ *
+ * @note pload_handle_t is NOT a file descriptor and may not be used directly.
  */
 pload_error_t pload_fd_get (
 	pload_handle_t handle,

include/corosync/quorum.h

@@ -60,29 +60,30 @@ typedef struct {
 } quorum_callbacks_t;
 
 
-/*
+/**
  * Create a new quorum connection
  */
 cs_error_t quorum_initialize (
 	quorum_handle_t *handle,
 	quorum_callbacks_t *callbacks);
 
-/*
+/**
  * Close the quorum handle
  */
 cs_error_t quorum_finalize (
 	quorum_handle_t handle);
 
 
-/*
- * Get a file descriptor on which to poll. quorum_handle_t is NOT a
- * file descriptor and may not be used directly.
+/**
+ * Get a file descriptor on which to poll.
+ *
+ * @note quorum_handle_t is NOT a file descriptor and may not be used directly.
  */
 cs_error_t quorum_fd_get (
 	quorum_handle_t handle,
 	int *fd);
 
-/*
+/**
  * Dispatch messages and configuration changes
  */
 cs_error_t quorum_dispatch (
@@ -90,14 +91,16 @@ cs_error_t quorum_dispatch (
 	cs_dispatch_flags_t dispatch_types);
 
 
-/*
+/**
  * Get quorum information.
  */
 cs_error_t quorum_getquorate (
 	quorum_handle_t handle,
 	int *quorate);
 
-/* Track node and quorum changes */
+/**
+ * Track node and quorum changes
+ */
 cs_error_t quorum_trackstart (
 	quorum_handle_t handle,
 	unsigned int flags );

include/corosync/sam.h

@@ -49,173 +49,193 @@ typedef enum {
 	SAM_RECOVERY_POLICY_CONFDB = 0x10,
 } sam_recovery_policy_t;
 
-/*
+/**
  * Callback definition for event driven checking
  */
 typedef int (*sam_hc_callback_t)(void);
 
-/*
- * Create a new SAM connection. This function must be called before any other.
+/**
+ * Create a new SAM connection.
+ *
+ * This function must be called before any other.
  * It is recommended to call it as one of first in application.
  *
  * @param time_interval Time interval in miliseconds of healthcheck. After this time, application
- * will be killed and recovery policy will be taken. This can be zero, which means,
- * that there is no time limit (only fall of application is checked and only then
- * recovery action is taken)
+ *        will be killed and recovery policy will be taken. This can be zero, which means,
+ *        that there is no time limit (only fall of application is checked and only then
+ *        recovery action is taken)
  * @param recovery_policy One of SAM_RECOVERY_POLICY_RESTART, which means, that after
- * timeout application will be killed and new instance will be started.
- * SAM_RECOVERY_POLICY_QUIT will just stop application
- * @return
- * - CS_OK in case no problem appeared
- * - CS_ERR_BAD_HANDLE in case user is trying to initialize initialized instance
- * - CS_ERR_INVALID_PARAM in case recovery_policy had bad value
+ *        timeout application will be killed and new instance will be started.
+ *        SAM_RECOVERY_POLICY_QUIT will just stop application
+ *
+ * @retval CS_OK in case no problem appeared
+ * @retval CS_ERR_BAD_HANDLE in case user is trying to initialize initialized instance
+ * @retval CS_ERR_INVALID_PARAM in case recovery_policy had bad value
  */
 cs_error_t sam_initialize (
         int time_interval,
         sam_recovery_policy_t recovery_policy);
 
-/*
- * Close the SAM handle. This function should be called as late as possible
+/**
+ * Close the SAM handle.
+ *
+ * This function should be called as late as possible.
  * (in reality, if you plan just quit, and checking is stopped, there is no need
  * to call it). Function will stop healtchecking and put library to state, where
  * no new start is possible.
  *
- * @return
- * - CS_OK in case no problem appeared
- * - CS_ERR_BAD_HANDLE library was not initialized by #sam_initialize
+ * @retval CS_OK in case no problem appeared
+ * @retval CS_ERR_BAD_HANDLE library was not initialized by #sam_initialize
  */
 cs_error_t sam_finalize (void);
 
-/*
- * Start healthchecking. From this time, you should call every time_interval
+/**
+ * Start healthchecking.
+ *
+ * From this time, you should call every time_interval
  * sam_hc_send, otherwise, recovery action will be taken.
- * @return
- * - CS_OK in case no problem appeared
- * - CS_ERR_BAD_HANDLE component was not registered by #sam_register
+ *
+ * @retval CS_OK in case no problem appeared
+ * @retval CS_ERR_BAD_HANDLE component was not registered by #sam_register
  */
 cs_error_t sam_start (void);
 
-/*
- * Stop healthchecking. Oposite of #sam_start. You can call sam_start and
- * sam_stop how many times you want.
+/**
+ * Stop healthchecking.
+ *
+ * Oposite of #sam_start. You can call sam_start and sam_stop how many
+ * times you want.
  *
- * @return
- * - CS_OK in case no problem appeared
- * - CS_ERR_BAD_HANDLE healthchecking is not in running state (no sam_start
- *   was called)
+ * @retval CS_OK in case no problem appeared
+ * @retval CS_ERR_BAD_HANDLE healthchecking is not in running state (no sam_start
+ *         was called)
  */
 cs_error_t sam_stop (void);
 
-/*
- * Set warning signal to be send. Default signal is SIGTERM. You can
- * use SIGKILL to emulate NOT sending warning signal and just send
- * SIGKILL.
- *
- * @return
- * - CS_OK in case no problem appeared
- * - CS_ERR_BAD_HANDLE library was not initialized by #sam_initialize or
- *   is finalized
+/**
+ * Set warning signal to be send.
+ *
+ * Default signal is SIGTERM. You can use SIGKILL to emulate NOT sending
+ * warning signal and just send SIGKILL.
+ *
+ * @retval CS_OK in case no problem appeared
+ * @retval CS_ERR_BAD_HANDLE library was not initialized by #sam_initialize or
+ *         is finalized
  */
 cs_error_t sam_warn_signal_set (int warn_signal);
 
-/*
- * Register application. This is one of most crucial function. In case, your
+/**
+ * Register application.
+ *
+ * This is one of most crucial function. In case, your
  * application will be restarted, you will always return to point after calling
  * this function. This function can be called only once, and SAM must be initialized
  * by sam_initialize. You can choose any place in your application, where to call
  * this function.
  *
  * @param instance_id NULL or pointer to int memory, where current instance
- * of application will be returned. It's always safe to suppose, that first instance
- * (this means, no recovery action was taken yet) will be always 1 and instance_id
- * will be raising up to MAX_INT (after this, it will fall to 0).
- * @return
- * - CS_OK in case no problem appeared
- * - CS_ERR_BAD_HANDLE in case, you call this function twice, or before sam_init
- * - CS_ERR_LIBRARY internal library call failed. This can be one of pipe or fork
- *   creation. You can get more information from errno
+ *        of application will be returned. It's always safe to suppose, that first instance
+ *        (this means, no recovery action was taken yet) will be always 1 and instance_id
+ *        will be raising up to MAX_INT (after this, it will fall to 0).
+ *
+ * @retval CS_OK in case no problem appeared
+ * @retval CS_ERR_BAD_HANDLE in case, you call this function twice, or before sam_init
+ * @retval CS_ERR_LIBRARY internal library call failed. This can be one of pipe or fork
+ *         creation. You can get more information from errno
  */
 cs_error_t sam_register (
 	unsigned int *instance_id);
 
-/*
- * Send healthcheck confirmation. This should be called after #sam_start
+/**
+ * Send healthcheck confirmation.
  *
- * - CS_OK in case no problem appeared
- * - CS_ERR_BAD_HANDLE healthchecking is not in running state (no sam_start was
- *   called, or called after sam_stop/sam_finalize)
+ * This should be called after #sam_start
+ *
+ * @retval CS_OK in case no problem appeared
+ * @retval CS_ERR_BAD_HANDLE healthchecking is not in running state (no sam_start was
+ *         called, or called after sam_stop/sam_finalize)
  */
 cs_error_t sam_hc_send (void);
 
-/*
- * Register healtcheck callback. After you will call this function, and set
+/**
+ * Register healtcheck callback.
+ *
+ * After you will call this function, and set
  * cb to something else then NULL, SAM is automatically switched from
  * application driven healtchecking to event driven healtchecking. In other
  * words, is not longer needed to call sam_hc_send, but your callback function
  * must return 0 in case of healtchecking is correct, or value different then
  * 0, in case something happend. After next hc iteration, warning signal and
  * after that kill signal is sent back to your application.
+ *
  * @param cb Pointer to healtcheck function, or NULL to switch back to application driven hc
- * @return
- * - CS_OK in case no problem appeared
- * - CS_ERR_BAD_HANDLE in case, you call this function before sam_init or after sam_start
- * - CS_ERR_LIBRARY internal library call failed. This can be one of pipe or pthread
- *   creation.
+ *
+ * @retval CS_OK in case no problem appeared
+ * @retval CS_ERR_BAD_HANDLE in case, you call this function before sam_init or after sam_start
+ * @retval CS_ERR_LIBRARY internal library call failed. This can be one of pipe or pthread
+ *         creation.
  */
 cs_error_t sam_hc_callback_register (sam_hc_callback_t cb);
 
-/*
+/**
  * Return size of stored data.
+ *
  * @param size Pointer to variable, where stored data size is returned. If
- * nothing or NULL is stored, then 0 is returned.
- * @return
- * - CS_OK in case no problem appeared
- * - CS_ERR_BAD_HANDLE in case you call this function before sam_init or after
- *   sam_finalize
- * - CS_ERR_INVALID_PARAM if size parameter is NULL
+ *        nothing or NULL is stored, then 0 is returned.
+ *
+ * @retval CS_OK in case no problem appeared
+ * @retval CS_ERR_BAD_HANDLE in case you call this function before sam_init or after
+ *         sam_finalize
+ * @retval CS_ERR_INVALID_PARAM if size parameter is NULL
  */
 cs_error_t sam_data_getsize (size_t *size);
 
-/*
+/**
  * Return stored data.
+ *
  * @param data Pointer to place, where to store data
  * @param size Allocated size of data
- * @return
- * - CS_OK if no problem appeared
- * - CS_ERR_BAD_HANDLE if you call this function before sam_init or after sam_finalize
- * - CS_ERR_INVALID_PARAM if data is NULL or size is less then currently saved user data length
+ *
+ * @retval CS_OK if no problem appeared
+ * @retval CS_ERR_BAD_HANDLE if you call this function before sam_init or after sam_finalize
+ * @retval CS_ERR_INVALID_PARAM if data is NULL or size is less then currently saved user data length
  */
 cs_error_t sam_data_restore (
 	void *data,
 	size_t size);
 
-/*
- * Store user data. Such stored data survives restart of child.
+/**
+ * Store user data.
+ *
+ * Such stored data survives restart of child.
+ *
  * @param data Data to store. You can use NULL to delete data
  * @param size Size of data to store.
- * @return
- * - CS_OK in case no problem appeared
- * - CS_ERR_BAD_HANDLE if you call this function before sam_init or
- *   after sam_finalize
- * - CS_ERR_NO_MEMORY if data is too large and malloc/realloc was not
- *   sucesfull
- * - CS_ERR_LIBRARY if some internal error appeared (communication with parent
- *   process)
+ *
+ * @retval CS_OK in case no problem appeared
+ * @retval CS_ERR_BAD_HANDLE if you call this function before sam_init or
+ *         after sam_finalize
+ * @retval CS_ERR_NO_MEMORY if data is too large and malloc/realloc was not
+ *         sucesfull
+ * @retval CS_ERR_LIBRARY if some internal error appeared (communication with parent
+ *         process)
  */
 cs_error_t sam_data_store (
 	const void *data,
 	size_t size);
 
-/*
- * Marks child as failed. This can be called only with SAM_RECOVERY_POLICY_CONFDB flag set and
+/**
+ * Marks child as failed.
+ *
+ * This can be called only with SAM_RECOVERY_POLICY_CONFDB flag set and
  * makes sense only for SAM_RECOVERY_POLICY_RESTART. This will kill child without sending warn
  * signal. Confdb state key will be set to failed.
  *
- * - CS_OK in case no problem appeared
- * - CS_ERR_BAD_HANDLE library was not initialized or was already finalized
- * - CS_ERR_INVALID_PARAM recovery policy doesn't has SAM_RECOVERY_POLICY_CONFDB flag set
- * - CS_ERR_LIBRARY if some internal error appeared (communication with parent
- *   process)
+ * @retval CS_OK in case no problem appeared
+ * @retval CS_ERR_BAD_HANDLE library was not initialized or was already finalized
+ * @retval CS_ERR_INVALID_PARAM recovery policy doesn't has SAM_RECOVERY_POLICY_CONFDB flag set
+ * @retval CS_ERR_LIBRARY if some internal error appeared (communication with parent
+ *         process)
  */
 cs_error_t sam_mark_failed (void);
 

include/corosync/sq.h

@@ -53,15 +53,16 @@ struct sq {
  * Compare a unsigned rollover-safe value to an unsigned rollover-safe value
  */
 
-/*
+/**
  * ADJUST_ROLLOVER_POINT is the value used to determine when a window should be
  *	used to calculate a less-then or less-then-equal comparison.
- *
+ */
+#define ADJUST_ROLLOVER_POINT 0x80000000
+/**
  * ADJUST_ROLLOVER_VALUE is the value by which both values in a comparison are
  *	adjusted if either value in a comparison is greater then
  *	ADJUST_ROLLOVER_POINT.
  */
-#define ADJUST_ROLLOVER_POINT 0x80000000
 #define ADJUST_ROLLOVER_VALUE 0x10000
 
 static inline int sq_lt_compare (unsigned int a, unsigned int b) {

include/corosync/totem/totem.h

@@ -52,7 +52,7 @@
 #define SEND_THREADS_MAX	16
 #define INTERFACE_MAX		2
 
-/*
+/**
  * Maximum number of continuous gather states
  */
 #define MAX_NO_CONT_GATHER	3
@@ -65,7 +65,6 @@ struct totem_interface {
 	uint16_t ttl;
 	int member_count;
 	struct totem_ip_address member_list[PROCESSOR_COUNT_MAX];
-	
 };
 
 struct totem_logging_configuration {

include/corosync/totem/totempg.h

@@ -33,6 +33,13 @@
  * THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/**
+ * @file
+ * Totem Single Ring Protocol
+ *
+ * depends on poll abstraction, POSIX, IPV4
+ */
+
 #ifndef TOTEMPG_H_DEFINED
 #define TOTEMPG_H_DEFINED
 
@@ -53,12 +60,7 @@ struct totempg_group {
 #define TOTEMPG_AGREED			0
 #define TOTEMPG_SAFE			1
 
-/*
- * Totem Single Ring Protocol
- * depends on poll abstraction, POSIX, IPV4
- */
-
-/*
+/**
  * Initialize the totem process groups abstraction
  */
 extern int totempg_initialize (
@@ -76,7 +78,7 @@ extern int totempg_callback_token_create (void **handle_out,
 
 extern void totempg_callback_token_destroy (void *handle);
 
-/*
+/**
  * Initialize a groups instance
  */
 extern int totempg_groups_initialize (

include/corosync/votequorum.h

@@ -102,36 +102,38 @@ typedef struct {
 } votequorum_callbacks_t;
 
 
-/*
+/**
  * Create a new quorum connection
  */
 cs_error_t votequorum_initialize (
 	votequorum_handle_t *handle,
 	votequorum_callbacks_t *callbacks);
 
-/*
+/**
  * Close the quorum handle
  */
 cs_error_t votequorum_finalize (
 	votequorum_handle_t handle);
 
 
-/*
+/**
  * Dispatch messages and configuration changes
  */
 cs_error_t votequorum_dispatch (
 	votequorum_handle_t handle,
 	cs_dispatch_flags_t dispatch_types);
 
-/*
- * Get a file descriptor on which to poll. votequorum_handle_t is NOT a
- * file descriptor and may not be used directly.
+/**
+ * Get a file descriptor on which to poll.
+ *
+ * @note votequorum_handle_t is NOT a file descriptor and may not be
+ *       used directly.
  */
 cs_error_t votequorum_fd_get (
 	votequorum_handle_t handle,
 	int *fd);
 
-/*
+/**
  * Get quorum information.
  */
 cs_error_t votequorum_getinfo (
@@ -139,14 +141,14 @@ cs_error_t votequorum_getinfo (
 	unsigned int nodeid,
 	struct votequorum_info *info);
 
-/*
+/**
  * set expected_votes
  */
 cs_error_t votequorum_setexpected (
 	votequorum_handle_t handle,
 	unsigned int expected_votes);
 
-/*
+/**
  * set votes for a node
  */
 cs_error_t votequorum_setvotes (
@@ -154,8 +156,9 @@ cs_error_t votequorum_setvotes (
 	unsigned int nodeid,
 	unsigned int votes);
 
-/*
+/**
  * Register a quorum device
+ *
  * it will be DEAD until polled
  */
 cs_error_t votequorum_qdisk_register (
@@ -163,33 +166,35 @@ cs_error_t votequorum_qdisk_register (
 	const char *name,
 	unsigned int votes);
 
-/*
+/**
  * Unregister a quorum device
  */
 cs_error_t votequorum_qdisk_unregister (
 	votequorum_handle_t handle);
 
-/*
+/**
  * Poll a quorum device
  */
 cs_error_t votequorum_qdisk_poll (
 	votequorum_handle_t handle,
 	unsigned int state);
 
-/*
+/**
  * Get quorum device information
  */
 cs_error_t votequorum_qdisk_getinfo (
 	votequorum_handle_t handle,
 	struct votequorum_qdisk_info *info);
 
-/*
+/**
  * Set the "hasstate" bit for this node
  */
 cs_error_t votequorum_setstate (
 	votequorum_handle_t handle);
 
-/* Track node and quorum changes */
+/**
+ * Track node and quorum changes
+ */
 cs_error_t votequorum_trackstart (
 	votequorum_handle_t handle,
 	uint64_t context,
@@ -198,13 +203,13 @@ cs_error_t votequorum_trackstart (
 cs_error_t votequorum_trackstop (
 	votequorum_handle_t handle);
 
-/*
+/**
  * Set our LEAVING flag. we should exit soon after this
  */
 cs_error_t votequorum_leaving (
 	votequorum_handle_t handle);
 
-/*
+/**
  * Save and retrieve private data/context
  */
 cs_error_t votequorum_context_get (