doxygen: enable AUTOBRIEF, drop \brief

Especially for short descriptions, it is annoying to have to type \brief for
every single API doc.

Drop all \brief and enable the AUTOBRIEF feature of doxygen, which always takes
the first sentence of an API doc as the brief description.

Change-Id: I11a8a821b065a128108641a2a63fb5a2b1916e87

59 files changed, 885 insertions, 885 deletions

diff --git a/include/osmocom/codec/codec.h b/include/osmocom/codec/codec.h
index 05da911e..3e9b6881 100644
--- a/include/osmocom/codec/codec.h
+++ b/include/osmocom/codec/codec.h
@@ -42,7 +42,7 @@ enum osmo_amr_quality {
        AMR_GOOD = 1
 };
 
-/*! \brief Check if given AMR Frame Type is a speech frame
+/*! Check if given AMR Frame Type is a speech frame
  *  \param[in] ft AMR Frame Type
  *  \returns true if AMR with given Frame Type contains voice, false otherwise
  */
diff --git a/include/osmocom/coding/gsm0503_coding.h b/include/osmocom/coding/gsm0503_coding.h
index 2f0e6315..a9c59e47 100644
--- a/include/osmocom/coding/gsm0503_coding.h
+++ b/include/osmocom/coding/gsm0503_coding.h
@@ -8,7 +8,7 @@
  */
 
 /*! \file gsm0503_coding.h
- *  \brief GSM TS 05.03 coding
+ *  GSM TS 05.03 coding
  */
 
 #define GSM0503_GPRS_BURSTS_NBITS	(116 * 4)
diff --git a/include/osmocom/coding/gsm0503_interleaving.h b/include/osmocom/coding/gsm0503_interleaving.h
index a5d25ed5..1463fb38 100644
--- a/include/osmocom/coding/gsm0503_interleaving.h
+++ b/include/osmocom/coding/gsm0503_interleaving.h
@@ -7,7 +7,7 @@
  */
 
 /*! \file gsm0503_interleaving.h
- *  \brief GSM TS 05.03 interleaving
+ *  GSM TS 05.03 interleaving
  */
 
 void gsm0503_xcch_deinterleave(sbit_t *cB, const sbit_t *iB);
