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, 61 insertions, 12 deletions

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 */
+
+/*! \addtogroup gsm0808
+ *  @{
+ */
+
+/*! \brief Encode TS 08.08 AoIP transport address IE
+ *  \param[out] msg Message Buffer to which to append IE
+ *  \param[in] ss Socket Address to be used in IE
+ *  \returns number of bytes added to \a msg */
 uint8_t gsm0808_enc_aoip_trasp_addr(struct msgb *msg,
 				    const struct sockaddr_storage *ss)
 {
@@ -80,7 +88,11 @@ uint8_t gsm0808_enc_aoip_trasp_addr(struct msgb *msg,
 	return *tlv_len + 2;
 }
 
-/* Decode AoIP transport address element */
+/*! \brief Decode TS 08.08 AoIP transport address IE
+ *  \param[out] ss Caller-provided memory where decoded socket addr is stored
+ *  \param[in] elem pointer to IE value
+ *  \param[in] len length of \a elem in bytes
+ *  \returns number of bytes parsed */
 int gsm0808_dec_aoip_trasp_addr(struct sockaddr_storage *ss,
 				const uint8_t *elem, uint8_t len)
 {
@@ -168,7 +180,10 @@ static uint8_t enc_speech_codec(struct msgb *msg,
 	return (uint8_t) (msg->tail - old_tail);
 }
 
-/* Encode Speech Codec element */
+/*! \brief Encode TS 08.08 Speech Codec IE
+ *  \param[out] msg Message Buffer to which IE will be appended
+ *  \param[in] sc Speech Codec to be encoded into IE
+ *  \returns number of bytes appended to \a msg */
 uint8_t gsm0808_enc_speech_codec(struct msgb *msg,
 				 const struct gsm0808_speech_codec *sc)
 {
@@ -188,7 +203,11 @@ uint8_t gsm0808_enc_speech_codec(struct msgb *msg,
 	return *tlv_len + 2;
 }
 
-/* Decode Speech Codec element */
+/*! \brief Decode TS 08.08 Speech Codec IE
+ *  \param[out] sc Caller-allocated memory for Speech Codec
+ *  \param[in] elem IE value to be decoded
+ *  \param[in] len Length of \a elem in bytes
+ *  \returns number of bytes parsed; negative on error */
 int gsm0808_dec_speech_codec(struct gsm0808_speech_codec *sc,
 			     const uint8_t *elem, uint8_t len)
 {
@@ -244,7 +263,10 @@ int gsm0808_dec_speech_codec(struct gsm0808_speech_codec *sc,
 	return (int)(elem - old_elem);
 }
 
-/* Encode Speech Codec list */
+/*! \brief Encode TS 08.08 Speech Codec list
+ *  \param[out] msg  Message Buffer to which IE is to be appended
+ *  \param[in] scl Speech Codec List to be encoded into IE
+ *  \returns number of bytes added to \a msg */
 uint8_t gsm0808_enc_speech_codec_list(struct msgb *msg,
 				      const struct gsm0808_speech_codec_list *scl)
 {
@@ -275,7 +297,11 @@ uint8_t gsm0808_enc_speech_codec_list(struct msgb *msg,
 	return *tlv_len + 2;
 }
 
-/* Decode Speech Codec list */
+/*! \brief Decode TS 08.08 Speech Codec list IE
+ *  \param[out] scl Caller-provided memory to store codec list
+ *  \param[in] elem IE value to be decoded
+ *  \param[in] len Length of \a elem in bytes
+ *  \returns number of bytes parsed; negative on error */
 int gsm0808_dec_speech_codec_list(struct gsm0808_speech_codec_list *scl,
 				  const uint8_t *elem, uint8_t len)
 {
@@ -315,7 +341,10 @@ int gsm0808_dec_speech_codec_list(struct gsm0808_speech_codec_list *scl,
 	return (int)(elem - old_elem);
 }
 
-/* Encode Channel Type element */
+/*! \brief Encode TS 08.08 Channel Type IE
+ *  \param[out] msg Message Buffer to which IE is to be appended
+ *  \param[in] ct Channel Type to be encoded
+ *  \returns number of bytes added to \a msg */
 uint8_t gsm0808_enc_channel_type(struct msgb *msg,
 				 const struct gsm0808_channel_type *ct)
 {
@@ -353,7 +382,11 @@ uint8_t gsm0808_enc_channel_type(struct msgb *msg,
 	return *tlv_len + 2;
 }
 
-/* Decode Channel Type element */
+/*! \brief Decode TS 08.08 Channel Type IE
+ *  \param[out] ct Caller-provided memory to store channel type
+ *  \param[in] elem IE Value to be decoded
+ *  \param[in] len Length of \a elem in bytes
+ *  \returns number of bytes parsed; negative on error */
 int gsm0808_dec_channel_type(struct gsm0808_channel_type *ct,
 			     const uint8_t *elem, uint8_t len)
 {
@@ -386,7 +419,10 @@ int gsm0808_dec_channel_type(struct gsm0808_channel_type *ct,
 	return (int)(elem - old_elem);
 }
 
-/* Encode Encryption Information element */
+/*! \brief Encode TS 08.08 Encryption Information IE
+ *  \param[out] msg Message Buffer to which IE is to be appended
+ *  \param[in] ei Encryption Information to be encoded
+ *  \returns number of bytes appended to \a msg */
 uint8_t gsm0808_enc_encrypt_info(struct msgb *msg,
 				 const struct gsm0808_encrypt_info *ei)
 {
@@ -421,7 +457,11 @@ uint8_t gsm0808_enc_encrypt_info(struct msgb *msg,
 	return *tlv_len + 2;
 }
 
-/* Decode Encryption Information element */
+/*! \brief Decode TS 08.08 Encryption Information IE
+ *  \param[out] ei Caller-provided memory to store encryption information
+ *  \param[in] elem IE value to be decoded
+ *  \param[in] len Length of \a elem in bytes
+ *  \returns number of bytes parsed; negative on error */
 int gsm0808_dec_encrypt_info(struct gsm0808_encrypt_info *ei,
 			     const uint8_t *elem, uint8_t len)
 {
@@ -456,7 +496,10 @@ int gsm0808_dec_encrypt_info(struct gsm0808_encrypt_info *ei,
 	return (int)(elem - old_elem);
 }
 
-/* Encode Cell Identifier List element */
+/*! \brief Encode TS 08.08 Cell Identifier List IE
+ *  \param[out] msg Message Buffer to which IE is to be appended
+ *  \param[in] cil Cell ID List to be encoded
+ *  \returns number of bytes appended to \a msg */
 uint8_t gsm0808_enc_cell_id_list(struct msgb *msg,
 				 const struct gsm0808_cell_id_list *cil)
 {
@@ -492,7 +535,11 @@ uint8_t gsm0808_enc_cell_id_list(struct msgb *msg,
 	return *tlv_len + 2;
 }
 
-/* Decode Cell Identifier List element */
+/*! \brief Decode Cell Identifier List IE
+ *  \param[out] cil Caller-provided memory to store Cell ID list
+ *  \param[in] elem IE value to be decoded
+ *  \param[in] len Length of \a elem in bytes
+ *  \returns number of bytes parsed; negative on error */
 int gsm0808_dec_cell_id_list(struct gsm0808_cell_id_list *cil,
 			     const uint8_t *elem, uint8_t len)
 {
@@ -533,3 +580,5 @@ int gsm0808_dec_cell_id_list(struct gsm0808_cell_id_list *cil,
 	cil->id_list_len = item_count;
 	return (int)(elem - old_elem);
 }
+
+/*! @} */