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
diff --git a/src/gsm/gsm0808_utils.c b/src/gsm/gsm0808_utils.c
index ff97b2d..bdd02e5 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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
cil->id_list_len = item_count;
return (int)(elem - old_elem);
}
+
+/*! @} */