diff --git a/include/osmocom/coding/gsm0503_mapping.h b/include/osmocom/coding/gsm0503_mapping.h
index 6e139bf0..435c9131 100644
--- a/include/osmocom/coding/gsm0503_mapping.h
+++ b/include/osmocom/coding/gsm0503_mapping.h
@@ -7,7 +7,7 @@
  */
 
 /*! \file gsm0503_mapping.c
- *  \brief GSM TS 05.03 burst mapping
+ *  GSM TS 05.03 burst mapping
  */
 
 void gsm0503_xcch_burst_unmap(sbit_t *iB, const sbit_t *eB,
diff --git a/include/osmocom/coding/gsm0503_parity.h b/include/osmocom/coding/gsm0503_parity.h
index f844720b..2743bdb1 100644
--- a/include/osmocom/coding/gsm0503_parity.h
+++ b/include/osmocom/coding/gsm0503_parity.h
@@ -7,7 +7,7 @@
  */
 
 /*! \file gsm0503_parity.h
- *  \brief GSM TS 05.03 parity
+ *  GSM TS 05.03 parity
  */
 
 const struct osmo_crc64gen_code gsm0503_fire_crc40;
diff --git a/include/osmocom/coding/gsm0503_tables.h b/include/osmocom/coding/gsm0503_tables.h
index 4622cae7..f8c43c61 100644
--- a/include/osmocom/coding/gsm0503_tables.h
+++ b/include/osmocom/coding/gsm0503_tables.h
@@ -8,7 +8,7 @@
  */
 
 /*! \file gsm0503_tables.h
- *  \brief GSM TS 05.03 tables
+ *  GSM TS 05.03 tables
  */
 
 extern const ubit_t gsm0503_pdtch_hl_hn_ubit[4][8];
diff --git a/include/osmocom/core/application.h b/include/osmocom/core/application.h
index ecaeaa8a..266fa9bb 100644
--- a/include/osmocom/core/application.h
+++ b/include/osmocom/core/application.h
@@ -2,16 +2,16 @@
 
 /*!
  * \file application.h
- * \brief Routines for helping with the osmocom application setup.
+ * Routines for helping with the osmocom application setup.
  */
 
-/*! \brief information containing the available logging subsystems */
+/*! information containing the available logging subsystems */
 struct log_info;
 
-/*! \brief one instance of a logging target (file, stderr, ...) */
+/*! one instance of a logging target (file, stderr, ...) */
 struct log_target;
 
-/*! \brief the default logging target, logging to stderr */
+/*! the default logging target, logging to stderr */
 extern struct log_target *osmo_stderr_target;
 
 void osmo_init_ignore_signals(void);
diff --git a/include/osmocom/core/bitXXgen.h.tpl b/include/osmocom/core/bitXXgen.h.tpl
index 7480a8f4..6881d87d 100644
--- a/include/osmocom/core/bitXXgen.h.tpl
+++ b/include/osmocom/core/bitXXgen.h.tpl
@@ -22,7 +22,7 @@
 
 #pragma once
 
-/*! \brief load unaligned n-byte integer (little-endian encoding) into uintXX_t
+/*! load unaligned n-byte integer (little-endian encoding) into uintXX_t
  *  \param[in] p Buffer where integer is stored
  *  \param[in] n Number of bytes stored in p
  *  \returns XX bit unsigned integer
@@ -36,7 +36,7 @@ static inline uintXX_t osmo_loadXXle_ext(const void *p, uint8_t n)
 	return r;
 }
 
-/*! \brief load unaligned n-byte integer (big-endian encoding) into uintXX_t
+/*! load unaligned n-byte integer (big-endian encoding) into uintXX_t
  *  \param[in] p Buffer where integer is stored
  *  \param[in] n Number of bytes stored in p
  *  \returns XX bit unsigned integer
@@ -51,7 +51,7 @@ static inline uintXX_t osmo_loadXXbe_ext(const void *p, uint8_t n)
 }
 
 
-/*! \brief store unaligned n-byte integer (little-endian encoding) from uintXX_t
+/*! store unaligned n-byte integer (little-endian encoding) from uintXX_t
  *  \param[in] x unsigned XX bit integer
  *  \param[out] p Buffer to store integer
  *  \param[in] n Number of bytes to store
@@ -63,7 +63,7 @@ static inline void osmo_storeXXle_ext(uintXX_t x, void *p, uint8_t n)
 	for(i = 0; i < n; q[i] = (x >> i * 8) & 0xFF, i++);
 }
 
-/*! \brief store unaligned n-byte integer (big-endian encoding) from uintXX_t
+/*! store unaligned n-byte integer (big-endian encoding) from uintXX_t
  *  \param[in] x unsigned XX bit integer
  *  \param[out] p Buffer to store integer
  *  \param[in] n Number of bytes to store
@@ -79,26 +79,26 @@ static inline void osmo_storeXXbe_ext(uintXX_t x, void *p, uint8_t n)
 /* Convenience function for most-used cases */
 
 
-/*! \brief load unaligned XX-bit integer (little-endian encoding) */
+/*! load unaligned XX-bit integer (little-endian encoding) */
 static inline uintXX_t osmo_loadXXle(const void *p)
 {
 	return osmo_loadXXle_ext(p, XX / 8);
 }
 
-/*! \brief load unaligned XX-bit integer (big-endian encoding) */
+/*! load unaligned XX-bit integer (big-endian encoding) */
 static inline uintXX_t osmo_loadXXbe(const void *p)
 {
 	return osmo_loadXXbe_ext(p, XX / 8);
 }
 
 
-/*! \brief store unaligned XX-bit integer (little-endian encoding) */
+/*! store unaligned XX-bit integer (little-endian encoding) */
 static inline void osmo_storeXXle(uintXX_t x, void *p)
 {
 	osmo_storeXXle_ext(x, p, XX / 8);
 }
 
-/*! \brief store unaligned XX-bit integer (big-endian encoding) */
+/*! store unaligned XX-bit integer (big-endian encoding) */
 static inline void osmo_storeXXbe(uintXX_t x, void *p)
 {
 	osmo_storeXXbe_ext(x, p, XX / 8);
diff --git a/include/osmocom/core/bitcomp.h b/include/osmocom/core/bitcomp.h
index e87c0e10..a184a1cf 100644
--- a/include/osmocom/core/bitcomp.h
+++ b/include/osmocom/core/bitcomp.h
@@ -27,7 +27,7 @@
  */
 
 /*! \file bitcomp.h
- *  \brief Osmocom bit compression routines
+ *  Osmocom bit compression routines
  */
 
 #include <stdint.h>
diff --git a/include/osmocom/core/bits.h b/include/osmocom/core/bits.h
index 5535920e..61af716c 100644
--- a/include/osmocom/core/bits.h
+++ b/include/osmocom/core/bits.h
@@ -12,18 +12,18 @@
  */
 
 /*! \file bits.h
- *  \brief Osmocom bit level support code
+ *  Osmocom bit level support code
  *
  *  NOTE on the endianess of pbit_t:
  *  Bits in a pbit_t are ordered MSB first, i.e. 0x80 is the first bit.
  *  Bit i in a pbit_t array is array[i/8] & (1<<(7-i%8))
  */
 
-typedef int8_t  sbit_t;		/*!< \brief soft bit (-127...127) */
-typedef uint8_t ubit_t;		/*!< \brief unpacked bit (0 or 1) */
-typedef uint8_t pbit_t;		/*!< \brief packed bis (8 bits in a byte) */
+typedef int8_t  sbit_t;		/*!< soft bit (-127...127) */
+typedef uint8_t ubit_t;		/*!< unpacked bit (0 or 1) */
+typedef uint8_t pbit_t;		/*!< packed bis (8 bits in a byte) */
 
-/*! \brief determine how many bytes we would need for \a num_bits packed bits
+/*! determine how many bytes we would need for \a num_bits packed bits
  *  \param[in] num_bits Number of packed bits
  *  \returns number of bytes needed for \a num_bits packed bits
  */
@@ -81,31 +81,31 @@ int osmo_pbit2ubit_ext(ubit_t *out, unsigned int out_ofs,
 
 /* BIT REVERSAL */
 
-/*! \brief bit-reversal mode for osmo_bit_reversal() */
+/*! bit-reversal mode for osmo_bit_reversal() */
 enum osmo_br_mode {
-	/*! \brief reverse all bits in a 32bit dword */
+	/*! reverse all bits in a 32bit dword */
 	OSMO_BR_BITS_IN_DWORD	= 31,
-	/*! \brief reverse byte order in a 32bit dword */
+	/*! reverse byte order in a 32bit dword */
 	OSMO_BR_BYTES_IN_DWORD	= 24,
-	/*! \brief reverse bits of each byte in a 32bit dword */
+	/*! reverse bits of each byte in a 32bit dword */
 	OSMO_BR_BITS_IN_BYTE	= 7,
-	/*! \brief swap the two 16bit words in a 32bit dword */
+	/*! swap the two 16bit words in a 32bit dword */
 	OSMO_BR_WORD_SWAP	= 16,
 };
 
-/*! \brief generic bit reversal function */
+/*! generic bit reversal function */
 uint32_t osmo_bit_reversal(uint32_t x, enum osmo_br_mode k);
 
-/* \brief reverse the bits within each byte of a 32bit word */
+/* reverse the bits within each byte of a 32bit word */
 uint32_t osmo_revbytebits_32(uint32_t x);
 
-/* \brief reverse the bits within a byte */
+/* reverse the bits within a byte */
 uint32_t osmo_revbytebits_8(uint8_t x);
 
-/* \brief reverse the bits of each byte in a given buffer */
+/* reverse the bits of each byte in a given buffer */
 void osmo_revbytebits_buf(uint8_t *buf, int len);
 
-/*! \brief left circular shift
+/*! left circular shift
  *  \param[in] in The 16 bit unsigned integer to be rotated
  *  \param[in] shift Number of bits to shift \a in to, [0;16] bits
  *  \returns shifted value
diff --git a/include/osmocom/core/bitvec.h b/include/osmocom/core/bitvec.h
index 6944770c..9187ce23 100644
--- a/include/osmocom/core/bitvec.h
+++ b/include/osmocom/core/bitvec.h
@@ -29,7 +29,7 @@
  */
 
 /*! \file bitvec.h
- *  \brief Osmocom bit vector abstraction
+ *  Osmocom bit vector abstraction
  *
  *  These functions assume a MSB (most significant bit) first layout of the
  *  bits, so that for instance the 5 bit number abcde (a is MSB) can be
@@ -44,22 +44,22 @@
 #include <osmocom/core/talloc.h>
 #include <stdbool.h>
 
-/*! \brief A single GSM bit
+/*! A single GSM bit
  *
  * In GSM mac blocks, every bit can be 0 or 1, or L or H.  L/H are
  * defined relative to the 0x2b padding pattern */
 enum bit_value {
-	ZERO	= 0, 	/*!< \brief A zero (0) bit */
-	ONE	= 1,	/*!< \brief A one (1) bit */
-	L	= 2,	/*!< \brief A CSN.1 "L" bit */
-	H	= 3,	/*!< \brief A CSN.1 "H" bit */
+	ZERO	= 0, 	/*!< A zero (0) bit */
+	ONE	= 1,	/*!< A one (1) bit */
+	L	= 2,	/*!< A CSN.1 "L" bit */
+	H	= 3,	/*!< A CSN.1 "H" bit */
 };
 
-/*! \brief structure describing a bit vector */
+/*! structure describing a bit vector */
 struct bitvec {
-	unsigned int cur_bit;	/*!< \brief cursor to the next unused bit */
-	unsigned int data_len;	/*!< \brief length of data array in bytes */
-	uint8_t *data;		/*!< \brief pointer to data array */
+	unsigned int cur_bit;	/*!< cursor to the next unused bit */
+	unsigned int data_len;	/*!< length of data array in bytes */
+	uint8_t *data;		/*!< pointer to data array */
 };
 
 enum bit_value bitvec_get_bit_pos(const struct bitvec *bv, unsigned int bitnr);
diff --git a/include/osmocom/core/byteswap.h b/include/osmocom/core/byteswap.h
index 1f09c2b1..4274b8fb 100644
--- a/include/osmocom/core/byteswap.h
+++ b/include/osmocom/core/byteswap.h
@@ -2,7 +2,7 @@
 #include <stdint.h>
 #include <osmocom/core/endian.h>
 
-/*! \brief byte-swap a 32bit word
+/*! byte-swap a 32bit word
  *  \param[in] in to be swapped 32bit word
  *  \returns byte-swapped 32bit word */
 static inline uint32_t osmo_swab32(uint32_t in)
@@ -17,7 +17,7 @@ static inline uint32_t osmo_swab32(uint32_t in)
 	return out;
 }
 
-/*! \brief byte-swap a 16bit word
+/*! byte-swap a 16bit word
  *  \param[in] in to be swapped 16bit word
  *  \returns byte-swapped 16bit word */
 static inline uint16_t osmo_swab16(uint16_t in)
diff --git a/include/osmocom/core/conv.h b/include/osmocom/core/conv.h
index e7f6bd6a..1888fe13 100644
--- a/include/osmocom/core/conv.h
+++ b/include/osmocom/core/conv.h
@@ -34,7 +34,7 @@
 
 #include <osmocom/core/bits.h>
 
-/*! \brief possibe termination types
+/*! possibe termination types
  *
  *  The termination type will determine which state the encoder/decoder
  *  can start/end with. This is mostly taken care of in the high level API
@@ -42,31 +42,31 @@
  *  proper calls yourself.
  */
 enum osmo_conv_term {
-	CONV_TERM_FLUSH = 0,	/*!< \brief Flush encoder state */
-	CONV_TERM_TRUNCATION,	/*!< \brief Direct truncation */
-	CONV_TERM_TAIL_BITING,	/*!< \brief Tail biting */
+	CONV_TERM_FLUSH = 0,	/*!< Flush encoder state */
+	CONV_TERM_TRUNCATION,	/*!< Direct truncation */
+	CONV_TERM_TAIL_BITING,	/*!< Tail biting */
 };
 
-/*! \brief structure describing a given convolutional code
+/*! structure describing a given convolutional code
  *
  *  The only required fields are N,K and the next_output/next_state arrays. The
  *  other can be left to default value of zero depending on what the code does.
  *  If 'len' is left at 0 then only the low level API can be used.
  */
 struct osmo_conv_code {
-	int N;				/*!< \brief Inverse of code rate */
-	int K;				/*!< \brief Constraint length */
-	int len;			/*!< \brief # of data bits */
+	int N;				/*!< Inverse of code rate */
+	int K;				/*!< Constraint length */
+	int len;			/*!< # of data bits */
 
-	enum osmo_conv_term term;	/*!< \brief Termination type */
+	enum osmo_conv_term term;	/*!< Termination type */
 
-	const uint8_t (*next_output)[2];/*!< \brief Next output array */
-	const uint8_t (*next_state)[2];	/*!< \brief Next state array  */
+	const uint8_t (*next_output)[2];/*!< Next output array */
+	const uint8_t (*next_state)[2];	/*!< Next state array  */
 
-	const uint8_t *next_term_output;/*!< \brief Flush termination output */
-	const uint8_t *next_term_state;	/*!< \brief Flush termination state  */
+	const uint8_t *next_term_output;/*!< Flush termination output */
+	const uint8_t *next_term_state;	/*!< Flush termination state  */
 
-	const int *puncture;		/*!< \brief Punctured bits indexes */
+	const int *puncture;		/*!< Punctured bits indexes */
 };
 
 
@@ -80,12 +80,12 @@ int osmo_conv_get_output_length(const struct osmo_conv_code *code, int len);
 
 	/* Low level API */
 
-/*! \brief convolutional encoder state */
+/*! convolutional encoder state */
 struct osmo_conv_encoder {
-	const struct osmo_conv_code *code; /*!< \brief for which code? */
-	int i_idx;	/*!< \brief Next input bit index */
-	int p_idx;	/*!< \brief Current puncture index */
-	uint8_t state;	/*!< \brief Current state */
+	const struct osmo_conv_code *code; /*!< for which code? */
+	int i_idx;	/*!< Next input bit index */
+	int p_idx;	/*!< Current puncture index */
+	uint8_t state;	/*!< Current state */
 };
 
 void osmo_conv_encode_init(struct osmo_conv_encoder *encoder,
@@ -105,20 +105,20 @@ int  osmo_conv_encode(const struct osmo_conv_code *code,
 
 	/* Low level API */
 
-/*! \brief convolutional decoder state */
+/*! convolutional decoder state */
 struct osmo_conv_decoder {
-	const struct osmo_conv_code *code; /*!< \brief for which code? */
+	const struct osmo_conv_code *code; /*!< for which code? */
 
-	int n_states;		/*!< \brief number of states */
+	int n_states;		/*!< number of states */
 
-	int len;		/*!< \brief Max o_idx (excl. termination) */
+	int len;		/*!< Max o_idx (excl. termination) */
 
-	int o_idx;		/*!< \brief output index */
-	int p_idx;		/*!< \brief puncture index */
+	int o_idx;		/*!< output index */
+	int p_idx;		/*!< puncture index */
 
-	unsigned int *ae;	/*!< \brief accumulated error */
-	unsigned int *ae_next;	/*!< \brief next accumulated error (tmp in scan) */
-	uint8_t *state_history;	/*!< \brief state history [len][n_states] */
+	unsigned int *ae;	/*!< accumulated error */
+	unsigned int *ae_next;	/*!< next accumulated error (tmp in scan) */
+	uint8_t *state_history;	/*!< state history [len][n_states] */
 };
 
 void osmo_conv_decode_init(struct osmo_conv_decoder *decoder,
diff --git a/include/osmocom/core/crcXXgen.h.tpl b/include/osmocom/core/crcXXgen.h.tpl
index 164f7201..47188090 100644
--- a/include/osmocom/core/crcXXgen.h.tpl
+++ b/include/osmocom/core/crcXXgen.h.tpl
@@ -35,12 +35,12 @@
 #include <osmocom/core/bits.h>
 
 
-/*! \brief structure describing a given CRC code of max XX bits */
+/*! structure describing a given CRC code of max XX bits */
 struct osmo_crcXXgen_code {
-	int bits;           /*!< \brief Actual number of bits of the CRC */
-	uintXX_t poly;      /*!< \brief Polynom (normal representation, MSB omitted */
-	uintXX_t init;      /*!< \brief Initialization value of the CRC state */
-	uintXX_t remainder; /*!< \brief Remainder of the CRC (final XOR) */
+	int bits;           /*!< Actual number of bits of the CRC */
+	uintXX_t poly;      /*!< Polynom (normal representation, MSB omitted */
+	uintXX_t init;      /*!< Initialization value of the CRC state */
+	uintXX_t remainder; /*!< Remainder of the CRC (final XOR) */
 };
 
 uintXX_t osmo_crcXXgen_compute_bits(const struct osmo_crcXXgen_code *code,
diff --git a/include/osmocom/core/defs.h b/include/osmocom/core/defs.h
index 51ac4e51..88c41b91 100644
--- a/include/osmocom/core/defs.h
+++ b/include/osmocom/core/defs.h
@@ -5,10 +5,10 @@
  */
 
 /*! \file defs.h
- *  \brief General definitions that are meant to be included from header files.
+ *  General definitions that are meant to be included from header files.
  */
 
-/*! \brief Check for gcc and version.
+/*! Check for gcc and version.
  *
  * \note Albeit glibc provides a features.h file that contains a similar
  *       definition (__GNUC_PREREQ), this definition has been copied from there
@@ -23,7 +23,7 @@
 # define OSMO_GNUC_PREREQ(maj, min) 0
 #endif
 
-/*! \brief Set the deprecated attribute with a message.
+/*! Set the deprecated attribute with a message.
  */
 #if defined(__clang__)
 # define _OSMO_HAS_ATTRIBUTE_DEPRECATED __has_attribute(deprecated)
diff --git a/include/osmocom/core/fsm.h b/include/osmocom/core/fsm.h
index f42dd0c6..fb182f35 100644
--- a/include/osmocom/core/fsm.h
+++ b/include/osmocom/core/fsm.h
@@ -12,21 +12,21 @@
  */
 
 /*! \file fsm.h
- *  \brief Finite State Machine
+ *  Finite State Machine
  */
 
 struct osmo_fsm_inst;
 
 enum osmo_fsm_term_cause {
-	/*! \brief terminate because parent terminated */
+	/*! terminate because parent terminated */
 	OSMO_FSM_TERM_PARENT,
-	/*! \brief terminate on explicit user request */
+	/*! terminate on explicit user request */
 	OSMO_FSM_TERM_REQUEST,
-	/*! \brief regular termination of process */
+	/*! regular termination of process */
 	OSMO_FSM_TERM_REGULAR,
-	/*! \brief erroneous termination of process */
+	/*! er