From: <ag...@us...> - 2012-07-05 11:39:40
|
Revision: 2008 http://nagios.svn.sourceforge.net/nagios/?rev=2008&view=rev Author: ageric Date: 2012-07-05 11:39:30 +0000 (Thu, 05 Jul 2012) Log Message: ----------- libnagios headers: Fix doxygen commenting It's nifty and we'll want to use it, but for preference without the retarded amount of warnings the previous state of the comments caused doxygen to spit out. Signed-off-by: Andreas Ericsson <ae...@op...> Modified Paths: -------------- nagioscore/trunk/lib/iobroker.h nagioscore/trunk/lib/iocache.h nagioscore/trunk/lib/kvvec.h nagioscore/trunk/lib/libnagios.h nagioscore/trunk/lib/pqueue.h nagioscore/trunk/lib/squeue.h Modified: nagioscore/trunk/lib/iobroker.h =================================================================== --- nagioscore/trunk/lib/iobroker.h 2012-07-05 11:39:06 UTC (rev 2007) +++ nagioscore/trunk/lib/iobroker.h 2012-07-05 11:39:30 UTC (rev 2008) @@ -1,6 +1,13 @@ #ifndef INCLUDE_iobroker_h__ #define INCLUDE_iobroker_h__ +/** + * @file iobroker.h + * @brief I/O broker library function declarations + * + * @{ + */ + #if (_POSIX_C_SOURCE - 0) >= 200112L #include <poll.h> # define IOBROKER_POLLIN POLLIN @@ -69,7 +76,7 @@ * @param iobs The socket set to add the socket to. * @param sd The socket descriptor to add * @param arg Argument passed to input handler on available input - * @param input_handler The callback function to call when input is available + * @param handler The callback function to call when input is available * * @return 0 on succes. < 0 on errors. */ @@ -126,7 +133,7 @@ /** * Destroy a socket set as created by iobroker_create * @param iobs The socket set to destroy - * @param close close(2) all available sockets + * @param flags If set, close(2) all registered sockets */ extern void iobroker_destroy(iobroker_set *iobs, int flags); @@ -137,3 +144,4 @@ */ extern int iobroker_poll(iobroker_set *iobs, int timeout); #endif /* INCLUDE_iobroker_h__ */ +/** @} */ Modified: nagioscore/trunk/lib/iocache.h =================================================================== --- nagioscore/trunk/lib/iocache.h 2012-07-05 11:39:06 UTC (rev 2007) +++ nagioscore/trunk/lib/iocache.h 2012-07-05 11:39:30 UTC (rev 2008) @@ -3,6 +3,17 @@ #include <stdlib.h> #include <limits.h> +/** + * @file iocache.h + * @brief I/O cache function declarations + * + * The I/O cache library is useful for reading large chunks of data + * from sockets and utilizing parts of that data based on either + * size or a magic delimiter. + * + * @{ + */ + /** opaque type for iocache operations */ struct iocache; typedef struct iocache iocache; @@ -92,3 +103,4 @@ extern int iocache_read(iocache *ioc, int fd); #endif /* INCLUDE_iocache_h__ */ +/** @} */ Modified: nagioscore/trunk/lib/kvvec.h =================================================================== --- nagioscore/trunk/lib/kvvec.h 2012-07-05 11:39:06 UTC (rev 2007) +++ nagioscore/trunk/lib/kvvec.h 2012-07-05 11:39:30 UTC (rev 2008) @@ -1,27 +1,53 @@ #ifndef INCLUDE_kvvec_h__ #define INCLUDE_kvvec_h__ + +/** + * @file kvvec.h + * @brief Key/value vector library function and type declarations + * + * The kvvec library is nifty as either a configuration meta-format + * or for IPC purposes. Take a look at the buf2kvvec() and kvvec2buf() + * pair of functions for the latter. + */ + +/** + * key/value pair + * One of the two major components of the kvvec api + */ struct key_value { - char *key, *value; - int key_len, value_len; + char *key; /**< The key */ + char *value; /**< The value */ + int key_len; /**< Length of key */ + int value_len; /**< Length of value */ }; +/** + * key/value vector buffer. Actually just a buffer, but one that gets + * used as return value and internal tracker for kvvec2buf() + */ struct kvvec_buf { - char *buf; - unsigned long buflen; - unsigned long bufsize; + char *buf; /**< The buffer */ + unsigned long buflen; /**< Length of buffer */ + unsigned long bufsize; /**< Size of buffer (includes overalloc) */ }; +/** + * key/value vector struct + * This is the main component of the kvvec library + * @note This should be made opaque, with a kvvec_foreach() using a + * callback to iterate over key/value pairs. + */ struct kvvec { - struct key_value *kv; - int kv_alloc; - int kv_pairs; - int kvv_sorted; - int combined_len; /* used for kvvec_buf to avoid one loop */ + struct key_value *kv; /**< The key/value array */ + int kv_alloc; /**< Allocated size of key/value array */ + int kv_pairs; /**< Number of key/value pairs */ + int kvv_sorted; /**< Determines if this kvvec has been sorted */ }; /** Parameters for kvvec_destroy() */ -#define KVVEC_FREE_KEYS 1 -#define KVVEC_FREE_VALUES 2 +#define KVVEC_FREE_KEYS 1 /**< Free keys when destroying a kv vector */ +#define KVVEC_FREE_VALUES 2 /**< Free values when destroying a kv vector */ +/** Free both keys and values when destroying a kv vector */ #define KVVEC_FREE_ALL (KVVEC_FREE_KEYS | KVVEC_FREE_VALUES) /** @@ -112,7 +138,7 @@ * * @param str The buffer to convert to a key/value vector * @param len Length of buffer to convert - * @param kv_sep Character separating key and value + * @param kvsep Character separating key and value * @param pair_sep Character separating key/value pairs */ extern struct kvvec *buf2kvvec(const char *str, unsigned int len, const char kvsep, const char pair_sep); Modified: nagioscore/trunk/lib/libnagios.h =================================================================== --- nagioscore/trunk/lib/libnagios.h 2012-07-05 11:39:06 UTC (rev 2007) +++ nagioscore/trunk/lib/libnagios.h 2012-07-05 11:39:30 UTC (rev 2008) @@ -1,3 +1,9 @@ +/** + * @file libnagios.h + * + * @brief Include this for all public parts of libnagios to be accessible + */ + #ifndef LIB_libnagios_h__ #define LIB_libnagios_h__ #include "pqueue.h" Modified: nagioscore/trunk/lib/pqueue.h =================================================================== --- nagioscore/trunk/lib/pqueue.h 2012-07-05 11:39:06 UTC (rev 2007) +++ nagioscore/trunk/lib/pqueue.h 2012-07-05 11:39:30 UTC (rev 2008) @@ -57,15 +57,15 @@ /** the priority queue handle */ typedef struct pqueue_t { - unsigned int size; - unsigned int avail; - unsigned int step; - pqueue_cmp_pri_f cmppri; - pqueue_get_pri_f getpri; - pqueue_set_pri_f setpri; - pqueue_get_pos_f getpos; - pqueue_set_pos_f setpos; - void **d; + unsigned int size; /**< number of elements in this queue */ + unsigned int avail; /**< slots available in this queue */ + unsigned int step; /**< growth stepping setting */ + pqueue_cmp_pri_f cmppri; /**< callback to compare nodes */ + pqueue_get_pri_f getpri; /**< callback to get priority of a node */ + pqueue_set_pri_f setpri; /**< callback to set priority of a node */ + pqueue_get_pos_f getpos; /**< callback to get position of a node */ + pqueue_set_pos_f setpos; /**< callback to set position of a node */ + void **d; /**< The actualy queue in binary heap form */ } pqueue_t; @@ -75,12 +75,14 @@ * @param n the initial estimate of the number of queue items for which memory * should be preallocated * @param cmppri The callback function to run to compare two elements - * This callback should return 0 for matching and - * @param pri the callback function to run to assign a score to a element - * @param get the callback function to get the current element's position - * @param set the callback function to set the current element's position + * This callback should return 0 for 'lower' and non-zero + * for 'higher', or vice versa if reverse priority is desired + * @param setpri the callback function to run to assign a score to an element + * @param getpri the callback function to run to set a score to an element + * @param getpos the callback function to get the current element's position + * @param setpos the callback function to set the current element's position * - * @Return the handle or NULL for insufficent memory + * @return the handle or NULL for insufficent memory */ pqueue_t * pqueue_init(unsigned int n, @@ -117,7 +119,7 @@ /** * move an existing entry to a different priority * @param q the queue - * @param old the old priority + * @param new_pri the new priority * @param d the entry */ void @@ -128,7 +130,7 @@ /** * pop the highest-ranking item from the queue. - * @param p the queue + * @param q the queue * @return NULL on error, otherwise the entry */ void *pqueue_pop(pqueue_t *q); @@ -136,7 +138,7 @@ /** * remove an item from the queue. - * @param p the queue + * @param q the queue * @param d the entry * @return 0 on success */ @@ -146,7 +148,6 @@ /** * access highest-ranking item without removing it. * @param q the queue - * @param d the entry * @return NULL on error, otherwise the entry */ void *pqueue_peek(pqueue_t *q); Modified: nagioscore/trunk/lib/squeue.h =================================================================== --- nagioscore/trunk/lib/squeue.h 2012-07-05 11:39:06 UTC (rev 2007) +++ nagioscore/trunk/lib/squeue.h 2012-07-05 11:39:30 UTC (rev 2008) @@ -1,3 +1,14 @@ +/** + * @file squeue.h + * @brief Scheduling queue function declarations + * + * This library is based on the pqueue api, which implements a + * priority queue based on a binary heap, providing O(lg n) times + * for insert() and remove(), and O(1) time for peek(). + * @note There is no "find". Callers must maintain pointers to their + * scheduled events if they wish to be able to remove them. + * @{ + */ #ifndef INCLUDE_squeue_h__ #define INCLUDE_squeue_h__ #include <sys/time.h> @@ -42,14 +53,14 @@ * with few scheduled items in that timeframe you'd be better off * using a more narrow horizon. * - * @param horizon The desired event horizon + * @param size Hint about how large this queue will get * @return A pointer to a scheduling queue */ extern squeue_t *squeue_create(unsigned int size); /** * Destroys a scheduling queue completely - * @param[in] sq The doomed queue + * @param[in] q The doomed queue * @param[in] flags Flags determining the the level of destruction */ extern void squeue_destroy(squeue_t *q, int flags); @@ -59,7 +70,7 @@ * It's up to the caller to keep the event pointer in case he/she * wants to remove the event from the queue later. * - * @param sq The scheduling queue to add to + * @param q The scheduling queue to add to * @param tv When this event should occur * @param data Pointer to any kind of data * @return The complete scheduled event @@ -70,7 +81,7 @@ * Adds an event to the scheduling queue. * See notes for squeue_add_tv() for details * - * @param sq The scheduling queue to add to + * @param q The scheduling queue to add to * @param when The unix timestamp when this event is to occur * @param data Pointer to any kind of data * @return The complete scheduled event @@ -81,7 +92,7 @@ * Adds an event to the scheduling queue with millisecond precision * See notes on squeue_add_tv() for details * - * @param[in] sq The scheduling queue to add to + * @param[in] q The scheduling queue to add to * @param[in] when Unix timestamp when this event should occur * @param[in] usec Millisecond of above this event should occur * @param[in] data Pointer to any kind of data @@ -93,7 +104,7 @@ * Adds an event to the scheduling queue with millisecond precision * See notes on squeue_add_tv() for details * - * @param[in] sq The scheduling queue to add to + * @param[in] q The scheduling queue to add to * @param[in] when Unix timestamp when this event should occur * @param[in] msec Millisecond of above this event should occur * @param[in] data Pointer to any kind of data @@ -105,7 +116,7 @@ * Returns the data of the next scheduled event from the scheduling * queue without removing it from the queue. * - * @param sq The scheduling queue to peek into + * @param q The scheduling queue to peek into */ extern void *squeue_peek(squeue_t *q); @@ -115,7 +126,7 @@ * This is equivalent to squeue_peek() + squeue_pop() * @note This causes the squeue_event to be free()'d. * - * @param sq The scheduling queue to pop from + * @param q The scheduling queue to pop from */ extern void *squeue_pop(squeue_t *q); @@ -136,3 +147,4 @@ */ extern unsigned int squeue_size(squeue_t *q); #endif +/** @} */ This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |