update/extend doxygen documentation

It's a pity that even with this patch we still are fare away from having
the whole API documented.  However, at least we have a more solid
foundation.  Updates not only extend the documentation, but also make
sure it is rendered properly in the doxygen HTML.

Change-Id: I1344bd1a6869fb00de7c1899a8db93bba9bafce3

30 files changed, 663 insertions, 98 deletions

diff --git a/src/gsm/a5.c b/src/gsm/a5.c
index dbba0f20..23cbe0c9 100644
--- a/src/gsm/a5.c
+++ b/src/gsm/a5.c
@@ -26,13 +26,12 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  */
 
-/*! \addtogroup a5
+/*! \addtogroup crypto
  *  @{
+ *  \brief Osmocom GSM/GPRS ciphering algorithm implementation
  */
 
-/*! \file gsm/a5.c
- *  \brief Osmocom GSM A5 ciphering algorithm implementation
- */
+/*! \file gsm/a5.c */
 
 #include <errno.h>
 #include <string.h>
diff --git a/src/gsm/abis_nm.c b/src/gsm/abis_nm.c
index 73759cbd..c9549027 100644
--- a/src/gsm/abis_nm.c
+++ b/src/gsm/abis_nm.c
@@ -22,6 +22,8 @@
 
 /*! \addtogroup oml
  *  @{
+ * \brief GSM Network Management (OML) messages on the A-bis interface
+ * 3GPP TS 12.21 version 8.0.0 Release 1999 / ETSI TS 100 623 V8.0.0
  */
 
 /*! \file abis_nm.c */
diff --git a/src/gsm/auth_comp128v1.c b/src/gsm/auth_comp128v1.c
index c40027ee..3b645d2a 100644
--- a/src/gsm/auth_comp128v1.c
+++ b/src/gsm/auth_comp128v1.c
@@ -24,6 +24,10 @@
 #include <osmocom/crypt/auth.h>
 #include <osmocom/gsm/comp128.h>
 
+/*! \addtogroup auth
+ *  @{
+ */
+
 static int c128v1_gen_vec(struct osmo_auth_vector *vec,
 			  struct osmo_sub_auth_data *aud,
 			  const uint8_t *_rand)
@@ -45,3 +49,5 @@ static __attribute__((constructor)) void on_dso_load_c128(void)
 {
 	osmo_auth_register(&c128v1_alg);
 }
+
+/*! @} */
diff --git a/src/gsm/auth_comp128v23.c b/src/gsm/auth_comp128v23.c
index 168f8865..b0900af2 100644
--- a/src/gsm/auth_comp128v23.c
+++ b/src/gsm/auth_comp128v23.c
@@ -27,6 +27,10 @@
 #include <osmocom/crypt/auth.h>
 #include <osmocom/gsm/comp128v23.h>
 
+/*! \addtogroup auth
+ *  @{
+ */
+
 static int c128v2_gen_vec(struct osmo_auth_vector *vec,
 			  struct osmo_sub_auth_data *aud,
 			  const uint8_t *_rand)
@@ -66,3 +70,5 @@ static __attribute__((constructor)) void on_dso_load_c128(void)
 	osmo_auth_register(&c128v2_alg);
 	osmo_auth_register(&c128v3_alg);
 }
+
+/*! @} */
diff --git a/src/gsm/auth_core.c b/src/gsm/auth_core.c
index 9ca5d93b..c9e403c5 100644
--- a/src/gsm/auth_core.c
+++ b/src/gsm/auth_core.c
@@ -32,10 +32,10 @@
 
 /*! \addtogroup auth
  *  @{
+ *  \brief GSM/GPRS/3G authentication core infrastructure
  */
 
-/* \file auth_core.c
- */
+/* \file auth_core.c */
 
 static LLIST_HEAD(osmo_auths);
 
diff --git a/src/gsm/auth_milenage.c b/src/gsm/auth_milenage.c
index c1331b5b..41e538d2 100644
--- a/src/gsm/auth_milenage.c
+++ b/src/gsm/auth_milenage.c
@@ -25,6 +25,10 @@
 #include "milenage/common.h"
 #include "milenage/milenage.h"
 
+/*! \addtogroup auth
+ *  @{
+ */
+
 static int milenage_gen_vec(struct osmo_auth_vector *vec,
 			    struct osmo_sub_auth_data *aud,
 			    const uint8_t *_rand)
@@ -160,3 +164,5 @@ static __attribute__((constructor)) void on_dso_load_milenage(void)
 {
 	osmo_auth_register(&milenage_alg);
 }
