docs: various osmux API documentation updates

Let's make sure
* only exported / user-relevant #defines appear in the manual
* deprecated functions are marked in a way doxygen can mark them
* descriptive comments are using doxygen syntax

Change-Id: I5af0133322ddd5345a13380f1c007474c0bea117
---
M include/osmocom/netif/osmux.h
M src/osmux.c
M src/osmux_input.c
M src/osmux_output.c
4 files changed, 56 insertions(+), 40 deletions(-)

diff --git a/include/osmocom/netif/osmux.h b/include/osmocom/netif/osmux.h
index 609ca3b..8a8bf88 100644
--- a/include/osmocom/netif/osmux.h
+++ b/include/osmocom/netif/osmux.h
@@ -15,7 +15,8 @@
 
 #define OSMUX_DEFAULT_PORT 1984
 
-/* OSmux header:
+/*! \struct osmux_hdr
+ * OSmux header:
  *
  *	rtp_m (1 bit):		RTP M field (RFC3550, RFC4867)
  *	ft (2 bits):		0=signalling, 1=voice, 2=dummy
@@ -32,6 +33,7 @@
 #define OSMUX_FT_VOICE_AMR	1
 #define OSMUX_FT_DUMMY		2
 
+/*! Osmux protocol header */
 struct osmux_hdr {
 #if OSMO_IS_LITTLE_ENDIAN
 	uint8_t amr_q:1,
@@ -56,9 +58,9 @@
 	uint8_t data[0];
 } __attribute__((packed));
 
