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

1 files changed, 87 insertions, 35 deletions

diff --git a/src/gsm/gsm48_ie.c b/src/gsm/gsm48_ie.c
index 2cc0645d..20d0075d 100644
--- a/src/gsm/gsm48_ie.c
+++ b/src/gsm/gsm48_ie.c
@@ -34,12 +34,20 @@
 #include <osmocom/gsm/protocol/gsm_04_08.h>
 #include <osmocom/gsm/gsm48_ie.h>
 
+/*! \addtogroup gsm0408
+ *  @{
+ */
+
 static const char bcd_num_digits[] = {
 	'0', '1', '2', '3', '4', '5', '6', '7',
 	'8', '9', '*', '#', 'a', 'b', 'c', '\0'
 };
 
-/* decode a 'called/calling/connect party BCD number' as in 10.5.4.7 */
+/*! \brief decode a 'called/calling/connect party BCD number' as in 10.5.4.7
+ *  \param[out] Caller-provided output buffer
+ *  \param[in] bcd_lv Length-Value portion of to-be-decoded IE
+ *  \param[in] h_len Length of an optional heder between L and V portion
+ *  \returns - in case of success; negative on error */
 int gsm48_decode_bcd_number(char *output, int output_len,
 			    const uint8_t *bcd_lv, int h_len)
 {
@@ -65,7 +73,7 @@ int gsm48_decode_bcd_number(char *output, int output_len,
 	return 0;
 }
 
-/* convert a single ASCII character to call-control BCD */
+/*! \brief convert a single ASCII character to call-control BCD */
 static int asc_to_bcd(const char asc)
 {
 	int i;
@@ -77,7 +85,12 @@ static int asc_to_bcd(const char asc)
 	return -EINVAL;
 }
 
-/* convert a ASCII phone number to 'called/calling/connect party BCD number' */
+/*! \brief convert a ASCII phone number to 'called/calling/connect party BCD number'
+ *  \param[out] bcd_lv Caller-provided output buffer
+ *  \param[in] max_len Maximum Length of \a bcd_lv
+ *  \param[in] h_len Length of an optional heder between L and V portion
+ *  \param[in] input phone number as 0-terminated ASCII
+ *  \returns number of bytes used in \a bcd_lv */
 int gsm48_encode_bcd_number(uint8_t *bcd_lv, uint8_t max_len,
 		      int h_len, const char *input)
 {
@@ -110,7 +123,10 @@ int gsm48_encode_bcd_number(uint8_t *bcd_lv, uint8_t max_len,
 	return (bcd_cur - bcd_lv);
 }
 
-/* TS 04.08 10.5.4.5: decode 'bearer capability' */
+/*! \brief Decode TS 04.08 Bearer Capability IE (10.5.4.5)
+ *  \param[out] Caller-provided memory for decoded output
+ *  \[aram[in] LV portion of TS 04.08 Bearer Capability
+ *  \returns 0 on success; negative on error */
 int gsm48_decode_bearer_cap(struct gsm_mncc_bearer_cap *bcap,
 			     const uint8_t *lv)
 {
@@ -219,7 +235,11 @@ int gsm48_decode_bearer_cap(struct gsm_mncc_bearer_cap *bcap,
 	return 0;
 }
 
-/* TS 04.08 10.5.4.5: encode 'bearer capability' */
+/*! \brief Encode TS 04.08 Bearer Capability IE (10.5.4.5)
+ *  \param[out] msg Message Buffer to which IE is to be appended
+ *  \param[in] lv_only Write only LV portion (1) or TLV (0)
+ *  \param[in] bcap Decoded Bearer Capability to be encoded
+ *  \returns 0 on success; negative on error */
 int gsm48_encode_bearer_cap(struct msgb *msg, int lv_only,
 			     const struct gsm_mncc_bearer_cap *bcap)
 {
@@ -274,7 +294,10 @@ int gsm48_encode_bearer_cap(struct msgb *msg, int lv_only,
 	return 0;
 }
 
-/* TS 04.08 10.5.4.5a: decode 'call control cap' */
+/*! \brief Decode TS 04.08 Call Control Capabilities IE (10.5.4.5a)
+ *  \param[out] Caller-provided memory for decoded CC capabilities
+ *  \param[in] lv Length-Value of IE
+ *  \retursns 0 on success; negative on error */
 int gsm48_decode_cccap(struct gsm_mncc_cccap *ccap, const uint8_t *lv)
 {
 	uint8_t in_len = lv[0];
@@ -289,7 +312,10 @@ int gsm48_decode_cccap(struct gsm_mncc_cccap *ccap, const uint8_t *lv)
 	return 0;
 }
 
-/* TS 04.08 10.5.4.5a: encode 'call control cap' */
+/*! \brief Encodoe TS 04.08 Call Control Capabilities (10.5.4.5a)
+ *  \param[out] msg Message Buffer to which to append IE (as TLV)
+ *  \param[in] ccap Decoded CC Capabilities to be encoded
+ *  \returns 0 on success; negative on error */
 int gsm48_encode_cccap(struct msgb *msg,
 			const struct gsm_mncc_cccap *ccap)
 {
@@ -307,7 +333,10 @@ int gsm48_encode_cccap(struct msgb *msg,
 	return 0;
 }
 
-/* TS 04.08 10.5.4.7: decode 'called party BCD number' */
+/*! \brief Decode TS 04.08 Called Party BCD Number IE (10.5.4.7)
+ *  \param[out] called Caller-provided memory for decoded number
+ *  \param[in] lv Length-Value portion of IE
+ *  \returns 0 on success; negative on error */
 int gsm48_decode_called(struct gsm_mncc_number *called,
 			 const uint8_t *lv)
 {
@@ -326,7 +355,10 @@ int gsm48_decode_called(struct gsm_mncc_number *called,
 	return 0;
 }
 
-/* TS 04.08 10.5.4.7: encode 'called party BCD number' */
+/*! \brief Encode TS 04.08 Called Party IE (10.5.4.7)
+ *  \param[out] msg Mesage Buffer to which to append IE (as TLV)
+ *  \param[in] called MNCC Number to encode/append
+ *  \returns 0 on success; negative on error */
 int gsm48_encode_called(struct msgb *msg,
 			 const struct gsm_mncc_number *called)
 {
@@ -348,7 +380,10 @@ int gsm48_encode_called(struct msgb *msg,
 	return 0;
 }
 
-/* decode callerid of various IEs */
+/*! \brief Decode TS 04.08 Caller ID
+ *  \param[out] called Caller-provided memory for decoded number
+ *  \param[in] lv Length-Value portion of IE
+ *  \returns 0 on success; negative on error */
 int gsm48_decode_callerid(struct gsm_mncc_number *callerid,
 			 const uint8_t *lv)
 {
@@ -375,7 +410,12 @@ int gsm48_decode_callerid(struct gsm_mncc_number *callerid,
 	return 0;
 }
 
-/* encode callerid of various IEs */
+/*! \brief Encode TS 04.08 Caller ID IE
+ *  \param[out] msg Mesage Buffer to which to append IE (as TLV)
+ *  \param[in] ie IE Identifier (tag)
+ *  \param[in] max_len maximum generated output in bytes
+ *  \param[in] callerid MNCC Number to encode/append
+ *  \returns 0 on success; negative on error */
 int gsm48_encode_callerid(struct msgb *msg, int ie, int max_len,
 			   const struct gsm_mncc_number *callerid)
 {
@@ -406,7 +446,10 @@ int gsm48_encode_callerid(struct msgb *msg, int ie, int max_len,
 	return 0;
 }
 
-/* TS 04.08 10.5.4.11: decode 'cause' */
+/*! \brief Decode TS 04.08 Cause IE (10.5.4.11)
+ *  \param[out] cause Caller-provided memory for output
+ *  \param[in] lv LV portion of Cause IE
+ *  \returns 0 on success; negative on error */
 int gsm48_decode_cause(struct gsm_mncc_cause *cause,
 			const uint8_t *lv)
 {
@@ -449,7 +492,11 @@ int gsm48_decode_cause(struct gsm_mncc_cause *cause,
 	return 0;
 }
 
-/* TS 04.08 10.5.4.11: encode 'cause' */
+/*! \brief Encode TS 04.08 Cause IE (10.5.4.11)
+ *  \param[out] msg Message Buffer to which to append IE
+ *  \param[in] lv_only Encode as LV (1) or TLV (0)
+ *  \param[in] cause Cause value to be encoded
+ *  \returns 0 on success; negative on error */
 int gsm48_encode_cause(struct msgb *msg, int lv_only,
 			const struct gsm_mncc_cause *cause)
 {
@@ -489,49 +536,49 @@ int gsm48_encode_cause(struct msgb *msg, int lv_only,
 	return 0;
 }
 
-/* TS 04.08 10.5.4.9: decode 'calling number' */
+/*! \brief Decode TS 04.08 Calling Number IE (10.5.4.9) */
 int gsm48_decode_calling(struct gsm_mncc_number *calling,
 			 const uint8_t *lv)
 {
 	return gsm48_decode_callerid(calling, lv);
 }
 
-/* TS 04.08 10.5.4.9: encode 'calling number' */
+/*! \brief Encode TS 04.08 Calling Number IE (10.5.4.9) */
 int gsm48_encode_calling(struct msgb *msg, 
 			  const struct gsm_mncc_number *calling)
 {
 	return gsm48_encode_callerid(msg, GSM48_IE_CALLING_BCD, 14, calling);
 }
 
-/* TS 04.08 10.5.4.13: decode 'connected number' */
+/*! \brief Decode TS 04.08 Connected Number IE (10.5.4.13) */
 int gsm48_decode_connected(struct gsm_mncc_number *connected,
 			 const uint8_t *lv)
 {
 	return gsm48_decode_callerid(connected, lv);
 }
 
-/* TS 04.08 10.5.4.13: encode 'connected number' */
+/*! \brief Encode TS 04.08 Connected Number IE (10.5.4.13) */
 int gsm48_encode_connected(struct msgb *msg,
 			    const struct gsm_mncc_number *connected)
 {
 	return gsm48_encode_callerid(msg, GSM48_IE_CONN_BCD, 14, connected);
 }
 
-/* TS 04.08 10.5.4.21b: decode 'redirecting number' */
+/*! \brief Decode TS 04.08 Redirecting Number IE (10.5.4.21b) */
 int gsm48_decode_redirecting(struct gsm_mncc_number *redirecting,
 			 const uint8_t *lv)
 {
 	return gsm48_decode_callerid(redirecting, lv);
 }
 
-/* TS 04.08 10.5.4.21b: encode 'redirecting number' */
+/*! \brief Encode TS 04.08 Redirecting Number IE (10.5.4.21b) */
 int gsm48_encode_redirecting(struct msgb *msg,
 			      const struct gsm_mncc_number *redirecting)
 {
 	return gsm48_encode_callerid(msg, GSM48_IE_REDIR_BCD, 19, redirecting);
 }
 
-/* TS 04.08 10.5.4.15: decode 'facility' */
+/*! \brief Decode TS 04.08 Facility IE (10.5.4.15) */
 int gsm48_decode_facility(struct gsm_mncc_facility *facility,
 			   const uint8_t *lv)
 {
@@ -549,7 +596,7 @@ int gsm48_decode_facility(struct gsm_mncc_facility *facility,
 	return 0;
 }
 
-/* TS 04.08 10.5.4.15: encode 'facility' */
+/*! \brief Encode TS 04.08 Facility IE (10.5.4.15) */
 int gsm48_encode_facility(struct msgb *msg, int lv_only,
 			   const struct gsm_mncc_facility *facility)
 {
@@ -568,7 +615,7 @@ int gsm48_encode_facility(struct msgb *msg, int lv_only,
 	return 0;
 }
 
-/* TS 04.08 10.5.4.20: decode 'notify' */
+/*! \brief Decode TS 04.08 Notify IE (10.5.4.20) */
 int gsm48_decode_notify(int *notify, const uint8_t *v)
 {
 	*notify = v[0] & 0x7f;
@@ -576,7 +623,7 @@ int gsm48_decode_notify(int *notify, const uint8_t *v)
 	return 0;
 }
 
-/* TS 04.08 10.5.4.20: encode 'notify' */
+/*! \brief Encode TS 04.08 Notify IE (10.5.4.20) */
 int gsm48_encode_notify(struct msgb *msg, int notify)
 {
 	msgb_v_put(msg, notify | 0x80);
@@ -584,7 +631,7 @@ int gsm48_encode_notify(struct msgb *msg, int notify)
 	return 0;
 }
 
-/* TS 04.08 10.5.4.23: decode 'signal' */
+/*! \brief Decode TS 04.08 Signal IE (10.5.4.23) */
 int gsm48_decode_signal(int *signal, const uint8_t *v)
 {
 	*signal = v[0];
@@ -592,7 +639,7 @@ int gsm48_decode_signal(int *signal, const uint8_t *v)
 	return 0;
 }
 
-/* TS 04.08 10.5.4.23: encode 'signal' */
+/*! \brief Encode TS 04.08 Signal IE (10.5.4.23) */
 int gsm48_encode_signal(struct msgb *msg, int signal)
 {
 	msgb_tv_put(msg, GSM48_IE_SIGNAL, signal);
@@ -600,7 +647,7 @@ int gsm48_encode_signal(struct msgb *msg, int signal)
 	return 0;
 }
 
-/* TS 04.08 10.5.4.17: decode 'keypad' */
+/*! \brief Decode TS 04.08 Keypad IE (10.5.4.17) */
 int gsm48_decode_keypad(int *keypad, const uint8_t *lv)
 {
 	uint8_t in_len = lv[0];
@@ -613,7 +660,7 @@ int gsm48_decode_keypad(int *keypad, const uint8_t *lv)
 	return 0;
 }
 
-/* TS 04.08 10.5.4.17: encode 'keypad' */
+/*! \brief Encode TS 04.08 Keypad IE (10.5.4.17) */
 int gsm48_encode_keypad(struct msgb *msg, int keypad)
 {
 	msgb_tv_put(msg, GSM48_IE_KPD_FACILITY, keypad);
@@ -621,7 +668,7 @@ int gsm48_encode_keypad(struct msgb *msg, int keypad)
 	return 0;
 }
 
-/* TS 04.08 10.5.4.21: decode 'progress' */
+/*! \brief Decode TS 04.08 Progress IE (10.5.4.21) */
 int gsm48_decode_progress(struct gsm_mncc_progress *progress,
 			   const uint8_t *lv)
 {
@@ -637,7 +684,7 @@ int gsm48_decode_progress(struct gsm_mncc_progress *progress,
 	return 0;
 }
 
-/* TS 04.08 10.5.4.21: encode 'progress' */
+/*! \brief Encode TS 04.08 Progress IE (10.5.4.21) */
 int gsm48_encode_progress(struct msgb *msg, int lv_only,
 			   const struct gsm_mncc_progress *p)
 {
@@ -654,7 +701,7 @@ int gsm48_encode_progress(struct msgb *msg, int lv_only,
 	return 0;
 }
 
-/* TS 04.08 10.5.4.25: decode 'user-user' */
+/*! \brief Decode TS 04.08 User-User IE (10.5.4.25) */
 int gsm48_decode_useruser(struct gsm_mncc_useruser *uu,
 			   const uint8_t *lv)
 {
@@ -680,7 +727,7 @@ int gsm48_decode_useruser(struct gsm_mncc_useruser *uu,
 	return 0;
 }
 
-/* TS 04.08 10.5.4.25: encode 'useruser' */
+/*! \brief Encode TS 04.08 User-User IE (10.5.4.25) */
 int gsm48_encode_useruser(struct msgb *msg, int lv_only,
 			   const struct gsm_mncc_useruser *uu)
 {
@@ -700,7 +747,7 @@ int gsm48_encode_useruser(struct msgb *msg, int lv_only,
 	return 0;
 }
 
-/* TS 04.08 10.5.4.24: decode 'ss version' */
+/*! \brief Decode TS 04.08 SS Version IE (10.5.4.24) */
 int gsm48_decode_ssversion(struct gsm_mncc_ssversion *ssv,
 			    const uint8_t *lv)
 {
@@ -715,7 +762,7 @@ int gsm48_decode_ssversion(struct gsm_mncc_ssversion *ssv,
 	return 0;
 }
 
-/* TS 04.08 10.5.4.24: encode 'ss version' */
+/*! \brief Encode TS 04.08 SS Version IE (10.5.4.24) */
 int gsm48_encode_ssversion(struct msgb *msg,
 			   const struct gsm_mncc_ssversion *ssv)
 {
@@ -733,7 +780,7 @@ int gsm48_encode_ssversion(struct msgb *msg,
 
 /* decode 'more data' does not require a function, because it has no value */
 
-/* TS 04.08 10.5.4.19: encode 'more data' */
+/*! \brief Encode TS 04.08 More Data IE (10.5.4.19) */
 int gsm48_encode_more(struct msgb *msg)
 {
 	uint8_t *ie;
@@ -756,7 +803,11 @@ static int32_t smod(int32_t n, int32_t m)
 	return res;
 }
 
-/* decode "Cell Channel Description" (10.5.2.1b) and other frequency lists */
+/*! \brief Decode TS 04.08 Cell Channel Description IE (10.5.2.1b) and other frequency lists
+ *  \param[out] f Caller-provided output memory
+ *  \param[in] cd Cell Channel Description IE
+ *  \param[in] len Length of \a cd in bytes
+ *  \returns 0 on success; negative on error */
 int gsm48_decode_freq_list(struct gsm_sysinfo_freq *f, uint8_t *cd,
 			   uint8_t len, uint8_t mask, uint8_t frqt)
 {
@@ -1190,3 +1241,4 @@ int gsm48_decode_freq_list(struct gsm_sysinfo_freq *f, uint8_t *cd,
 
 	return 0;
 }
+/*! @} */