+
+/*! @} */
diff --git a/src/gsm/comp128.c b/src/gsm/comp128.c
index abb49179..cb3a3092 100644
--- a/src/gsm/comp128.c
+++ b/src/gsm/comp128.c
@@ -68,6 +68,14 @@
 #include <string.h>
 #include <stdint.h>
 
+/*! \addtogroup auth
+ *  @{
+ */
+
+/*! \file comp128.c
+ *  \brief COMP128 v1; common/old GSM Authentication Algorithm (A3/A8)
+ */
+
 /* The compression tables (just copied ...) */
 static const uint8_t table_0[512] = {
  102, 177, 186, 162,   2, 156, 112,  75,  55,  25,   8,  12, 251, 193, 246, 188,
@@ -184,6 +192,11 @@ _comp128_permutation(uint8_t *x, uint8_t *bits)
 		x[(i>>3)+16] |= bits[(i*17) & 127] << (7-(i&7));
 }
 
+/*! \brief Perform COMP128v1 algorithm
+ *  \param[in] ki Secret Key K(i) of subscriber
+ *  \param[in] rand Random Challenge
+ *  \param[out] sres user-supplied buffer for storing computed SRES value
+ *  \param[out] kc user-supplied buffer for storing computed Kc value */
 void
 comp128v1(const uint8_t *ki, const uint8_t *rand, uint8_t *sres, uint8_t *kc)
 {
@@ -228,8 +241,16 @@ comp128v1(const uint8_t *ki, const uint8_t *rand, uint8_t *sres, uint8_t *kc)
 	kc[7] = 0;
 }
 
+
+/*! \brief Perform COMP128v1 algorithm
+ *  \param[in] ki Secret Key K(i) of subscriber
+ *  \param[in] rand Random Challenge
+ *  \param[out] sres user-supplied buffer for storing computed SRES value
+ *  \param[out] kc user-supplied buffer for storing computed Kc value */
 void
 comp128(const uint8_t *ki, const uint8_t *rand, uint8_t *sres, uint8_t *kc)
 {
     comp128v1(ki, rand, sres, kc);
 }
+
+/*! @} */
diff --git a/src/gsm/comp128v23.c b/src/gsm/comp128v23.c
index e21b718e..bfb4a0ee 100644
--- a/src/gsm/comp128v23.c
+++ b/src/gsm/comp128v23.c
@@ -28,6 +28,14 @@
 #include <stdint.h>
 #include <string.h>
 
+/*! \addtogroup auth
+ *  @{
+ */
+
+/*! \file comp128v23.c
+ *  \brief COMP128 v2 / v3; Common Algorithm used for GSM Authentication (A3/A8)
+ */
+
 static const uint8_t table0[256] = {
 	197, 235, 60, 151, 98, 96, 3, 100, 248, 118, 42, 117, 172, 211, 181, 203, 61,
 	126, 156, 87, 149, 224, 55, 132, 186, 63, 238, 255, 85, 83, 152, 33, 160,
@@ -101,6 +109,12 @@ _comp128v23_internal(uint8_t *output, const uint8_t *kxor, const uint8_t *rand)
 	}
 }
 
+/*! \brief Perform COMP128v3 algorithm
+ *  \param[in] ki Secret Key K(i) of subscriber
+ *  \param[in] rand Random Challenge
+ *  \param[out] sres user-supplied buffer for storing computed SRES value
+ *  \param[out] kc user-supplied buffer for storing computed Kc value
+ *  \returns 0 */
 int
 comp128v3(const uint8_t *ki, const uint8_t *rand, uint8_t *sres, uint8_t *kc)
 {
@@ -147,6 +161,12 @@ comp128v3(const uint8_t *ki, const uint8_t *rand, uint8_t *sres, uint8_t *kc)
 	return 0;
 }
 
+/*! \brief Perform COMP128v2 algorithm
+ *  \param[in] ki Secret Key K(i) of subscriber
+ *  \param[in] rand Random Challenge
+ *  \param[out] sres user-supplied buffer for storing computed SRES value
+ *  \param[out] kc user-supplied buffer for storing computed Kc value
+ *  \returns 0 */
 int
 comp128v2(const uint8_t *ki, const uint8_t *rand, uint8_t *sres, uint8_t *kc)
 {
@@ -155,3 +175,5 @@ comp128v2(const uint8_t *ki, const uint8_t *rand, uint8_t *sres, uint8_t *kc)
 	kc[6] &= 0xfc;
 	return r;
 }
