Good for merge - thanks! Reviewed-by: Steven Dake <[email protected]>
On 03/11/2011 07:50 PM, Russell Bryant wrote: > 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 ( _______________________________________________ Openais mailing list [email protected] https://lists.linux-foundation.org/mailman/listinfo/openais
