Update doxygen annotations in libosmocore
This adds and improves doxygen API descriptions all over libosmocore,
reducing the 'white spots' that don't have any documentation.
diff --git a/src/application.c b/src/application.c
index 9c3fe52..8a325c8 100644
--- a/src/application.c
+++ b/src/application.c
@@ -40,7 +40,7 @@
* a multi-threaded context, you have to add your own locking.
*
* \section sec_copyright Copyright and License
- * Copyright © 2008-2011 - Harald Welte, Holger Freyther and contributors\n
+ * Copyright © 2008-2016 - Harald Welte, Holger Freyther and contributors\n
* All rights reserved. \n\n
* The source code of libosmocore is licensed under the terms of the GNU
* General Public License as published by the Free Software Foundation;
diff --git a/src/backtrace.c b/src/backtrace.c
index 5b93bec..6cd798c 100644
--- a/src/backtrace.c
+++ b/src/backtrace.c
@@ -70,6 +70,8 @@
}
/*! \brief Generate and log a call back-trace
+ * \param[in] subsys Logging sub-system
+ * \param[in] level Logging level
*
* This function will generate a function call back-trace of the
* current process and log it to the specified subsystem and
diff --git a/src/bitcomp.c b/src/bitcomp.c
index bf35927..8b3090e 100644
--- a/src/bitcomp.c
+++ b/src/bitcomp.c
@@ -232,9 +232,9 @@
/*! \brief Attempt to decode compressed bit vector
*
- * Return length of RLE according to modified ITU-T T.4 from TS 44.060 Table 9.1.10.2
- * or -1 if no applicable RLE found
- * N. B: we need explicit bit length to make decoding unambiguous
+ * \return length of RLE according to modified ITU-T T.4 from TS 44.060
+ * Table 9.1.10.2 or -1 if no applicable RLE found N. B: we need
+ * explicit bit length to make decoding unambiguous
*/
static inline int t4_rle_term(unsigned w, bool b, unsigned bits)
{
@@ -256,8 +256,9 @@
/*! \brief Make-up codes for a given length
*
- * Return proper make-up code word for an uninterrupted sequence of b bits
- * of length len according to modified ITU-T T.4 from TS 44.060 Table 9.1.10.2 */
+ * \return Return proper make-up code word for an uninterrupted
+ * sequence of b bits of length len according to modified ITU-T T.4
+ * from TS 44.060 Table 9.1.10.2 */
static inline int t4_rle(struct bitvec *bv, unsigned len, bool b)
{
if (len >= 960) {
@@ -384,7 +385,7 @@
* \param[in] in bit vector with encoded data
* \param[in] cc color code (whether decoding should start with 1 or 0)
* \param[out] out the bit vector to store result into
- * returns 0 on success, negative value otherwise
+ * \return 0 on success, negative value otherwise
*/
int osmo_t4_decode(const struct bitvec *in, bool cc, struct bitvec *out)
{
@@ -437,7 +438,8 @@
/*! \brief encode bit vector in-place using T4 encoding
* Assumes MSB first encoding.
* \param[in] bv bit vector to be encoded
- * returns color code (if the encoding started with 0 or 1) or -1 on failure (encoded is bigger than original)
+ * \return color code (if the encoding started with 0 or 1) or -1 on
+ * failure (encoded is bigger than original)
*/
int osmo_t4_encode(struct bitvec *bv)
{
diff --git a/src/bits.c b/src/bits.c
index 48314af..569a10f 100644
--- a/src/bits.c
+++ b/src/bits.c
@@ -89,6 +89,7 @@
* \param[out] out output buffer of unpacked bits
* \param[in] in input buffer of packed bits
* \param[in] num_bits number of bits
+ * \return number of bytes used in \ref out
*/
int osmo_pbit2ubit(ubit_t *out, const pbit_t *in, unsigned int num_bits)
{
diff --git a/src/bitvec.c b/src/bitvec.c
index a92fd71..88343c4 100644
--- a/src/bitvec.c
+++ b/src/bitvec.c
@@ -75,7 +75,7 @@
/*! \brief check if the bit is 0 or 1 for a given position inside a bitvec
* \param[in] bv the bit vector on which to check
* \param[in] bitnr the bit number inside the bit vector to check
- * \returns
+ * \return value of the requested bit
*/
enum bit_value bitvec_get_bit_pos(const struct bitvec *bv, unsigned int bitnr)
{
@@ -97,6 +97,7 @@
/*! \brief check if the bit is L or H for a given position inside a bitvec
* \param[in] bv the bit vector on which to check
* \param[in] bitnr the bit number inside the bit vector to check
+ * \return value of the requested bit
*/
enum bit_value bitvec_get_bit_pos_high(const struct bitvec *bv,
unsigned int bitnr)
@@ -179,7 +180,8 @@
return rc;
}
-/*! \brief get the next bit (low/high) inside a bitvec */
+/*! \brief get the next bit (low/high) inside a bitvec
+ * \return value of th next bit in the vector */
int bitvec_get_bit_high(struct bitvec *bv)
{
int rc;
@@ -195,7 +197,7 @@
* \param[in] bv bit vector
* \param[in] bits array of \ref bit_value
* \param[in] count number of bits to set
- */
+ * \return 0 on success; negative in case of error */
int bitvec_set_bits(struct bitvec *bv, enum bit_value *bits, unsigned int count)
{
int i, rc;
@@ -209,7 +211,8 @@
return 0;
}
-/*! \brief set multiple bits (based on numeric value) at current pos */
+/*! \brief set multiple bits (based on numeric value) at current pos
+ * \return 0 in case of success; negative in case of error */
int bitvec_set_uint(struct bitvec *bv, unsigned int ui, unsigned int num_bits)
{
int rc;
@@ -226,7 +229,8 @@
return 0;
}
-/*! \brief get multiple bits (num_bits) from beginning of vector (MSB side) */
+/*! \brief get multiple bits (num_bits) from beginning of vector (MSB side)
+ * \return 16bit signed integer retrieved from bit vector */
int16_t bitvec_get_int16_msb(const struct bitvec *bv, unsigned int num_bits)
{
if (num_bits > 15 || bv->cur_bit < num_bits)
@@ -238,7 +242,8 @@
return osmo_load16be(bv->data) >> (16 - num_bits);
}
-/*! \brief get multiple bits (based on numeric value) from current pos */
+/*! \brief get multiple bits (based on numeric value) from current pos
+ * \return integer value retrieved from bit vector */
int bitvec_get_uint(struct bitvec *bv, unsigned int num_bits)
{
int i;
@@ -257,7 +262,7 @@
}
/*! \brief fill num_bits with \fill starting from the current position
- * returns 0 on success, negative otherwise (out of vector boundary)
+ * \return 0 on success; negative otherwise (out of vector boundary)
*/
int bitvec_fill(struct bitvec *bv, unsigned int num_bits, enum bit_value fill)
{
@@ -269,7 +274,8 @@
return 0;
}
-/*! \brief pad all remaining bits up to num_bits */
+/*! \brief pad all remaining bits up to num_bits
+ * \return 0 on success; negative otherwise */
int bitvec_spare_padding(struct bitvec *bv, unsigned int up_to_bit)
{
int n = up_to_bit - bv->cur_bit + 1;
@@ -279,7 +285,8 @@
return bitvec_fill(bv, n, L);
}
-/*! \brief find first bit set in bit vector */
+/*! \brief find first bit set in bit vector
+ * \return 0 on success; negative otherwise */
int bitvec_find_bit_pos(const struct bitvec *bv, unsigned int n,
enum bit_value val)
{
@@ -298,6 +305,7 @@
* \param[in] bv bit vector
* \param[in] bytes array
* \param[in] count number of bytes to copy
+ * \return 0 on success; negative otherwise
*/
int bitvec_get_bytes(struct bitvec *bv, uint8_t *bytes, unsigned int count)
{
@@ -333,6 +341,7 @@
* \param[in] bv bit vector
* \param[in] bytes array
* \param[in] count number of bytes to copy
+ * \return 0 on success; negative otherwise
*/
int bitvec_set_bytes(struct bitvec *bv, const uint8_t *bytes, unsigned int count)
{
@@ -367,6 +376,10 @@
return 0;
}
+/*! \brief Allocate a bit vector
+ * \param[in] size Number of bits in the vector
+ * \param[in] ctx Context from which to allocate
+ * \return pointer to allocated vector; NULL in case of error */
struct bitvec *bitvec_alloc(unsigned int size, TALLOC_CTX *ctx)
{
struct bitvec *bv = talloc_zero(ctx, struct bitvec);
@@ -384,12 +397,18 @@
return bv;
}
+/*! \brief Free a bit vector (release its memory)
+ * \param[in] bit vector to free */
void bitvec_free(struct bitvec *bv)
{
talloc_free(bv->data);
talloc_free(bv);
}
+/*! \brief Export a bit vector to a buffer
+ * \param[in] bitvec (unpacked bits)
+ * \param[out] buffer for the unpacked bits
+ * \return number of bytes (= bits) copied */
unsigned int bitvec_pack(const struct bitvec *bv, uint8_t *buffer)
{
unsigned int i = 0;
@@ -399,6 +418,10 @@
return i;
}
+/*! \brief Copy buffer of unpacked bits into bit vector
+ * \param[in] buffer unpacked input bits
+ * \param[out] bv unpacked bit vector
+ * \return number of bytes (= bits) copied */
unsigned int bitvec_unpack(struct bitvec *bv, const uint8_t *buffer)
{
unsigned int i = 0;
@@ -408,7 +431,11 @@
return i;
}
-
+/*! \brief read hexadecimap string into a bit vector
+ * \param[in] src string containing hex digits
+ * \param[out] bv unpacked bit vector
+ * \return 0 in case of success; 1 in case of error
+ */
int bitvec_unhex(struct bitvec *bv, const char *src)
{
unsigned i;
@@ -472,7 +499,9 @@
return 0;
}
-/*! \brief convert enum to corresponding character */
+/*! \brief convert enum to corresponding character
+ * \param v input value (bit)
+ * \return single character, either 0, 1, L or H */
char bit_value_to_char(enum bit_value v)
{
switch (v) {
diff --git a/src/crc16.c b/src/crc16.c
index 2741cf5..9dd4672 100644
--- a/src/crc16.c
+++ b/src/crc16.c
@@ -10,7 +10,7 @@
#include <osmocom/core/crc16.h>
-/** CRC table for the CRC-16. The poly is 0x8005 (x^16 + x^15 + x^2 + 1) */
+/*! \brief CRC table for the CRC-16. The poly is 0x8005 (x^16 + x^15 + x^2 + 1) */
uint16_t const osmo_crc16_table[256] = {
0x0000, 0xC0C1, 0xC181, 0x0140, 0xC301, 0x03C0, 0x0280, 0xC241,
0xC601, 0x06C0, 0x0780, 0xC741, 0x0500, 0xC5C1, 0xC481, 0x0440,
@@ -46,13 +46,11 @@
0x8201, 0x42C0, 0x4380, 0x8341, 0x4100, 0x81C1, 0x8081, 0x4040
};
-/**
- * crc16 - compute the CRC-16 for the data buffer
- * @crc: previous CRC value
- * @buffer: data pointer
- * @len: number of bytes in the buffer
- *
- * Returns the updated CRC value.
+/*! \brief compute the CRC-16 for the data buffer
+ * \param crc[in] previous CRC value
+ * \param buffer[in] data pointer
+ * \param len[in] number of bytes in input \ref buffer
+ * \return updated CRC value
*/
uint16_t osmo_crc16(uint16_t crc, uint8_t const *buffer, size_t len)
{
diff --git a/src/gsmtap_util.c b/src/gsmtap_util.c
index 82690a9..7a63771 100644
--- a/src/gsmtap_util.c
+++ b/src/gsmtap_util.c
@@ -99,6 +99,7 @@
* \param[in] snr Signal/Noise Ratio (SNR)
* \param[in] data Pointer to data buffer
* \param[in] len Length of \ref data
+ * \return dynamically allocated message buffer containing data
*
* This function will allocate a new msgb and fill it with a GSMTAP
* header containing the information
@@ -145,6 +146,7 @@
* \param[in] snr Signal/Noise Ratio (SNR)
* \param[in] data Pointer to data buffer
* \param[in] len Length of \ref data
+ * \return message buffer or NULL in case of error
*
* This function will allocate a new msgb and fill it with a GSMTAP
* header containing the information
@@ -165,6 +167,7 @@
/*! \brief Create a new (sending) GSMTAP source socket
* \param[in] host host name or IP address in string format
* \param[in] port UDP port number in host byte order
+ * \return file descriptor of the new socket
*
* Opens a GSMTAP source (sending) socket, conncet it to host/port and
* return resulting fd. If \a host is NULL, the destination address
@@ -217,6 +220,7 @@
/*! \brief Send a \ref msgb through a GSMTAP source
* \param[in] gti GSMTAP instance
* \param[in] msg message buffer
+ * \return 0 in case of success; negative in case of error
*/
int gsmtap_sendmsg(struct gsmtap_inst *gti, struct msgb *msg)
{
@@ -312,7 +316,21 @@
return 0;
}
-/*! \brief Add a local sink to an existing GSMTAP source instance */
+/*! \brief Add a local sink to an existing GSMTAP source and return fd
+ * \param[in] gsmtap_fd file descriptor of the gsmtap socket
+ * \returns file descriptor of locally bound receive socket
+ *
+ * In case the GSMTAP socket is connected to a local destination
+ * IP/port, this function creates a corresponding receiving socket
+ * bound to that destination IP + port.
+ *
+ * In case the gsmtap socket is not connected to a local IP/port, or
+ * creation of the receiving socket fails, a negative error code is
+ * returned.
+ *
+ * The file descriptor of the receiving socket is automatically added
+ * to the libosmocore select() handling.
+ */
int gsmtap_source_add_sink(struct gsmtap_inst *gti)
{
int fd;
@@ -340,6 +358,7 @@
* \param[in] host host name or IP address in string format
* \param[in] port UDP port number in host byte order
* \param[in] ofd_wq_mode Register \ref osmo_wqueue (1) or not (0)
+ * \return callee-allocated \ref gsmtap_inst
*
* Open GSMTAP source (sending) socket, connect it to host/port,
* allocate 'struct gsmtap_inst' and optionally osmo_fd/osmo_wqueue
diff --git a/src/logging.c b/src/logging.c
index 4d6fd40..b2f8d43 100644
--- a/src/logging.c
+++ b/src/logging.c
@@ -142,13 +142,19 @@
return (subsys * -1) + (osmo_log_info->num_cat_user-1);
}
-/*! \brief Parse a human-readable log level into a numeric value */
+/*! \brief Parse a human-readable log level into a numeric value
+ * \param lvl[in] zero-terminated string containing log level name
+ * \returns numeric log level
+ */
int log_parse_level(const char *lvl)
{
return get_string_value(loglevel_strs, lvl);
}
-/*! \brief convert a numeric log level into human-readable string */
+/*! \brief convert a numeric log level into human-readable string
+ * \param lvl[in] numeric log level
+ * \returns zero-terminated string (log level name)
+ */
const char *log_level_str(unsigned int lvl)
{
return get_value_string(loglevel_strs, lvl);
@@ -353,7 +359,14 @@
return 1;
}
-/*! \brief vararg version of logging function */
+/*! \brief vararg version of logging function
+ * \param[in] subsys Logging sub-system
+ * \param[in] level Log level
+ * \param[in] file name of source code file
+ * \param[in] cont continuation (1) or new line (0)
+ * \param[in] format format string
+ * \param[in] ap vararg-list containing format string arguments
+ */
void osmo_vlogp(int subsys, int level, const char *file, int line,
int cont, const char *format, va_list ap)
{
@@ -376,7 +389,12 @@
}
}
-/*! \brief logging function used by DEBUGP() macro */
+/*! \brief logging function used by DEBUGP() macro
+ * \param[in] subsys Logging sub-system
+ * \param[in] file name of source code file
+ * \param[in] cont continuation (1) or new line (0)
+ * \param[in] format format string
+ */
void logp(int subsys, const char *file, int line, int cont,
const char *format, ...)
{
@@ -387,7 +405,13 @@
va_end(ap);
}
-/*! \brief logging function used by LOGP() macro */
+/*! \brief logging function used by LOGP() macro
+ * \param[in] subsys Logging sub-system
+ * \param[in] level Log level
+ * \param[in] file name of source code file
+ * \param[in] cont continuation (1) or new line (0)
+ * \param[in] format format string
+ */
void logp2(int subsys, unsigned int level, const char *file, int line, int cont, const char *format, ...)
{
va_list ap;
@@ -422,6 +446,7 @@
/*! \brief Set the logging context
* \param[in] ctx_nr logging context number
* \param[in] value value to which the context is to be set
+ * \returns 0 in case of success; negative otherwise
*
* A logging context is something like the subscriber identity to which
* the currently processed message relates, or the BTS through which it
@@ -537,7 +562,12 @@
fflush(target->tgt_file.out);
}
-/*! \brief Create a new log target skeleton */
+/*! \brief Create a new log target skeleton
+ * \returns dynamically-allocated log target
+ * This funcition allocates a \ref log_target and initializes it
+ * with some default values. The newly created target is not
+ * registered yet.
+ */
struct log_target *log_target_create(void)
{
struct log_target *target;
@@ -574,7 +604,8 @@
return target;
}
-/*! \brief Create the STDERR log target */
+/*! \brief Create the STDERR log target
+ * \returns dynamically-allocated \ref log_target for STDERR */
struct log_target *log_target_create_stderr(void)
{
/* since C89/C99 says stderr is a macro, we can safely do this! */
@@ -639,7 +670,8 @@
return NULL;
}
-/*! \brief Unregister, close and delete a log target */
+/*! \brief Unregister, close and delete a log target
+ * \param target[in] log target to unregister, close and delete */
void log_target_destroy(struct log_target *target)
{
@@ -661,7 +693,9 @@
talloc_free(target);
}
-/*! \brief close and re-open a log file (for log file rotation) */
+/*! \brief close and re-open a log file (for log file rotation)
+ * \param[in] target log target to re-open
+ * \returns 0 in case of success; negative otherwise */
int log_target_file_reopen(struct log_target *target)
{
fclose(target->tgt_file.out);
@@ -675,7 +709,8 @@
return 0;
}
-/*! \brief close and re-open a log file (for log file rotation) */
+/*! \brief close and re-open all log files (for log file rotation)
+ * \returns 0 in case of success; negative otherwise */
int log_targets_reopen(void)
{
struct log_target *tar;
@@ -697,6 +732,7 @@
/*! \brief Generates the logging command string for VTY
* \param[in] unused_info Deprecated parameter, no longer used!
+ * \returns vty command string for use by VTY command node
*/
const char *log_vty_command_string(const struct log_info *unused_info)
{
@@ -774,6 +810,7 @@
/*! \brief Generates the logging command description for VTY
* \param[in] unused_info Deprecated parameter, no longer used!
+ * \returns logging command description for use by VTY command node
*/
const char *log_vty_command_description(const struct log_info *unused_info)
{
diff --git a/src/macaddr.c b/src/macaddr.c
index a6e1304..f83e054 100644
--- a/src/macaddr.c
+++ b/src/macaddr.c
@@ -20,12 +20,24 @@
*
*/
+/*! \addtogroup utils
+ * @{
+ */
+
+/*! \file loggingrb.c */
+
#include <stdint.h>
#include <string.h>
#include <stdlib.h>
#include <unistd.h>
-
+/*! \brief Parse a MAC address from human-readable notation
+ * This function parses an ethernet MAC address in the commonly-used
+ * hex/colon notation (00:00:00:00:00:00) and generates the binary
+ * representation from it.
+ * \param[out] out pointer to caller-allocated buffer of 6 bytes
+ * \param[in] in pointer to input data as string with hex/colon notation
+ */
int osmo_macaddr_parse(uint8_t *out, const char *in)
{
/* 00:00:00:00:00:00 */
@@ -54,7 +66,11 @@
#include <net/if_dl.h>
#include <net/if_types.h>
-
+/*! \brief Obtain the MAC address of a given network device
+ * \param[out] mac_out pointer to caller-allocated buffer of 6 bytes
+ * \param[in] dev_name string name of the network device
+ * \returns 0 in case of success; negative otherwise
+ */
int osmo_get_macaddr(uint8_t *mac_out, const char *dev_name)
{
int rc = -1;
@@ -92,6 +108,11 @@
#include <netinet/in.h>
#include <netinet/ip.h>
+/*! \brief Obtain the MAC address of a given network device
+ * \param[out] mac_out pointer to caller-allocated buffer of 6 bytes
+ * \param[in] dev_name string name of the network device
+ * \returns 0 in case of success; negative otherwise
+ */
int osmo_get_macaddr(uint8_t *mac_out, const char *dev_name)
{
int fd, rc;
@@ -114,3 +135,5 @@
return 0;
}
#endif
+
+/*! @} */
diff --git a/src/msgb.c b/src/msgb.c
index 6361913..f09da90 100644
--- a/src/msgb.c
+++ b/src/msgb.c
@@ -40,6 +40,7 @@
/*! \brief Allocate a new message buffer
* \param[in] size Length in octets, including headroom
* \param[in] name Human-readable name to be associated with msgb
+ * \returns dynamically-allocated \ref msgb
*
* This function allocates a 'struct msgb' as well as the underlying
* memory buffer for the actual message data (size specified by \a size)
diff --git a/src/panic.c b/src/panic.c
index 84bab33..0ce50db 100644
--- a/src/panic.c
+++ b/src/panic.c
@@ -24,7 +24,9 @@
* @{
*/
-/*! \file panic.c */
+/*! \file panic.c
+ * \brief Routines for panic handling
+ */
#include <osmocom/gsm/gsm_utils.h>
#include <osmocom/core/panic.h>
@@ -58,7 +60,19 @@
#endif
-/*! \brief Terminate the current program with a panic */
+/*! \brief Terminate the current program with a panic
+ *
+ * You can call this function in case some severely unexpected situation
+ * is detected and the program is supposed to terminate in a way that
+ * reports the fact that it terminates.
+ *
+ * The application can register a panic handler function using \ref
+ * osmo_set_panic_handler. If it doesn't, a default panic handler
+ * function is called automatically.
+ *
+ * The default function on most systems will generate a backtrace and
+ * then abort() the process.
+ */
void osmo_panic(const char *fmt, ...)
{
va_list args;
@@ -74,7 +88,12 @@
}
-/*! \brief Set the panic handler */
+/*! \brief Set the panic handler
+ * \param[in] h New panic handler function
+ *
+ * This changes the panic handling function from the currently active
+ * function to a new call-back function supplied by the caller.
+ */
void osmo_set_panic_handler(osmo_panic_handler_t h)
{
osmo_panic_handler = h;
diff --git a/src/prim.c b/src/prim.c
index c2e7198..3f41c41 100644
--- a/src/prim.c
+++ b/src/prim.c
@@ -1,6 +1,8 @@
#include <osmocom/core/utils.h>
#include <osmocom/core/prim.h>
+/*! \brief human-readable string mapping for
+ * \ref osmo_prim_operation */
const struct value_string osmo_prim_op_names[5] = {
{ PRIM_OP_REQUEST, "request" },
{ PRIM_OP_RESPONSE, "response" },
diff --git a/src/rate_ctr.c b/src/rate_ctr.c
index 436deef..f995f3f 100644
--- a/src/rate_ctr.c
+++ b/src/rate_ctr.c
@@ -153,7 +153,10 @@
return 0;
}
-/*! \brief Search for counter group based on group name and index */
+/*! \brief Search for counter group based on group name and index
+ * \param[in] name Name of the counter group you're looking for
+ * \param[in] idx Index inside the counter group
+ * \returns \ref rate_ctr_group or NULL in case of error */
struct rate_ctr_group *rate_ctr_get_group_by_name_idx(const char *name, const unsigned int idx)
{
struct rate_ctr_group *ctrg;
@@ -170,7 +173,11 @@
return NULL;
}
-/*! \brief Search for counter group based on group name */
+/*! \brief Search for counter based on group + name
+ * \param[in] ctrg pointer to \ref rate_ctr_group
+ * \param[in] name name of counter inside group
+ * \returns \ref rate_ctr or NULL in caes of error
+ */
const struct rate_ctr *rate_ctr_get_by_name(const struct rate_ctr_group *ctrg, const char *name)
{
int i;
@@ -189,6 +196,12 @@
return NULL;
}
+/*! \brief Iterate over each counter in group and call function
+ * \param[in] counter group over whose counter to iterate
+ * \param[in] handle_counter function pointer
+ * \param[in] data Data to hand transparently to \ref handle_counter
+ * \returns 0 on success; negative otherwise
+ */
int rate_ctr_for_each_counter(struct rate_ctr_group *ctrg,
rate_ctr_handler_t handle_counter, void *data)
{
@@ -206,6 +219,11 @@
return rc;
}
+/*! \brief Iterate over all counter groups
+ * \param[in] handle_group function pointer of callback function
+ * \param[in] data Data to hand transparently to \ref handle_group
+ * \returns 0 on success; negative otherwise
+ */
int rate_ctr_for_each_group(rate_ctr_group_handler_t handle_group, void *data)
{
struct rate_ctr_group *statg;
@@ -220,5 +238,4 @@
return rc;
}
-
/*! @} */
diff --git a/src/select.c b/src/select.c
index 02bc2cc..192cae2 100644
--- a/src/select.c
+++ b/src/select.c
@@ -47,6 +47,7 @@
/*! \brief Register a new file descriptor with select loop abstraction
* \param[in] fd osmocom file descriptor to be registered
+ * \returns 0 on success; negative in case of error
*/
int osmo_fd_register(struct osmo_fd *fd)
{
@@ -160,6 +161,7 @@
/*! \brief select main loop integration
* \param[in] polling should we pollonly (1) or block on select (0)
+ * \returns 0 if no fd handled; 1 if fd handled; negative in case of error
*/
int osmo_select_main(int polling)
{
@@ -189,7 +191,9 @@
return osmo_fd_disp_fds(&readset, &writeset, &exceptset);
}
-/*! \brief find an osmo_fd based on the integer fd */
+/*! \brief find an osmo_fd based on the integer fd
+ * \param[in] fd file descriptor to use as search key
+ * \returns \ref osmo_fd for \ref fd; NULL in case it doesn't exist */
struct osmo_fd *osmo_fd_get_by_fd(int fd)
{
struct osmo_fd *ofd;
diff --git a/src/signal.c b/src/signal.c
index 6384384..8402591 100644
--- a/src/signal.c
+++ b/src/signal.c
@@ -46,6 +46,7 @@
* \param[in] subsys Subsystem number
* \param[in] cbfn Callback function
* \param[in] data Data passed through to callback
+ * \returns 0 on success; negative in case of error
*/
int osmo_signal_register_handler(unsigned int subsys,
osmo_signal_cbfn *cbfn, void *data)
diff --git a/src/socket.c b/src/socket.c
index 567939b..7e610bf 100644
--- a/src/socket.c
+++ b/src/socket.c
@@ -57,6 +57,7 @@
* \param[in] host remote host name or IP address in string form
* \param[in] port remote port number in host byte order
* \param[in] flags flags like \ref OSMO_SOCK_F_CONNECT
+ * \returns socket file descriptor on success; negative on error
*
* This function creates a new socket of the designated \a family, \a
* type and \a proto and optionally binds or connects it, depending on
@@ -153,6 +154,7 @@
/*! \brief fill \ref osmo_fd for a give sfd
* \param[out] ofd file descriptor (will be filled in)
* \param[in] sfd socket file descriptor
+ * \returns socket fd on success; negative on error
*
* This function fills the \a ofd structure.
*/
@@ -183,6 +185,7 @@
* \param[in] host remote host name or IP address in string form
* \param[in] port remote port number in host byte order
* \param[in] flags flags like \ref OSMO_SOCK_F_CONNECT
+ * \returns socket fd on success; negative on error
*
* This function creates (and optionall binds/connects) a socket using
* \ref osmo_sock_init, but also fills the \a ofd structure.
@@ -198,6 +201,7 @@
* \param[in] type Socket type like SOCK_DGRAM, SOCK_STREAM
* \param[in] proto Protocol like IPPROTO_TCP, IPPROTO_UDP
* \param[in] flags flags like \ref OSMO_SOCK_F_CONNECT
+ * \returns socket fd on success; negative on error
*
* This function creates (and optionall binds/connects) a socket using
* \ref osmo_sock_init, but also fills the \a ss structure.
@@ -294,6 +298,7 @@
* \param[in] proto Protocol like IPPROTO_TCP, IPPROTO_UDP
* \param[in] socket_path path to identify the socket
* \param[in] flags flags like \ref OSMO_SOCK_F_CONNECT
+ * \returns socket fd on success; negative on error
*
* This function creates a new unix domain socket, \a
* type and \a proto and optionally binds or connects it, depending on
@@ -365,6 +370,7 @@
* \param[in] proto Protocol like IPPROTO_TCP, IPPROTO_UDP
* \param[in] socket_path path to identify the socket
* \param[in] flags flags like \ref OSMO_SOCK_F_CONNECT
+ * \returns socket fd on success; negative on error
*
* This function creates (and optionall binds/connects) a socket using
* \ref osmo_sock_unix_init, but also fills the \a ofd structure.
diff --git a/src/timer.c b/src/timer.c
index 21b7015..0358b89 100644
--- a/src/timer.c
+++ b/src/timer.c
@@ -249,6 +249,8 @@
return work;
}
+/*! \brief Check how many timers we have in the system
+ * \returns number of \ref osmo_timer_list registered */
int osmo_timers_check(void)
{
struct rb_node *node;
diff --git a/src/write_queue.c b/src/write_queue.c
index 9a8b05c..3e488ae 100644
--- a/src/write_queue.c
+++ b/src/write_queue.c
@@ -33,6 +33,7 @@
/*! \brief Select loop function for write queue handling
* \param[in] fd osmocom file descriptor
* \param[in] what bit-mask of events that have happened
+ * \returns 0 on success; negative on error
*
* This function is provided so that it can be registered with the
* select loop abstraction code (\ref osmo_fd::cb).
@@ -99,6 +100,7 @@
/*! \brief Enqueue a new \ref msgb into a write queue
* \param[in] queue Write queue to be used
* \param[in] data to-be-enqueued message buffer
+ * \returns 0 on success; negative on error
*/
int osmo_wqueue_enqueue(struct osmo_wqueue *queue, struct msgb *data)
{