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 | 4 +- exec/service.h | 13 ++- exec/tlist.h | 4 +- exec/totemiba.h | 2 +- exec/totemmrp.h | 20 +++-- exec/totemnet.h | 14 ++- exec/totemrrp.h | 15 ++- exec/totemsrp.h | 19 ++-- exec/totemudp.h | 2 +- exec/totemudpu.h | 2 +- exec/util.h | 4 +- exec/vsf.h | 7 +- include/corosync/cfg.h | 24 ++++-- include/corosync/confdb.h | 39 ++++---- include/corosync/cpg.h | 53 ++++++---- include/corosync/evs.h | 40 +++++--- include/corosync/ipc_cpg.h | 4 +- include/corosync/lcr/lcr_ckpt.h | 13 ++- include/corosync/lcr/lcr_comp.h | 26 +++--- include/corosync/list.h | 7 +- include/corosync/pload.h | 11 +- include/corosync/quorum.h | 19 ++-- include/corosync/sam.h | 198 +++++++++++++++++++++----------------- include/corosync/sq.h | 7 +- include/corosync/totem/totem.h | 3 +- include/corosync/totem/totempg.h | 16 ++-- include/corosync/votequorum.h | 39 ++++---- 28 files changed, 354 insertions(+), 261 deletions(-) diff --git a/exec/main.h b/exec/main.h index ac2e31e..ac260a8 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..b8d4ff9 100644 --- a/exec/mainconfig.h +++ b/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 { diff --git a/exec/service.h b/exec/service.h index 2cc3399..b7b934a 100644 --- a/exec/service.h +++ b/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 ( diff --git a/exec/tlist.h b/exec/tlist.h index 7b568ee..42549ad 100644 --- a/exec/tlist.h +++ b/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) diff --git a/exec/totemiba.h b/exec/totemiba.h index 4b2fbbf..d826541 100644 --- a/exec/totemiba.h +++ b/exec/totemiba.h @@ -40,7 +40,7 @@ #include <corosync/totem/totem.h> -/* +/** * Create an instance */ extern int totemiba_initialize ( diff --git a/exec/totemmrp.h b/exec/totemmrp.h index d351072..b3528ca 100644 --- a/exec/totemmrp.h +++ b/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); diff --git a/exec/totemnet.h b/exec/totemnet.h index 7e6374c..cf3baac 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 + * 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 ( diff --git a/exec/totemrrp.h b/exec/totemrrp.h index da79ed2..b092735 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 + * 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 ( diff --git a/exec/totemsrp.h b/exec/totemsrp.h index 55f7ce2..8544161 100644 --- a/exec/totemsrp.h +++ b/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); diff --git a/exec/totemudp.h b/exec/totemudp.h index 6218794..faae363 100644 --- a/exec/totemudp.h +++ b/exec/totemudp.h @@ -41,7 +41,7 @@ #include <corosync/totem/totem.h> -/* +/** * Create an instance */ extern int totemudp_initialize ( diff --git a/exec/totemudpu.h b/exec/totemudpu.h index 2dcad24..9a400fe 100644 --- a/exec/totemudpu.h +++ b/exec/totemudpu.h @@ -41,7 +41,7 @@ #include <corosync/totem/totem.h> -/* +/** * Create an instance */ extern int totemudpu_initialize ( diff --git a/exec/util.h b/exec/util.h index f04794e..0df192c 100644 --- a/exec/util.h +++ b/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); diff --git a/exec/vsf.h b/exec/vsf.h index 1bd6f4c..28d3ef8 100644 --- a/exec/vsf.h +++ b/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); }; diff --git a/include/corosync/cfg.h b/include/corosync/cfg.h index 5e3c8b9..903d1ef 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) -*/ +/** + * 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; diff --git a/include/corosync/confdb.h b/include/corosync/confdb.h index ca0d7ba..06aac1e 100644 --- a/include/corosync/confdb.h +++ b/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); diff --git a/include/corosync/cpg.h b/include/corosync/cpg.h index 6189eb5..f7956fa 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,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( diff --git a/include/corosync/evs.h b/include/corosync/evs.h index 1718e40..3769149 100644 --- a/include/corosync/evs.h +++ b/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 ( diff --git a/include/corosync/ipc_cpg.h b/include/corosync/ipc_cpg.h index afdebaa..664f814 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 */ +/** + * 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..7d3ba4d 100644 --- a/include/corosync/lcr/lcr_ckpt.h +++ b/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); diff --git a/include/corosync/lcr/lcr_comp.h b/include/corosync/lcr/lcr_comp.h index 084cda6..f163cbf 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 */ 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); diff --git a/include/corosync/list.h b/include/corosync/list.h index 1790a69..d7720e0 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 + * 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..ba0df37 100644 --- a/include/corosync/pload.h +++ b/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, diff --git a/include/corosync/quorum.h b/include/corosync/quorum.h index ab5333b..ab45aea 100644 --- a/include/corosync/quorum.h +++ b/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 ); diff --git a/include/corosync/sam.h b/include/corosync/sam.h index 30401a0..84bf532 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 */ 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); 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..eb1a908 100644 --- a/include/corosync/totem/totem.h +++ 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 { diff --git a/include/corosync/totem/totempg.h b/include/corosync/totem/totempg.h index 26447aa..066be21 100644 --- a/include/corosync/totem/totempg.h +++ b/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 ( diff --git a/include/corosync/votequorum.h b/include/corosync/votequorum.h index f915686..6cdad49 100644 --- a/include/corosync/votequorum.h +++ b/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 ( -- 1.7.4 _______________________________________________ Openais mailing list [email protected] https://lists.linux-foundation.org/mailman/listinfo/openais
