Update doxygen annotations in libosmocore

This adds and improves doxygen API descriptions all over libosmocore,
reducing the 'white spots' that don't have any documentation.

1 files changed, 20 insertions, 1 deletions

diff --git a/src/gsmtap_util.c b/src/gsmtap_util.c
index 82690a9c..7a63771a 100644
--- a/src/gsmtap_util.c
+++ b/src/gsmtap_util.c
@@ -99,6 +99,7 @@ uint8_t chantype_rsl2gsmtap(uint8_t rsl_chantype, uint8_t link_id)
  *  \param[in] snr Signal/Noise Ratio (SNR)
  *  \param[in] data Pointer to data buffer
  *  \param[in] len Length of \ref data
+ *  \return dynamically allocated message buffer containing data
  *
  * This function will allocate a new msgb and fill it with a GSMTAP
  * header containing the information
@@ -145,6 +146,7 @@ struct msgb *gsmtap_makemsg_ex(uint8_t type, uint16_t arfcn, uint8_t ts, uint8_t
  *  \param[in] snr Signal/Noise Ratio (SNR)
  *  \param[in] data Pointer to data buffer
  *  \param[in] len Length of \ref data
+ *  \return message buffer or NULL in case of error
  *
  * This function will allocate a new msgb and fill it with a GSMTAP
  * header containing the information
@@ -165,6 +167,7 @@ struct msgb *gsmtap_makemsg(uint16_t arfcn, uint8_t ts, uint8_t chan_type,
 /*! \brief Create a new (sending) GSMTAP source socket 
  *  \param[in] host host name or IP address in string format
  *  \param[in] port UDP port number in host byte order
+ *  \return file descriptor of the new socket
  *
  * Opens a GSMTAP source (sending) socket, conncet it to host/port and
  * return resulting fd.  If \a host is NULL, the destination address
@@ -217,6 +220,7 @@ int gsmtap_source_add_sink_fd(int gsmtap_fd)
 /*! \brief Send a \ref msgb through a GSMTAP source
  *  \param[in] gti GSMTAP instance
  *  \param[in] msg message buffer
+ *  \return 0 in case of success; negative in case of error
  */
 int gsmtap_sendmsg(struct gsmtap_inst *gti, struct msgb *msg)
 {
@@ -312,7 +316,21 @@ static int gsmtap_sink_fd_cb(struct osmo_fd *fd, unsigned int flags)
 	return 0;
 }
 
-/*! \brief Add a local sink to an existing GSMTAP source instance */
+/*! \brief Add a local sink to an existing GSMTAP source and return fd
+ *  \param[in] gsmtap_fd file descriptor of the gsmtap socket
+ *  \returns file descriptor of locally bound receive socket
+ *
+ *  In case the GSMTAP socket is connected to a local destination
+ *  IP/port, this function creates a corresponding receiving socket
+ *  bound to that destination IP + port.
+ *
+ *  In case the gsmtap socket is not connected to a local IP/port, or
+ *  creation of the receiving socket fails, a negative error code is
+ *  returned.
+ *
+ *  The file descriptor of the receiving socket is automatically added
+ *  to the libosmocore select() handling.
+ */
 int gsmtap_source_add_sink(struct gsmtap_inst *gti)
 {
 	int fd;
@@ -340,6 +358,7 @@ int gsmtap_source_add_sink(struct gsmtap_inst *gti)
  *  \param[in] host host name or IP address in string format
  *  \param[in] port UDP port number in host byte order
  *  \param[in] ofd_wq_mode Register \ref osmo_wqueue (1) or not (0)
+ *  \return callee-allocated \ref gsmtap_inst
  *
  * Open GSMTAP source (sending) socket, connect it to host/port,
  * allocate 'struct gsmtap_inst' and optionally osmo_fd/osmo_wqueue