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 <[email protected]> --- exec/main.h | 10 ++- exec/mainconfig.h | 8 +- exec/service.h | 19 ++-- exec/tlist.h | 8 +- exec/totemiba.h | 4 +- exec/totemmrp.h | 28 +++-- exec/totemnet.h | 16 ++- exec/totemrrp.h | 17 ++-- exec/totemsrp.h | 25 +++-- exec/totemudp.h | 4 +- exec/totemudpu.h | 4 +- exec/util.h | 8 +- exec/vsf.h | 9 +- include/corosync/cfg.h | 26 +++-- include/corosync/confdb.h | 61 ++++++----- include/corosync/cpg.h | 71 +++++++------ include/corosync/evs.h | 56 ++++++---- include/corosync/ipc_cpg.h | 4 +- include/corosync/lcr/lcr_ckpt.h | 19 ++-- include/corosync/lcr/lcr_comp.h | 30 +++--- include/corosync/list.h | 7 +- include/corosync/pload.h | 15 ++-- include/corosync/quorum.h | 27 +++-- include/corosync/sam.h | 222 +++++++++++++++++++++----------------- include/corosync/sq.h | 7 +- include/corosync/totem/totem.h | 5 +- include/corosync/totem/totempg.h | 20 ++-- include/corosync/votequorum.h | 65 ++++++----- 28 files changed, 444 insertions(+), 351 deletions(-) diff --git a/exec/main.h b/exec/main.h index ac2e31e..9573ad5 100644 --- a/exec/main.h +++ b/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); diff --git a/exec/mainconfig.h b/exec/mainconfig.h index a1c87a3..4264689 100644 --- a/exec/mainconfig.h +++ b/exec/mainconfig.h @@ -40,8 +40,8 @@ #include <corosync/list.h> #include <corosync/engine/coroapi.h> -/* - * All service handlers in the AIS +/** + * \brief All service handlers in the AIS */ struct dynamic_service { char *name; @@ -51,8 +51,8 @@ struct dynamic_service { }; #define MAX_DYNAMIC_SERVICES 128 -/* - * Structure describing cached uidgid item +/** + * \brief Structure describing cached uidgid item */ struct uidgid_item { struct list_head list; diff --git a/exec/service.h b/exec/service.h index 2cc3399..7998c68 100644 --- a/exec/service.h +++ b/exec/service.h @@ -36,33 +36,34 @@ #define COROSYNC_SERVICE_H_DEFINED #include <corosync/hdb.h> -/* - * Link and initialize a service - */ + struct corosync_api_v1; +/** + * \brief 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 +/** + * \brief Unlink and exit a service */ extern unsigned int corosync_service_unlink_and_exit ( struct corosync_api_v1 *objdb, const char *service_name, unsigned int service_ver); -/* - * Unlink and exit all corosync services +/** + * \brief 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 +/** + * \brief Load all of the default services */ extern unsigned int corosync_service_defaults_link_and_init ( struct corosync_api_v1 *objdb); diff --git a/exec/tlist.h b/exec/tlist.h index 7b568ee..c9b64f4 100644 --- a/exec/tlist.h +++ b/exec/tlist.h @@ -243,8 +243,8 @@ 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 +/** + * \brief 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,8 +280,8 @@ static inline unsigned long long timerlist_msec_duration_to_expire (struct timer return (msec_duration_to_expire); } -/* - * Expires any timers that should be expired +/** + * \brief Expires any timers that should be expired */ static inline void timerlist_expire (struct timerlist *timerlist) { diff --git a/exec/totemiba.h b/exec/totemiba.h index 4b2fbbf..9689f91 100644 --- a/exec/totemiba.h +++ b/exec/totemiba.h @@ -40,8 +40,8 @@ #include <corosync/totem/totem.h> -/* - * Create an instance +/** + * \brief Create an instance */ extern int totemiba_initialize ( hdb_handle_t poll_handle, diff --git a/exec/totemmrp.h b/exec/totemmrp.h index d351072..857ccd4 100644 --- a/exec/totemmrp.h +++ b/exec/totemmrp.h @@ -32,17 +32,21 @@ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF * THE POSSIBILITY OF SUCH DAMAGE. */ + +/** + * \file + * \brief 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 +/** + * \brief Initialize the logger */ extern void totemmrp_log_printf_init ( void (*log_printf) (int , char *, ...), @@ -52,8 +56,8 @@ extern void totemmrp_log_printf_init ( int log_level_notice, int log_level_debug); -/* - * Initialize the group messaging interface +/** + * \brief Initialize the group messaging interface */ extern int totemmrp_initialize ( hdb_handle_t poll_handle, @@ -74,16 +78,16 @@ extern int totemmrp_initialize ( extern void totemmrp_finalize (void); -/* - * Multicast a message +/** + * \brief Multicast a message */ extern int totemmrp_mcast ( struct iovec *iovec, unsigned int iov_len, int priority); -/* - * Return number of available messages that can be queued +/** + * \brief Return number of available messages that can be queued */ extern int totemmrp_avail (void); diff --git a/exec/totemnet.h b/exec/totemnet.h index 7e6374c..5ee1a94 100644 --- a/exec/totemnet.h +++ b/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 + * \brief Totem Network interface - also does encryption/decryption + * + * depends on poll abstraction, POSIX, IPV4 + */ + #ifndef TOTEMNET_H_DEFINED #define TOTEMNET_H_DEFINED @@ -42,13 +50,9 @@ #define TOTEMNET_NOFLUSH 0 #define TOTEMNET_FLUSH 1 -/* - * Totem Network interface - also does encryption/decryption - * depends on poll abstraction, POSIX, IPV4 - */ -/* - * Create an instance +/** + * \brief Create an instance */ extern int totemnet_initialize ( hdb_handle_t poll_handle, diff --git a/exec/totemrrp.h b/exec/totemrrp.h index da79ed2..10622c4 100644 --- a/exec/totemrrp.h +++ b/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 + * \brief Totem Network interface - also does encryption/decryption + * + * depends on poll abstraction, POSIX, IPV4 + */ + #ifndef TOTEMRRP_H_DEFINED #define TOTEMRRP_H_DEFINED @@ -43,13 +51,8 @@ #define TOTEMRRP_NOFLUSH 0 #define TOTEMRRP_FLUSH 1 -/* - * Totem Network interface - also does encryption/decryption - * depends on poll abstraction, POSIX, IPV4 - */ - -/* - * Create an instance +/** + * \brief Create an instance */ extern int totemrrp_initialize ( hdb_handle_t poll_handle, diff --git a/exec/totemsrp.h b/exec/totemsrp.h index 55f7ce2..10dda25 100644 --- a/exec/totemsrp.h +++ b/exec/totemsrp.h @@ -32,19 +32,22 @@ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF * THE POSSIBILITY OF SUCH DAMAGE. */ + +/** + * \file + * \brief 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 +/** + * \brief Create a protocol instance */ int totemsrp_initialize ( hdb_handle_t poll_handle, @@ -66,8 +69,8 @@ int totemsrp_initialize ( void totemsrp_finalize (void *srp_context); -/* - * Multicast a message +/** + * \brief Multicast a message */ int totemsrp_mcast ( void *srp_context, @@ -75,8 +78,8 @@ int totemsrp_mcast ( unsigned int iov_len, int priority); -/* - * Return number of available messages that can be queued +/** + * \brief Return number of available messages that can be queued */ int totemsrp_avail (void *srp_context); diff --git a/exec/totemudp.h b/exec/totemudp.h index 6218794..77cdf31 100644 --- a/exec/totemudp.h +++ b/exec/totemudp.h @@ -41,8 +41,8 @@ #include <corosync/totem/totem.h> -/* - * Create an instance +/** + * \brief Create an instance */ extern int totemudp_initialize ( hdb_handle_t poll_handle, diff --git a/exec/totemudpu.h b/exec/totemudpu.h index 2dcad24..0d53d0f 100644 --- a/exec/totemudpu.h +++ b/exec/totemudpu.h @@ -41,8 +41,8 @@ #include <corosync/totem/totem.h> -/* - * Create an instance +/** + * \brief Create an instance */ extern int totemudpu_initialize ( hdb_handle_t poll_handle, diff --git a/exec/util.h b/exec/util.h index f04794e..42c9348 100644 --- a/exec/util.h +++ b/exec/util.h @@ -38,8 +38,8 @@ #include <sys/time.h> #include <corosync/corotypes.h> -/* - * Get the time of day and convert to nanoseconds +/** + * \brief Get the time of day and convert to nanoseconds */ extern cs_time_t clust_time_now(void); @@ -86,8 +86,8 @@ static inline cs_error_t hdb_error_to_cs (int res) \ } \ } -/* - * Compare two names. returns non-zero on match. +/** + * \brief Compare two names. returns non-zero on match. */ extern int name_match(cs_name_t *name1, cs_name_t *name2); #define corosync_exit_error(err) _corosync_exit_error ((err), __FILE__, __LINE__) diff --git a/exec/vsf.h b/exec/vsf.h index 1bd6f4c..6346f9b 100644 --- a/exec/vsf.h +++ b/exec/vsf.h @@ -37,8 +37,8 @@ struct corosync_api_v1; struct corosync_vsf_iface_ver0 { - /* - * Executes a callback whenever component changes + /** + * \brief Executes a callback whenever component changes */ int (*init) ( struct corosync_api_v1 *api, @@ -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); }; diff --git a/include/corosync/cfg.h b/include/corosync/cfg.h index 5e3c8b9..140a0c3 100644 --- a/include/corosync/cfg.h +++ b/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) -*/ +/** + * \brief Shutdown types. + */ typedef enum { + /** + * \brief REQUEST is the normal shutdown. + * Other daemons will be consulted. + */ COROSYNC_CFG_SHUTDOWN_FLAG_REQUEST = 0, + /** + * \brief REGARDLESS will tell other daemons but ignore their opinions. + */ COROSYNC_CFG_SHUTDOWN_FLAG_REGARDLESS = 1, + /** + * \brief 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] +/** + * \brief 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; diff --git a/include/corosync/confdb.h b/include/corosync/confdb.h index ca0d7ba..2416d03 100644 --- a/include/corosync/confdb.h +++ b/include/corosync/confdb.h @@ -118,30 +118,30 @@ typedef struct { /** @} */ -/* - * Create a new confdb connection +/** + * \brief Create a new confdb connection */ cs_error_t confdb_initialize ( confdb_handle_t *handle, confdb_callbacks_t *callbacks); -/* - * Close the confdb handle +/** + * \brief Close the confdb handle */ cs_error_t confdb_finalize ( confdb_handle_t handle); -/* - * Write back the configuration +/** + * \brief Write back the configuration */ cs_error_t confdb_write ( confdb_handle_t handle, char *error_text, size_t errbuf_len); -/* - * Reload the configuration +/** + * \brief Reload the configuration */ cs_error_t confdb_reload ( confdb_handle_t handle, @@ -149,23 +149,24 @@ 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. +/** + * \brief 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 +/** + * \brief Dispatch configuration changes */ cs_error_t confdb_dispatch ( confdb_handle_t handle, cs_dispatch_flags_t dispatch_types); -/* - * Change notification +/** + * \brief Change notification */ cs_error_t confdb_track_changes ( confdb_handle_t handle, @@ -175,8 +176,8 @@ cs_error_t confdb_track_changes ( cs_error_t confdb_stop_track_changes ( confdb_handle_t handle); -/* - * Manipulate objects +/** + * \brief Manipulate objects */ cs_error_t confdb_object_create ( confdb_handle_t handle, @@ -200,8 +201,8 @@ cs_error_t confdb_object_name_get ( char *object_name, size_t *object_name_len); -/* - * Manipulate keys +/** + * \brief Manipulate keys */ cs_error_t confdb_key_create ( confdb_handle_t handle, @@ -227,8 +228,8 @@ cs_error_t confdb_key_delete ( const void *value, size_t value_len); -/* - * Key queries +/** + * \brief Key queries */ cs_error_t confdb_key_get ( confdb_handle_t handle, @@ -270,10 +271,12 @@ cs_error_t confdb_key_decrement ( size_t key_name_len, unsigned int *value); -/* - * Object queries +/** + * \brief 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,8 +309,8 @@ cs_error_t confdb_object_iter_destroy( confdb_handle_t handle, hdb_handle_t parent_object_handle); -/* - * Key iterator +/** + * \brief Key iterator */ cs_error_t confdb_key_iter_start ( confdb_handle_t handle, @@ -329,14 +332,16 @@ cs_error_t confdb_key_iter_typed ( size_t *value_len, confdb_value_types_t *type); -/* - * Get/set context variable +/** + * \brief Get context variable */ - cs_error_t confdb_context_get ( confdb_handle_t handle, const void **context); +/** + * \brief Set context variable + */ cs_error_t confdb_context_set ( confdb_handle_t handle, const void *context); diff --git a/include/corosync/cpg.h b/include/corosync/cpg.h index 6189eb5..9ab3788 100644 --- a/include/corosync/cpg.h +++ b/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,15 +154,15 @@ typedef struct { /** @} */ -/* - * Create a new cpg connection +/** + * \brief 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 +/** + * \brief Create a new cpg connection, initialize with model */ cs_error_t cpg_model_initialize ( cpg_handle_t *handle, @@ -170,41 +170,46 @@ cs_error_t cpg_model_initialize ( cpg_model_data_t *model_data, void *context); -/* - * Close the cpg handle +/** + * \brief 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. +/** + * \brief 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 +/** + * \brief Get contexts for a CPG handle */ cs_error_t cpg_context_get ( cpg_handle_t handle, void **context); +/** + * \brief Set contexts for a CPG handle + */ cs_error_t cpg_context_set ( cpg_handle_t handle, void *context); -/* - * Dispatch messages and configuration changes +/** + * \brief 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. +/** + * \brief 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 +/** + * \brief 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. +/** + * \brief Multicast to groups joined with cpg_join. + * + * \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,8 +240,8 @@ cs_error_t cpg_mcast_joined ( const struct iovec *iovec, unsigned int iov_len); -/* - * Get membership information from cpg +/** + * \brief Get membership information from cpg */ cs_error_t cpg_membership_get ( cpg_handle_t handle, @@ -263,8 +272,8 @@ cs_error_t cpg_zcb_mcast_joined ( void *msg, size_t msg_len); -/* - * Iteration +/** + * \brief Iteration */ cs_error_t cpg_iteration_initialize( cpg_handle_t handle, diff --git a/include/corosync/evs.h b/include/corosync/evs.h index 1718e40..9304533 100644 --- a/include/corosync/evs.h +++ b/include/corosync/evs.h @@ -92,47 +92,52 @@ typedef struct { /** @} */ -/* - * Create a new evs connection +/** + * \brief Create a new evs connection */ cs_error_t evs_initialize ( evs_handle_t *handle, evs_callbacks_t *callbacks); -/* - * Close the evs handle +/** + * \brief 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. +/** + * \brief 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 +/** + * \brief Get contexts for a EVS handle */ cs_error_t evs_context_get ( evs_handle_t handle, void **context); +/** + * \brief Set contexts for a EVS handle + */ cs_error_t evs_context_set ( evs_handle_t handle, void *context); -/* - * Dispatch messages and configuration changes +/** + * \brief 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. +/** + * \brief 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,18 +147,22 @@ cs_error_t evs_join ( const struct evs_group *groups, size_t group_cnt); -/* - * Leave one or more groups +/** + * \brief Leave one or more groups */ cs_error_t evs_leave ( evs_handle_t handle, 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. +/** + * \brief Multicast to groups joined with evs_join. + * + * \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. +/** + * \brief 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,8 +184,8 @@ cs_error_t evs_mcast_groups ( const struct iovec *iovec, unsigned int iov_len); -/* - * Get membership information from evs +/** + * \brief Get membership information from evs */ cs_error_t evs_membership_get ( evs_handle_t handle, diff --git a/include/corosync/ipc_cpg.h b/include/corosync/ipc_cpg.h index afdebaa..4f3bcd3 100644 --- a/include/corosync/ipc_cpg.h +++ b/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 */ +/** + * \brief 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))); diff --git a/include/corosync/lcr/lcr_ckpt.h b/include/corosync/lcr/lcr_ckpt.h index 8020bd2..d2ff115 100644 --- a/include/corosync/lcr/lcr_ckpt.h +++ b/include/corosync/lcr/lcr_ckpt.h @@ -31,26 +31,27 @@ #ifndef LCR_CKPT_H_DEFINED #define LCR_CKPT_H_DEFINED -/* - * Write data of length data_len into the section name for ckpt_handle +/** + * \brief 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. +/** + * \brief Read the section name into data with data len. + * + * \return 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 +/** + * \brief 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 +/** + * \brief Get the current section, return it in name, and advance to next section */ int lcr_ckpt_section_iterator_next (void *ckpt_handle, char **name); diff --git a/include/corosync/lcr/lcr_comp.h b/include/corosync/lcr/lcr_comp.h index 084cda6..f4e80f9 100644 --- a/include/corosync/lcr/lcr_comp.h +++ b/include/corosync/lcr/lcr_comp.h @@ -31,27 +31,27 @@ #ifndef LCR_COMP_H_DEFINED #define LCR_COMP_H_DEFINED -/* - * LCR Interface +/** + * \brief 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 +/** + * \brief 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); diff --git a/include/corosync/list.h b/include/corosync/list.h index 1790a69..e707dbb 100644 --- a/include/corosync/list.h +++ b/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 + * \brief 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 diff --git a/include/corosync/pload.h b/include/corosync/pload.h index ff9bcec..62c1bc5 100644 --- a/include/corosync/pload.h +++ b/include/corosync/pload.h @@ -74,22 +74,23 @@ typedef struct { /** @} */ -/* - * Create a new pload connection +/** + * \brief Create a new pload connection */ pload_error_t pload_initialize ( pload_handle_t *handle, pload_callbacks_t *callbacks); -/* - * Close the pload handle +/** + * \brief 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. +/** + * \brief 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, diff --git a/include/corosync/quorum.h b/include/corosync/quorum.h index ab5333b..a7e915e 100644 --- a/include/corosync/quorum.h +++ b/include/corosync/quorum.h @@ -60,44 +60,47 @@ typedef struct { } quorum_callbacks_t; -/* - * Create a new quorum connection +/** + * \brief Create a new quorum connection */ cs_error_t quorum_initialize ( quorum_handle_t *handle, quorum_callbacks_t *callbacks); -/* - * Close the quorum handle +/** + * \brief 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. +/** + * \brief 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 +/** + * \brief Dispatch messages and configuration changes */ cs_error_t quorum_dispatch ( quorum_handle_t handle, cs_dispatch_flags_t dispatch_types); -/* - * Get quorum information. +/** + * \brief Get quorum information. */ cs_error_t quorum_getquorate ( quorum_handle_t handle, int *quorate); -/* Track node and quorum changes */ +/** + * \brief Track node and quorum changes + */ cs_error_t quorum_trackstart ( quorum_handle_t handle, unsigned int flags ); diff --git a/include/corosync/sam.h b/include/corosync/sam.h index 30401a0..64726c8 100644 --- a/include/corosync/sam.h +++ b/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 +/** + * \brief 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. +/** + * \brief 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) - * @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 + * \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) + * \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 + * + * \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 +/** + * \brief 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 +/** + * \brief 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. +/** + * \brief 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 +/** + * \brief 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 +/** + * \brief 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 + * \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). + * + * \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 +/** + * \brief 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 +/** + * \brief 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. + * + * \param cb Pointer to healtcheck function, or NULL to switch back to application driven hc + * + * \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 +/** + * \brief 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. + * + * \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 +/** + * \brief Return stored data. + * + * \param data Pointer to place, where to store data + * \param size Allocated size of data + * + * \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. - * @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) +/** + * \brief 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. + * + * \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 +/** + * \brief 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); diff --git a/include/corosync/sq.h b/include/corosync/sq.h index ce3b1f8..3fe78f7 100644 --- a/include/corosync/sq.h +++ b/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) { diff --git a/include/corosync/totem/totem.h b/include/corosync/totem/totem.h index 1c63186..e275663 100644 --- a/include/corosync/totem/totem.h +++ b/include/corosync/totem/totem.h @@ -52,8 +52,8 @@ #define SEND_THREADS_MAX 16 #define INTERFACE_MAX 2 -/* - * Maximum number of continuous gather states +/** + * \brief 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 { diff --git a/include/corosync/totem/totempg.h b/include/corosync/totem/totempg.h index 26447aa..d7a95f5 100644 --- a/include/corosync/totem/totempg.h +++ b/include/corosync/totem/totempg.h @@ -33,6 +33,13 @@ * THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file + * \brief Totem Single Ring Protocol + * + * depends on poll abstraction, POSIX, IPV4 + */ + #ifndef TOTEMPG_H_DEFINED #define TOTEMPG_H_DEFINED @@ -53,13 +60,8 @@ 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 +/** + * \brief Initialize the totem process groups abstraction */ extern int totempg_initialize ( hdb_handle_t poll_handle, @@ -76,8 +78,8 @@ extern int totempg_callback_token_create (void **handle_out, extern void totempg_callback_token_destroy (void *handle); -/* - * Initialize a groups instance +/** + * \brief Initialize a groups instance */ extern int totempg_groups_initialize ( hdb_handle_t *handle, diff --git a/include/corosync/votequorum.h b/include/corosync/votequorum.h index f915686..673c59e 100644 --- a/include/corosync/votequorum.h +++ b/include/corosync/votequorum.h @@ -102,60 +102,63 @@ typedef struct { } votequorum_callbacks_t; -/* - * Create a new quorum connection +/** + * \brief Create a new quorum connection */ cs_error_t votequorum_initialize ( votequorum_handle_t *handle, votequorum_callbacks_t *callbacks); -/* - * Close the quorum handle +/** + * \brief Close the quorum handle */ cs_error_t votequorum_finalize ( votequorum_handle_t handle); -/* - * Dispatch messages and configuration changes +/** + * \brief 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. +/** + * \brief 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. +/** + * \brief Get quorum information. */ cs_error_t votequorum_getinfo ( votequorum_handle_t handle, unsigned int nodeid, struct votequorum_info *info); -/* - * set expected_votes +/** + * \brief set expected_votes */ cs_error_t votequorum_setexpected ( votequorum_handle_t handle, unsigned int expected_votes); -/* - * set votes for a node +/** + * \brief set votes for a node */ cs_error_t votequorum_setvotes ( votequorum_handle_t handle, unsigned int nodeid, unsigned int votes); -/* - * Register a quorum device +/** + * \brief 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 +/** + * \brief Unregister a quorum device */ cs_error_t votequorum_qdisk_unregister ( votequorum_handle_t handle); -/* - * Poll a quorum device +/** + * \brief Poll a quorum device */ cs_error_t votequorum_qdisk_poll ( votequorum_handle_t handle, unsigned int state); -/* - * Get quorum device information +/** + * \brief 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 +/** + * \brief Set the "hasstate" bit for this node */ cs_error_t votequorum_setstate ( votequorum_handle_t handle); -/* Track node and quorum changes */ +/** + * \brief Track node and quorum changes + */ cs_error_t votequorum_trackstart ( votequorum_handle_t handle, uint64_t context, @@ -198,14 +203,14 @@ cs_error_t votequorum_trackstart ( cs_error_t votequorum_trackstop ( votequorum_handle_t handle); -/* - * Set our LEAVING flag. we should exit soon after this +/** + * \brief 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 +/** + * \brief Save and retrieve private data/context */ cs_error_t votequorum_context_get ( votequorum_handle_t handle, -- 1.7.4 _______________________________________________ Openais mailing list [email protected] https://lists.linux-foundation.org/mailman/listinfo/openais