+
+/*! @} */
diff --git a/src/gsm/gan.c b/src/gsm/gan.c
index 0bcaa175..1d98b38b 100644
--- a/src/gsm/gan.c
+++ b/src/gsm/gan.c
@@ -21,6 +21,10 @@
 
 #include <osmocom/gsm/protocol/gsm_44_318.h>
 
+/*! \file gan.c
+ *  \brief Generic Access Network (GAN) / UMA according to TS 44.318
+ */
+
 
 const struct value_string gan_msgt_vals[] = {
 	{ GA_MT_RC_DISCOVERY_REQUEST,	"GA-RC DISCOVERY REQUEST" },
diff --git a/src/gsm/gea.c b/src/gsm/gea.c
index b8f6768a..8d026a29 100644
--- a/src/gsm/gea.c
+++ b/src/gsm/gea.c
@@ -30,6 +30,13 @@
 #include <stdint.h>
 #include <string.h>
 
+/*! \addtogroup crypto
+ *  @{
+ */
+
+/*! \file gsm/gea.c */
+
+
 /*! \brief Performs the GEA4 algorithm as in 3GPP TS 55.226 V9.0.0
  *  \param[in,out] out Buffer for gamma for encrypted/decrypted
  *  \param[in] len Length of out, in bytes
@@ -58,3 +65,5 @@ int gea3(uint8_t *out, uint16_t len, uint8_t *kc, uint32_t iv,
 	osmo_c4(ck, kc);
 	return gea4(out, len, ck, iv, direction);
 }
+
+/*! @} */
diff --git a/src/gsm/gprs_cipher_core.c b/src/gsm/gprs_cipher_core.c
index da6e0a83..a0cf1851 100644
--- a/src/gsm/gprs_cipher_core.c
+++ b/src/gsm/gprs_cipher_core.c
@@ -29,6 +29,10 @@
 
 #include <osmocom/crypt/gprs_cipher.h>
 
+/*! \addtogroup crypto
+ *  @{
+ */
+
 static LLIST_HEAD(gprs_ciphers);
 
 static struct gprs_cipher_impl *selected_ciphers[_GPRS_ALGO_NUM];
@@ -125,3 +129,4 @@ uint32_t gprs_cipher_gen_input_i(uint32_t iov_i, uint32_t lfn, uint32_t oc)
 {
 	return iov_i + lfn + oc;
 }
+/*! @} */
diff --git a/src/gsm/gprs_gea.c b/src/gsm/gprs_gea.c
index 8ff16484..836ee68c 100644
--- a/src/gsm/gprs_gea.c
+++ b/src/gsm/gprs_gea.c
@@ -27,6 +27,10 @@
 
 #include <stdint.h>
 
+/*! \addtogroup crypto
+ *  @{
+ */
+
 static struct gprs_cipher_impl gea3_impl = {
 	.algo = GPRS_ALGO_GEA3,
 	.name = "GEA3 (libosmogsm built-in)",
@@ -46,3 +50,5 @@ static __attribute__((constructor)) void on_dso_load_gea(void)
 	gprs_cipher_register(&gea3_impl);
 	gprs_cipher_register(&gea4_impl);
 }
+
+/*! @} */
diff --git a/src/gsm/gprs_rlc.c b/src/gsm/gprs_rlc.c
index a4053ef6..d1247be6 100644
--- a/src/gsm/gprs_rlc.c
+++ b/src/gsm/gprs_rlc.c
@@ -5,6 +5,10 @@
 #include <osmocom/coding/gsm0503_coding.h>
 #include <osmocom/gprs/protocol/gsm_04_60.h>
 
+/*! \file gsm/gprs_rlc.c
+ *  \brief helper functions for (E)GPRS RLC according to 3GPP TS 44.060
+ */
+
 #define EGPRS_CPS_TYPE1_TBL_SZ		29
 #define EGPRS_CPS_TYPE2_TBL_SZ		8
 #define EGPRS_CPS_TYPE3_TBL_SZ		16
diff --git a/src/gsm/gsm0341.c b/src/gsm/gsm0341.c
index 1c14d3ed..2592b54e 100644
--- a/src/gsm/gsm0341.c
+++ b/src/gsm/gsm0341.c
@@ -27,6 +27,22 @@
 #include <osmocom/core/talloc.h>
 #include <osmocom/gsm/protocol/gsm_03_41.h>
 
+/*! \addtogroup sms
+ *  @{
+ */
+
+/*! \brief Encode a 3GPP TS 03.41 SMS-CB message
+ *  \param[in] ctx talloc allocation context
+ *  \param[in] geo_scope Geographic Scope
+ *  \param[in] msg_code Message Code
+ *  \param[in] update Is this an update?
+ *  \param[in] msg_id Message ID
+ *  \param[in] dcs Data Coding Scheme
+ *  \param[in] page_total Total number of pages
+ *  \param[in] page_cur Current Page (up to \a page_total)
+ *  \param[in] data Message data (copied 1:1)
+ *  \param[in] len Length of \a data in bytes (up to 88)
+ *  \returns callee-allocated TS 03.41 message with encoded data */
 struct gsm341_ms_message *
 gsm0341_build_msg(void *ctx, uint8_t geo_scope, uint8_t msg_code,
 		  uint8_t update, uint16_t msg_id, uint8_t dcs,
@@ -57,3 +73,5 @@ gsm0341_build_msg(void *ctx, uint8_t geo_scope, uint8_t msg_code,
 
 	return cbmsg;
 }
+
+/*! @} */
diff --git a/src/gsm/gsm0411_smc.c b/src/gsm/gsm0411_smc.c
index 4c083659..03016b92 100644
--- a/src/gsm/gsm0411_smc.c
+++ b/src/gsm/gsm0411_smc.c
@@ -60,6 +60,11 @@
 #include <osmocom/gsm/gsm0411_smc.h>
 #include <osmocom/gsm/protocol/gsm_04_08.h>
 
+/*! \addtogroup sms
+ *  @{
+ *  \brief Point-to-Point (PP) Short Message Service (SMS) as per TS 04.11
+ */
+
 static void cp_timer_expired(void *data);
 
 #define MAX_SMS_RETRY 2
@@ -569,3 +574,5 @@ int gsm411_smc_recv(struct gsm411_smc_inst *inst, int msg_type,
 
 	return rc;
 }
+
+/*! @} */
diff --git a/src/gsm/gsm0411_smr.c b/src/gsm/gsm0411_smr.c
index eb8aec0d..d120f2df 100644
--- a/src/gsm/gsm0411_smr.c
+++ b/src/gsm/gsm0411_smr.c
@@ -62,6 +62,10 @@
 
 #define SMR_LOG_STR "SMR(%" PRIu64 ") "
 
+/*! \addtogroup sms
+ *  @{
+ */
+
 static void rp_timer_expired(void *data);
 
 /* init a new instance */
@@ -484,3 +488,5 @@ int gsm411_smr_recv(struct gsm411_smr_inst *inst, int msg_type,
 
 	return rc;
 }
+
+/*! @} */
diff --git a/src/gsm/gsm0411_utils.c b/src/gsm/gsm0411_utils.c
index b84c9f25..543775cc 100644
--- a/src/gsm/gsm0411_utils.c
+++ b/src/gsm/gsm0411_utils.c
@@ -38,16 +38,24 @@
 #include <osmocom/gsm/protocol/gsm_03_40.h>
 #include <osmocom/gsm/protocol/gsm_04_11.h>
 
+/*! \addtogroup sms
+ *  @{
+ */
+
 #define GSM411_ALLOC_SIZE	1024
 #define GSM411_ALLOC_HEADROOM	128
 
+/*! \brief Allocate a message buffer for use as TS 04.11 message
+ *  \returns allocated message buffer */
 struct msgb *gsm411_msgb_alloc(void)
 {
 	return msgb_alloc_headroom(GSM411_ALLOC_SIZE, GSM411_ALLOC_HEADROOM,
 				   "GSM 04.11");
 }
 
-/* Turn int into semi-octet representation: 98 => 0x89 */
+/*! \brief Turn int into semi-octet representation: 98 => 0x89
+ *  \param[in] integer value representing decimal number 0..99
+ *  \returns BSC encoded as nibbles, swapped */
 uint8_t gsm411_bcdify(uint8_t value)
 {
 	uint8_t ret;
@@ -58,7 +66,9 @@ uint8_t gsm411_bcdify(uint8_t value)
 	return ret;
 }
 
-/* Turn semi-octet representation into int: 0x89 => 98 */
+/*! \brief Turn semi-octet representation into int: 0x89 => 98
+ *  \param[in] value byte containing two BCD nibbles in revere order
+ *  \returns integer representing decoded, re-ordered nibbles */
 uint8_t gsm411_unbcdify(uint8_t value)
 {
 	uint8_t ret;
@@ -73,7 +83,9 @@ uint8_t gsm411_unbcdify(uint8_t value)
 	return ret;
 }
 
-/* Generate 03.40 TP-SCTS */
+/*! \brief Generate 03.40 TP-SCTS
+ *  \param[out] scts Caller-provided buffer to store SCTS (7 octets)
+ *  \param[in] time to encode */
 void gsm340_gen_scts(uint8_t *scts, time_t time)
 {
 	struct tm *tm = gmtime(&time);
@@ -92,7 +104,9 @@ void gsm340_gen_scts(uint8_t *scts, time_t time)
 #endif
 }
 
-/* Decode 03.40 TP-SCTS (into utc/gmt timestamp) */
+/*! \brief Decode 03.40 TP-SCTS (into utc/gmt timestamp)
+ *  \param[in] scts SMS Center Time Stamp
+ *  \return time in UTC time_t format */
 time_t gsm340_scts(uint8_t *scts)
 {
 	struct tm tm;
@@ -190,7 +204,10 @@ static unsigned long gsm340_vp_relative_semioctet(uint8_t *sms_vp)
 	return minutes;
 }
 
-/* decode validity period. return minutes */
+/*! \brief decode validity period. return minutes
+ *  \param[in] sms_vpf Validity Period Format in 03.40 encoding
+ *  \param[in] sms_vp Validity Period Information Element
+ *  \returns validity period in minutes */
 unsigned long gsm340_validity_period(uint8_t sms_vpf, uint8_t *sms_vp)
 {
 	uint8_t fi; /* functionality indicator */
@@ -228,7 +245,9 @@ unsigned long gsm340_validity_period(uint8_t sms_vpf, uint8_t *sms_vp)
 	}
 }
 
-/* determine coding alphabet dependent on GSM 03.38 Section 4 DCS */
+/*! \brief determine coding alphabet dependent on GSM 03.38 Section 4 DCS
+ *  \param[in] dcs Data Coding Scheme in 03.38 encoding
+ *  \returns libosmogsm internal enum \ref sms_alphabet */
 enum sms_alphabet gsm338_get_sms_alphabet(uint8_t dcs)
 {
 	uint8_t cgbits = dcs >> 4;
@@ -266,7 +285,13 @@ enum sms_alphabet gsm338_get_sms_alphabet(uint8_t dcs)
 	return alpha;
 }
 
-/* generate a TPDU address field compliant with 03.40 sec. 9.1.2.5 */
+/*! \brief generate a TPDU address field compliant with 03.40 sec. 9.1.2.5 
+ *  \param[out] oa caller-provided output buffer
+ *  \param[in] oa_len caller-specified length of \a oa in bytes
+ *  \param[in] type GSM340_TYPE_*
+ *  \param[in] plan Numbering Plan
+ *  \param[in] number string containing number
+ *  \reurns number of bytes of \a oa that have been used */
 int gsm340_gen_oa(uint8_t *oa, unsigned int oa_len, uint8_t type,
 	uint8_t plan, const char *number)
 {
@@ -296,7 +321,11 @@ int gsm340_gen_oa(uint8_t *oa, unsigned int oa_len, uint8_t type,
 	return len_in_bytes;
 }
 
-/* Prefix msg with a RP header */
+/*! \brief Prefix \ref msgb with a RP header
+ *  \param msg Message Buffer containing message
+ *  \param[in] rp_msg_type RP Message Type
+ *  \param[in] rp_msg_ref RP Message Reference
+ *  \returns 0 */
 int gsm411_push_rp_header(struct msgb *msg, uint8_t rp_msg_type,
 	uint8_t rp_msg_ref)
 {
@@ -312,7 +341,12 @@ int gsm411_push_rp_header(struct msgb *msg, uint8_t rp_msg_type,
 	return 0;
 }
 
-/* Prefix msg with a 04.08/04.11 CP header */
+/*! \brief Prefix \ref msgb with a 04.08/04.11 CP header
+ *  \param msg Message Buffer containing message
+ *  \param[in] proto Protocol
+ *  \param[in] trans Transaction
+ *  \param[in] msg_type Message Type
+ *  \retrns 0 */
 int gsm411_push_cp_header(struct msgb *msg, uint8_t proto, uint8_t trans,
 			     uint8_t msg_type)
 {
@@ -320,3 +354,5 @@ int gsm411_push_cp_header(struct msgb *msg, uint8_t proto, uint8_t trans,
 	gsm0480_l3hdr_push(msg, proto | (trans << 4), msg_type);
 	return 0;
 }
+
+/*! @} */
diff --git a/src/gsm/gsm0808.c b/src/gsm/gsm0808.c
index 04c2f018..c96dc779 100644
--- a/src/gsm/gsm0808.c
+++ b/src/gsm/gsm0808.c
@@ -24,9 +24,22 @@
 #include <osmocom/gsm/protocol/gsm_08_08.h>
 #include <osmocom/gsm/gsm48.h>
 
+/*! \addtogroup gsm0808
+ *  @{
+ *  \brief Helper functions regarding the TS 08.08 / 48.008 A interface
+ */
+
 #define BSSMAP_MSG_SIZE 512
 #define BSSMAP_MSG_HEADROOM 128
 
+/*! \brief Create "Complete L3 Info" for AoIP
+ *  \param[in] msg_l3 msgb containing Layer 3 Message
+ *  \param[in] nc Mobile Network Code
+ *  \param[in] cc Mobile Country Code
+ *  \param[in] lac Location Area Code
+ *  \param[in] _ci Cell Identity
+ *  \param[in] scl Speech Codec List
+ *  \returns callee-allocated msgb with Complete L3 Info message */
 struct msgb *gsm0808_create_layer3_aoip(const struct msgb *msg_l3, uint16_t nc,
 					uint16_t cc, int lac, uint16_t _ci,
 					const struct gsm0808_speech_codec_list
@@ -68,12 +81,21 @@ struct msgb *gsm0808_create_layer3_aoip(const struct msgb *msg_l3, uint16_t nc,
 	return msg;
 }
 
+/*! \brief Create "Complete L3 Info" for A
+ *  \param[in] msg_l3 msgb containing Layer 3 Message
+ *  \param[in] nc Mobile Network Code
+ *  \param[in] cc Mobile Country Code
+ *  \param[in] lac Location Area Code
+ *  \param[in] _ci Cell Identity
+ *  \returns callee-allocated msgb with Complete L3 Info message */
 struct msgb *gsm0808_create_layer3(struct msgb *msg_l3, uint16_t nc,
 				   uint16_t cc, int lac, uint16_t _ci)
 {
 	return gsm0808_create_layer3_aoip(msg_l3, nc, cc, lac, _ci, NULL);
 }
 
+/*! \brief Create BSSMAP RESET message
+ *  \returns callee-allocated msgb with BSSMAP Reset message */
 struct msgb *gsm0808_create_reset(void)
 {
 	uint8_t cause = GSM0808_CAUSE_EQUIPMENT_FAILURE;
@@ -89,6 +111,8 @@ struct msgb *gsm0808_create_reset(void)
 	return msg;
 }
 
+/*! \brief Create BSSMAP RESET ACK message
+ *  \returns callee-allocated msgb with BSSMAP Reset ACK message */
 struct msgb *gsm0808_create_reset_ack(void)
 {
 	struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM,
@@ -102,6 +126,8 @@ struct msgb *gsm0808_create_reset_ack(void)
 	return msg;
 }
 
+/*! \brief Create BSSMAP Clear Complete message
+ *  \returns callee-allocated msgb with BSSMAP Clear Complete message */
 struct msgb *gsm0808_create_clear_complete(void)
 {
 	struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM,
@@ -116,6 +142,9 @@ struct msgb *gsm0808_create_clear_complete(void)
 	return msg;
 }
 
+/*! \brief Create BSSMAP Clear Command message
+ *  \param[in] reason TS 08.08 cause value
+ *  \returns callee-allocated msgb with BSSMAP Clear Command message */
 struct msgb *gsm0808_create_clear_command(uint8_t reason)
 {
 	struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM,
@@ -130,6 +159,10 @@ struct msgb *gsm0808_create_clear_command(uint8_t reason)
 	return msg;
 }
 
+/*! \brief Create BSSMAP Cipher Mode Command message
+ *  \param[in] ei Mandatory Encryption Information
+ *  \param[in] cipher_response_mode optional 1-byte Cipher Response Mode
+ *  \returns callee-allocated msgb with BSSMAP Cipher Mode Command message */
 struct msgb *gsm0808_create_cipher(const struct gsm0808_encrypt_info *ei,
 				   const uint8_t *cipher_response_mode)
 {
@@ -163,6 +196,10 @@ struct msgb *gsm0808_create_cipher(const struct gsm0808_encrypt_info *ei,
 	return msg;
 }
 
+/*! \brief Create BSSMAP Cipher Mode Complete message
+ *  \param[in] layer3 L3 Message to be included
+ *  \param[in] alg_id Chosen Encrpytion Algorithm
+ *  \returns callee-allocated msgb with BSSMAP Cipher Mode Complete message */
 struct msgb *gsm0808_create_cipher_complete(struct msgb *layer3, uint8_t alg_id)
 {
 	struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM,
@@ -188,6 +225,9 @@ struct msgb *gsm0808_create_cipher_complete(struct msgb *layer3, uint8_t alg_id)
 	return msg;
 }
 
+/*! \brief Create BSSMAP Cipher Mode Reject message
+ *  \param[in] reason TS 08.08 cause value
+ *  \returns callee-allocated msgb with BSSMAP Cipher Mode Reject message */
 struct msgb *gsm0808_create_cipher_reject(uint8_t cause)
 {
 	struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM,
@@ -202,6 +242,12 @@ struct msgb *gsm0808_create_cipher_reject(uint8_t cause)
 	return msg;
 }
 
+/*! \brief Create BSSMAP Classmark Update message
+ *  \param[in] cm2 Classmark 2
+ *  \param[in] cm2_len length (in octets) of \a cm2
+ *  \param[in] cm3 Classmark 3
+ *  \param[in] cm3_len length (in octets) of \a cm3
+ *  \returns callee-allocated msgb with BSSMAP Classmark Update message */
 struct msgb *gsm0808_create_classmark_update(const uint8_t *cm2, uint8_t cm2_len,
 					     const uint8_t *cm3, uint8_t cm3_len)
 {
@@ -221,6 +267,9 @@ struct msgb *gsm0808_create_classmark_update(const uint8_t *cm2, uint8_t cm2_len
 	return msg;
 }
 
+/*! \brief Create BSSMAP SAPI N Reject message
+ *  \param[in] link_id Link Identifier
+ *  \returns callee-allocated msgb with BSSMAP SAPI N Reject message */
 struct msgb *gsm0808_create_sapi_reject(uint8_t link_id)
 {
 	struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM,
@@ -237,6 +286,13 @@ struct msgb *gsm0808_create_sapi_reject(uint8_t link_id)
 	return msg;
 }
 
+/*! \brief Create BSSMAP Assignment Request message
+ *  \param[in] ct Channel Type
+ *  \param[in] cic Circuit Identity Code (Classic A only)
+ *  \param[in] ss Socket Address of MSC-side RTP socket (AoIP only)
+ *  \param[in] scl Speech Codec List (AoIP only)
+ *  \param[in] ci Call Identifier (Optional, LCLS)
+ *  \returns callee-allocated msgb with BSSMAP Assignment Request message */
 struct msgb *gsm0808_create_ass(const struct gsm0808_channel_type *ct,
 				const uint16_t *cic,
 				const struct sockaddr_storage *ss,
@@ -293,6 +349,15 @@ struct msgb *gsm0808_create_ass(const struct gsm0808_channel_type *ct,
 	return msg;
 }
 
+/*! \brief Create BSSMAP Assignment Completed message
+ *  \param[in] rr_cause GSM 04.08 RR Cause value
+ *  \param[in] chosen_channel Chosen Channel
+ *  \param[in] encr_alg_id Encryption Algorithm ID
+ *  \param[in] speech_mode Speech Mode
+ *  \param[in] ss Socket Address of BSS-side RTP socket
+ *  \param[in] sc Speech Codec (current)
+ *  \param[in] scl Speech Codec List (permitted)
+ *  \returns callee-allocated msgb with BSSMAP Assignment Complete message */
 struct msgb *gsm0808_create_ass_compl(uint8_t rr_cause, uint8_t chosen_channel,
 				      uint8_t encr_alg_id, uint8_t speech_mode,
 				      const struct sockaddr_storage *ss,
@@ -342,6 +407,12 @@ struct msgb *gsm0808_create_ass_compl(uint8_t rr_cause, uint8_t chosen_channel,
 	return msg;
 }
 
+/*! \brief Create BSSMAP Assignment Completed message
+ *  \param[in] rr_cause GSM 04.08 RR Cause value
+ *  \param[in] chosen_channel Chosen Channel
+ *  \param[in] encr_alg_id Encryption Algorithm ID
+ *  \param[in] speech_mode Speech Mode
+ *  \returns callee-allocated msgb with BSSMAP Assignment Complete message */
 struct msgb *gsm0808_create_assignment_completed(uint8_t rr_cause,
 						 uint8_t chosen_channel,
 						 uint8_t encr_alg_id,
@@ -351,6 +422,11 @@ struct msgb *gsm0808_create_assignment_completed(uint8_t rr_cause,
 					speech_mode, NULL, NULL, NULL);
 }
 
+/*! \brief Create BSSMAP Assignment Failure message
+ *  \param[in] cause BSSMAP Cause value
+ *  \param[in] rr_cause GSM 04.08 RR Cause value
+ *  \param[in] scl Optional Speech Cdec List (AoIP)
+ *  \returns callee-allocated msgb with BSSMAP Assignment Failure message */
 struct msgb *gsm0808_create_ass_fail(uint8_t cause, const uint8_t *rr_cause,
 				     const struct gsm0808_speech_codec_list
 				     *scl)
@@ -380,12 +456,19 @@ struct msgb *gsm0808_create_ass_fail(uint8_t cause, const uint8_t *rr_cause,
 	return msg;
 }
 
+/*! \brief Create BSSMAP Assignment Failure message
+ *  \param[in] cause BSSMAP Cause value
+ *  \param[in] rr_cause GSM 04.08 RR Cause value
+ *  \returns callee-allocated msgb with BSSMAP Assignment Failure message */
 struct msgb *gsm0808_create_assignment_failure(uint8_t cause,
 					       uint8_t *rr_cause)
 {
 	return gsm0808_create_ass_fail(cause, rr_cause, NULL);
 }
 
+/*! \brief Create BSSMAP Clear Request message
+ *  \param[in] cause BSSMAP Cause value
+ *  \returns callee-allocated msgb with BSSMAP Clear Request message */
 struct msgb *gsm0808_create_clear_rqst(uint8_t cause)
 {
 	struct msgb *msg;
@@ -402,6 +485,12 @@ struct msgb *gsm0808_create_clear_rqst(uint8_t cause)
 	return msg;
 }
 
+/*! \brief Create BSSMAP PAGING message
+ *  \param[in] imsi Mandatory paged IMSI in string representation
+ *  \param[in] tmsi Optional paged TMSI
+ *  \param[in] cil Cell Identity List (where to page)
+ *  \param[in] chan_needed Channel Type needed
+ *  \returns callee-allocated msgb with BSSMAP PAGING message */
 struct msgb *gsm0808_create_paging(const char *imsi, const uint32_t *tmsi,
 				   const struct gsm0808_cell_id_list *cil,
 				   const uint8_t *chan_needed)
@@ -454,6 +543,9 @@ struct msgb *gsm0808_create_paging(const char *imsi, const uint32_t *tmsi,
 	return msg;
 }
 
+/*! \brief Prepend a DTAP header to given Message Buffer
+ *  \param[in] msgb Message Buffer
+ *  \param[in] link_id Link Identifier */
 void gsm0808_prepend_dtap_header(struct msgb *msg, uint8_t link_id)
 {
 	uint8_t *hh = msgb_push(msg, 3);
@@ -462,6 +554,10 @@ void gsm0808_prepend_dtap_header(struct msgb *msg, uint8_t link_id)
 	hh[2] = msg->len - 3;
 }
 
+/*! \brief Create BSSMAP DTAP message
+ *  \param[in] msg_l3 Messge Buffer containing Layer3 message
+ *  \param[in] link_id Link Identifier
+ *  \returns callee-allocated msgb with BSSMAP DTAP message */
 struct msgb *gsm0808_create_dtap(struct msgb *msg_l3, uint8_t link_id)
 {
 	struct dtap_header *header;
@@ -722,6 +818,7 @@ static const struct value_string gsm0808_msgt_names[] = {
 	{ 0, NULL }
 };
 
+/*! \brief Return string name of BSSMAP Message Type */
 const char *gsm0808_bssmap_name(uint8_t msg_type)
 {
 	return get_value_string(gsm0808_msgt_names, msg_type);
@@ -733,7 +830,10 @@ static const struct value_string gsm0808_bssap_names[] = {
 	{ 0, NULL }
 };
 
+/*! \brief Return string name of BSSAP Message Type */
 const char *gsm0808_bssap_name(uint8_t msg_type)
 {
 	return get_value_string(gsm0808_bssap_names, msg_type);
 }
+
+/*! @} */
diff --git a/src/gsm/gsm0808_utils.c b/src/gsm/gsm0808_utils.c
index ff97b2d2..bdd02e56 100644
--- a/src/gsm/gsm0808_utils.c
+++ b/src/gsm/gsm0808_utils.c
@@ -39,7 +39,15 @@
 
 #include <sys/socket.h>
 #include <netinet/in.h>
-/* Encode AoIP transport address element */