-/* one to handle all existing RTP flows */
+/*! one to handle all existing RTP flows */
 struct osmux_in_handle {
-	/* Initial Osmux seqnum for each circuit, set during osmux_xfrm_input_open_circuit() */
+	/*! Initial Osmux seqnum for each circuit, set during osmux_xfrm_input_open_circuit() */
 	uint8_t osmux_seq;
 	uint8_t batch_factor;
 	uint16_t batch_size;
@@ -79,7 +81,7 @@
 
 typedef struct msgb *(*rtp_msgb_alloc_cb_t)(void *rtp_msgb_alloc_priv_data,
 					    unsigned int msg_len);
-/* one per OSmux circuit_id, ie. one per RTP flow. */
+/*! one per OSmux circuit_id, ie. one per RTP flow. */
 struct osmux_out_handle {
 	uint16_t rtp_seq;
 	uint32_t rtp_timestamp;
@@ -94,6 +96,7 @@
 	void *rtp_msgb_alloc_cb_data; /* Opaque data pointer set by user and passed in rtp_msgb_alloc_cb() */
 };
 
+/*! return pointer to osmux payload (behind osmux_hdr) */
 static inline uint8_t *osmux_get_payload(struct osmux_hdr *osmuxh)
 {
 	return (uint8_t *)osmuxh + sizeof(struct osmux_hdr);
diff --git a/src/osmux.c b/src/osmux.c
index d3294de..999aedd 100644
--- a/src/osmux.c
+++ b/src/osmux.c
@@ -27,6 +27,14 @@
 
 #include <arpa/inet.h>
 
+#define SNPRINTF_BUFFER_SIZE(ret, remain, offset)	\
+	if (ret < 0)					\
+		ret = 0;				\
+	offset += ret;					\
+	if (ret > remain)				\
+		ret = remain;				\
+	remain -= ret;
+
 /*! \addtogroup osmux Osmocom Multiplex Protocol
  *  @{
  *
@@ -49,14 +57,6 @@
 	return osmo_amr_bytes(osmuxh->amr_ft) * (osmuxh->ctr+1);
 }
 
-#define SNPRINTF_BUFFER_SIZE(ret, remain, offset)	\
-	if (ret < 0)					\
-		ret = 0;				\
-	offset += ret;					\
-	if (ret > remain)				\
-		ret = remain;				\
-	remain -= ret;
-
 static int osmux_snprintf_header(char *buf, size_t size, struct osmux_hdr *osmuxh)
 {
 	unsigned int remain = size, offset = 0;
diff --git a/src/osmux_input.c b/src/osmux_input.c
index 120f95f..2184a08 100644
--- a/src/osmux_input.c
+++ b/src/osmux_input.c
@@ -28,23 +28,6 @@
 
 #include <arpa/inet.h>
 
-/*! \addtogroup osmux Osmocom Multiplex Protocol
- *  @{
- *
- *  This code implements a variety of utility functions related to the
- *  OSMUX user-plane multiplexing protocol, an efficient alternative to
- *  plain UDP/RTP streams for voice transport in back-haul of cellular
- *  networks.
- *
- *  For information about the OSMUX protocol design, please see the
- *  OSMUX reference manual at
- *  http://ftp.osmocom.org/docs/latest/osmux-reference.pdf
- */
-
-/*! \file osmux_input.c
- *  \brief Osmocom multiplex protocol helpers (input)
- */
-
 /* This allows you to debug osmux message transformations (spamming) */
 #if 0
 #define DEBUG_MSG		0
@@ -68,6 +51,22 @@
 	LOGMUXLK_(link, lvl, "[CID=%" PRIu8 ",batched=%u/%u] " fmt, \
 		  (circuit)->ccid, (circuit)->nmsgs, (link)->h->batch_factor, ## args)
 
+/*! \addtogroup osmux Osmocom Multiplex Protocol
+ *  @{
+ *
+ *  This code implements a variety of utility functions related to the
+ *  OSMUX user-plane multiplexing protocol, an efficient alternative to
+ *  plain UDP/RTP streams for voice transport in back-haul of cellular
+ *  networks.
+ *
+ *  For information about the OSMUX protocol design, please see the
+ *  OSMUX reference manual at
+ *  http://ftp.osmocom.org/docs/latest/osmux-reference.pdf
+ */
+
+/*! \file osmux_input.c
+ *  \brief Osmocom multiplex protocol helpers (input)
+ */
 
 static void *osmux_ctx;
 
@@ -698,6 +697,7 @@
 	return 0;
 }
 
+static unsigned int next_default_name_idx = 0;
 /*! \brief Allocate a new osmux in handle (osmux source, tx side)
  *  \param[in] ctx talloc context to use when allocating the returned struct
  *  \return Allocated osmux in handle
@@ -708,7 +708,6 @@
  * stack outgoing network Osmux messages.
  * Returned pointer can be freed with regular talloc_free, all pending messages
  * in queue and all internal data will be freed. */
-static unsigned int next_default_name_idx = 0;
 struct osmux_in_handle *osmux_xfrm_input_alloc(void *ctx)
 {
 	struct osmux_in_handle *h;
@@ -735,7 +734,7 @@
 	return h;
 }
 
-/* DEPRECATED: Use osmux_xfrm_input_alloc() instead */
+/*! \deprecated: Use osmux_xfrm_input_alloc() instead */
 void osmux_xfrm_input_init(struct osmux_in_handle *h)
 {
 	struct osmux_link *link;
@@ -849,7 +848,7 @@
 	osmux_link_del_circuit(link, circuit);
 }
 
-/* DEPRECATED: Use talloc_free() instead (will call osmux_xfrm_input_talloc_destructor()) */
+/*! \deprecated: Use talloc_free() instead (will call osmux_xfrm_input_talloc_destructor()) */
 void osmux_xfrm_input_fini(struct osmux_in_handle *h)
 {
 	(void)osmux_xfrm_input_talloc_destructor(h);
diff --git a/src/osmux_output.c b/src/osmux_output.c
index f48e1c9..664ed60 100644
--- a/src/osmux_output.c
+++ b/src/osmux_output.c
@@ -27,6 +27,12 @@
 
 #include <arpa/inet.h>
 
+/* delta time between two RTP messages (in microseconds) */
+#define DELTA_RTP_MSG		20000
+/* delta time between two RTP messages (in samples, 8kHz) */
+#define DELTA_RTP_TIMESTAMP	160
+
+
 /*! \addtogroup osmux Osmocom Multiplex Protocol
  *  @{
  *
@@ -43,12 +49,6 @@
 /*! \file osmux_output.c
  *  \brief Osmocom multiplex protocol helpers (output)
  */
-
-/* delta time between two RTP messages (in microseconds) */
-#define DELTA_RTP_MSG		20000
-/* delta time between two RTP messages (in samples, 8kHz) */
-#define DELTA_RTP_TIMESTAMP	160
-
 static uint32_t osmux_ft_dummy_size(uint8_t amr_ft, uint8_t batch_factor)
 {
 	return sizeof(struct osmux_hdr) + (osmo_amr_bytes(amr_ft) * batch_factor);
@@ -330,14 +330,14 @@
 	return h;
 }
 
-/* DEPRECATED: Use osmux_xfrm_output_alloc() and osmux_xfrm_output_set_rtp_*() instead */
+/*! \deprecated: Use osmux_xfrm_output_alloc() and osmux_xfrm_output_set_rtp_*() instead */
 void osmux_xfrm_output_init2(struct osmux_out_handle *h, uint32_t rtp_ssrc, uint8_t rtp_payload_type)
 {
 	memset(h, 0, sizeof(*h));
 	_osmux_xfrm_output_init(h, rtp_ssrc, rtp_payload_type);
 }
 
-/* DEPRECATED: Use osmux_xfrm_output_alloc() and osmux_xfrm_output_set_rtp_*() instead */
+/*! \deprecated: Use osmux_xfrm_output_alloc() and osmux_xfrm_output_set_rtp_*() instead */
 void osmux_xfrm_output_init(struct osmux_out_handle *h, uint32_t rtp_ssrc)
 {
 	/* backward compatibility with old users, where 98 was harcoded in osmux_rebuild_rtp()  */

