ns2: Improve/extend doxygen comments for new ns2 implementation

I was reading through the code and noticed many functions not
documented yet, or with incomplete documentation. Change that.

Change-Id: I85a2419604a9fd9ff3c4828a7463e222652f77bf

6 files changed, 197 insertions, 126 deletions

diff --git a/src/gb/gprs_ns2.c b/src/gb/gprs_ns2.c
index 0fa71975..21a45a13 100644
--- a/src/gb/gprs_ns2.c
+++ b/src/gb/gprs_ns2.c
@@ -203,6 +203,11 @@ static const struct osmo_stat_item_group_desc nsvc_statg_desc = {
 	.class_id = OSMO_STATS_CLASS_PEER,
 };
 
+/*! string-format a given NS-VC into a user-supplied buffer.
+ *  \param[in] buf user-allocated output buffer
+ *  \param[in] buf_len size of user-allocated output buffer in bytes
+ *  \param[in] nsvc NS-VC to be string-formatted
+ *  \return pointer to buf on success; NULL on error */
 char *gprs_ns2_ll_str_buf(char *buf, size_t buf_len, struct gprs_ns2_vc *nsvc)
 {
 	struct osmo_sockaddr *local;
@@ -256,12 +261,19 @@ char *gprs_ns2_ll_str_buf(char *buf, size_t buf_len, struct gprs_ns2_vc *nsvc)
 /* udp is the longest: udp)[IP6]:65536<65536>[IP6]:65536 */
 #define NS2_LL_MAX_STR 4+2*(INET6_ADDRSTRLEN+9)+8
 
+/*! string-format a given NS-VC to a thread-local static buffer.
+ *  \param[in] nsvc NS-VC to be string-formatted
+ *  \return pointer to the string on success; NULL on error */
 const char *gprs_ns2_ll_str(struct gprs_ns2_vc *nsvc)
 {
 	static __thread char buf[NS2_LL_MAX_STR];
 	return gprs_ns2_ll_str_buf(buf, sizeof(buf), nsvc);
 }
 
+/*! string-format a given NS-VC to a dynamically allocated string.
+ *  \param[in] ctx talloc context from which to allocate
+ *  \param[in] nsvc NS-VC to be string-formatted
+ *  \return pointer to the string on success; NULL on error */
 char *gprs_ns2_ll_str_c(const void *ctx, struct gprs_ns2_vc *nsvc)
 {
 	char *buf = talloc_size(ctx, NS2_LL_MAX_STR);
@@ -270,12 +282,10 @@ char *gprs_ns2_ll_str_c(const void *ctx, struct gprs_ns2_vc *nsvc)
 	return gprs_ns2_ll_str_buf(buf, NS2_LL_MAX_STR, nsvc);
 }
 
-/*!
- * Receive a primitive from the NS User (Gb)
- * \param nsi
- * \param oph The primitive.
- * \return 0 on success
- */
+/*! Receive a primitive from the NS User (Gb).
+ *  \param[in] nsi NS instance to which the primitive is issued
+ *  \param[in] oph The primitive
+ *  \return 0 on success; negative on error */
 int gprs_ns2_recv_prim(struct gprs_ns2_inst *nsi, struct osmo_prim_hdr *oph)
 {
 	/* TODO: implement load distribution function */
@@ -329,6 +339,11 @@ int gprs_ns2_recv_prim(struct gprs_ns2_inst *nsi, struct osmo_prim_hdr *oph)
 	return ns2_tx_unit_data(nsvc, bvci, sducontrol, oph->msg);
 }
 
+/*! Send a STATUS.ind primitive to the specified NS instance user.
+ *  \param[in] nsi NS instance on which we operate
+ *  \param[in] nsei NSEI to which the statue relates
+ *  \param[in] bvci BVCI to which the status relates
+ *  \param[in] cause The cause of the status */
 void ns2_prim_status_ind(struct gprs_ns2_inst *nsi,
 			 uint16_t nsei, uint16_t bvci,
 			 enum gprs_ns2_affecting_cause cause)
@@ -343,13 +358,11 @@ void ns2_prim_status_ind(struct gprs_ns2_inst *nsi,
 	nsi->cb(&nsp.oph, nsi->cb_data);
 }
 
-/*!
- * \brief ns2_vc_alloc
- * \param bind
- * \param nse
- * \param initiater - if this is an incoming remote (!initiater) or a local outgoing connection (initater)
- * \return
- */
+/*! Allocate a NS-VC within the given bind + NSE.
+ * \param[in] bind The 'bind' on which we operate
+ * \param[in] nse The NS Entity on which we operate
+ * \param[in] initiater - if this is an incoming remote (!initiater) or a local outgoing connection (initater)
+ * \return newly allocated NS-VC on success; NULL on error */
 struct gprs_ns2_vc *ns2_vc_alloc(struct gprs_ns2_vc_bind *bind, struct gprs_ns2_nse *nse, bool initiater)
 {
 	struct gprs_ns2_vc *nsvc = talloc_zero(bind, struct gprs_ns2_vc);
@@ -390,7 +403,8 @@ err:
 	return NULL;
 }
 
-
+/*! Destroy/release given NS-VC.
+ *  \param[in] nsvc NS-VC to destroy */
 void gprs_ns2_free_nsvc(struct gprs_ns2_vc *nsvc)
 {
 	if (!nsvc)
@@ -419,6 +433,7 @@ void gprs_ns2_free_nsvc(struct gprs_ns2_vc *nsvc)
 	talloc_free(nsvc);
 }
 
+/*! Allocate a message buffer for use with the NS2 stack. */
 struct msgb *gprs_ns2_msgb_alloc(void)
 {
 	struct msgb *msg = msgb_alloc_headroom(NS_ALLOC_SIZE, NS_ALLOC_HEADROOM,
@@ -430,14 +445,12 @@ struct msgb *gprs_ns2_msgb_alloc(void)
 	return msg;
 }
 
-/*!
- * Create a status message to be sent over a new connection.
- * \param[in] orig_msg the original message
- * \param[in] tp TLVP parsed of the original message
- * \param[out] reject
- * \param[in] cause
- * \return 0 on success
- */
+/*! Create a status message to be sent over a new connection.
+ *  \param[in] orig_msg the original message
+ *  \param[in] tp TLVP parsed of the original message
+ *  \param[out] reject callee-allocated message buffer of the generated NS-STATUS
+ *  \param[in] cause Cause for the rejection
+ *  \return 0 on success */
 static int reject_status_msg(struct msgb *orig_msg, struct tlv_parsed *tp, struct msgb **reject, enum ns_cause cause)
 {
 	struct msgb *msg = gprs_ns2_msgb_alloc();
@@ -492,6 +505,10 @@ static int reject_status_msg(struct msgb *orig_msg, struct tlv_parsed *tp, struc
 	return 0;
 }
 
+/*! Resolve a NS Entity based on its NSEI.
+ *  \param[in] nsi NS Instance in which we do the look-up
+ *  \param[in] nsei NSEI to look up
+ *  \return NS Entity in successful case; NULL if none found */
 struct gprs_ns2_nse *gprs_ns2_nse_by_nsei(struct gprs_ns2_inst *nsi, uint16_t nsei)
 {
 	struct gprs_ns2_nse *nse;
@@ -504,6 +521,10 @@ struct gprs_ns2_nse *gprs_ns2_nse_by_nsei(struct gprs_ns2_inst *nsi, uint16_t ns
 	return NULL;
 }
 
+/*! Resolve a NS-VC Entity based on its NS-VCI.
+ *  \param[in] nsi NS Instance in which we do the look-up
+ *  \param[in] nsvci NS-VCI to look up
+ *  \return NS-VC Entity in successful case; NULL if none found */
 struct gprs_ns2_vc *gprs_ns2_nsvc_by_nsvci(struct gprs_ns2_inst *nsi, uint16_t nsvci)
 {
 	struct gprs_ns2_nse *nse;
@@ -519,6 +540,10 @@ struct gprs_ns2_vc *gprs_ns2_nsvc_by_nsvci(struct gprs_ns2_inst *nsi, uint16_t n
 	return NULL;
 }
 
+/*! Create a NS Entity within given NS instance.
+ *  \param[in] nsi NS instance in which to create NS Entity
+ *  \param[in] nsei NS Entity Identifier of to-be-created NSE
+ *  \returns newly-allocated NS-E in successful case; NULL on error */
 struct gprs_ns2_nse *gprs_ns2_create_nse(struct gprs_ns2_inst *nsi, uint16_t nsei)
 {
 	struct gprs_ns2_nse *nse;
@@ -541,6 +566,8 @@ struct gprs_ns2_nse *gprs_ns2_create_nse(struct gprs_ns2_inst *nsi, uint16_t nse
 	return nse;
 }
 
+/*! Destroy given NS Entity.
+ *  \param[in] nse NS Entity to destroy */
 void gprs_ns2_free_nse(struct gprs_ns2_nse *nse)
 {
 	struct gprs_ns2_vc *nsvc, *tmp;
@@ -574,15 +601,13 @@ static inline int ns2_tlv_parse(struct tlv_parsed *dec,
 }
 
 
-/*!
- * Create a new VC based on a message. Depending on the bind it might create NSE.
- * \param[in] bind
- * \param[in] msg
- * \param[in] logname A name to describe the VC. E.g. ip address pair
- * \param[out] reject A message filled to be sent back. Only used in failure cases.
- * \param[out] success A pointer which will be set to the new VC on success
- * \return
- */
+/*! Create a new NS-VC based on a [received] message. Depending on the bind it might create a NSE.
+ *  \param[in] bind the bind through which msg was received
+ *  \param[in] msg the actual received message
+ *  \param[in] logname A name to describe the VC. E.g. ip address pair
+ *  \param[out] reject A message filled to be sent back. Only used in failure cases.
+ *  \param[out] success A pointer which will be set to the new VC on success
+ *  \return enum value indicating the status, e.g. GPRS_NS2_CS_CREATED */
 enum gprs_ns2_cs ns2_create_vc(struct gprs_ns2_vc_bind *bind,
 			       struct msgb *msg,
 			       const char *logname,
@@ -696,6 +721,12 @@ enum gprs_ns2_cs ns2_create_vc(struct gprs_ns2_vc_bind *bind,
 	return GPRS_NS2_CS_CREATED;
 }
 
+/*! Create, and connect an inactive, new IP-based NS-VC
+ *  \param[in] bind bind in which the new NS-VC is to be created
+ *  \param[in] remote remote address to which to connect
+ *  \param[in] nse NS Entity in which the NS-VC is to be created
+ *  \param[in] nsvci is only required when bind->vc_mode == NS2_VC_MODE_BLOCKRESET
+ *  \return pointer to newly-allocated, connected and inactive NS-VC; NULL on error */
 struct gprs_ns2_vc *gprs_ns2_ip_connect_inactive(struct gprs_ns2_vc_bind *bind,
 					struct osmo_sockaddr *remote,
 					struct gprs_ns2_nse *nse,
@@ -715,14 +746,12 @@ struct gprs_ns2_vc *gprs_ns2_ip_connect_inactive(struct gprs_ns2_vc_bind *bind,
 	return nsvc;
 }
 
-/*!
- * Create a new IP-based NSVC
- * \param bind
- * \param remote
- * \param nse
- * \param nsvci is only required when bind->vc_mode == NS2_VC_MODE_BLOCKRESET
- * \return
- */
+/*! Create, connect and activate a new IP-based NS-VC
+ *  \param[in] bind bind in which the new NS-VC is to be created
+ *  \param[in] remote remote address to which to connect
+ *  \param[in] nse NS Entity in which the NS-VC is to be created
+ *  \param[in] nsvci is only required when bind->vc_mode == NS2_VC_MODE_BLOCKRESET
+ *  \return pointer to newly-allocated, connected and activated NS-VC; NULL on error */
 struct gprs_ns2_vc *gprs_ns2_ip_connect(struct gprs_ns2_vc_bind *bind,
 					struct osmo_sockaddr *remote,
 					struct gprs_ns2_nse *nse,
@@ -738,14 +767,12 @@ struct gprs_ns2_vc *gprs_ns2_ip_connect(struct gprs_ns2_vc_bind *bind,
 	return nsvc;
 }
 
-/*!
- * Create a new IP-based NSVC
- * \param bind
- * \param remote
- * \param nsei
- * \param nsvci only required when bind->vc_mode == NS2_VC_MODE_BLOCKRESET
- * \return
- */
+/*! Create, connect and activate a new IP-based NS-VC
+ *  \param[in] bind bind in which the new NS-VC is to be created
+ *  \param[in] remote remote address to which to connect
+ *  \param[in] nsei NSEI of the NS Entity in which the NS-VC is to be created
+ *  \param[in] nsvci is only required when bind->vc_mode == NS2_VC_MODE_BLOCKRESET
+ *  \return pointer to newly-allocated, connected and activated NS-VC; NULL on error */
 struct gprs_ns2_vc *gprs_ns2_ip_connect2(struct gprs_ns2_vc_bind *bind,
 					 struct osmo_sockaddr *remote,
 					 uint16_t nsei,
@@ -762,13 +789,11 @@ struct gprs_ns2_vc *gprs_ns2_ip_connect2(struct gprs_ns2_vc_bind *bind,
 	return gprs_ns2_ip_connect(bind, remote, nse, nsvci);
 }
 
-/*!
- * Create a new IP SNS NSE
- * \param bind
- * \param remote
- * \param nsei
- * \return 0 on success
- */
+/*! Create, connect and activate a new IP-SNS NSE.
+ *  \param[in] bind bind in which the new NS-VC is to be created
+ *  \param[in] remote remote address to which to connect
+ *  \param[in] nsei NSEI of the NS Entity in which the NS-VC is to be created
+ *  \return 0 on success; negative on error */
 int gprs_ns2_ip_connect_sns(struct gprs_ns2_vc_bind *bind,
 			    struct osmo_sockaddr *remote,
 			    uint16_t nsei)
@@ -795,6 +820,10 @@ int gprs_ns2_ip_connect_sns(struct gprs_ns2_vc_bind *bind,
 	return ns2_sns_bss_fsm_start(nse, nsvc, remote);
 }
 
+/*! Find NS-VC for given socket address.
+ *  \param[in] nse NS Entity in which to search
+ *  \param[in] sockaddr socket address to search for
+ *  \return NS-VC matching sockaddr; NULL if none found */
 struct gprs_ns2_vc *gprs_ns2_nsvc_by_sockaddr(struct gprs_ns2_nse *nse,
 					      struct osmo_sockaddr *sockaddr)
 {
@@ -814,13 +843,11 @@ struct gprs_ns2_vc *gprs_ns2_nsvc_by_sockaddr(struct gprs_ns2_nse *nse,
 }
 
 
-/*!
- * \brief gprs_ns2_recv_vc entrypoint of received NS PDU from the driver/bind
- * \param nsi
- * \param vc
- * \param msg the received message. Must not be freeded.
- * \return
- */
+/*! Bottom-side entry-point for received NS PDU from the driver/bind
+ * \param[in] nsi NS instance
+ * \param[in] nsvc NS-VC for which the message was received
+ * \param msg the received message. Ownership is trasnferred, caller must not free it!
+ * \return 0 on success; negative on error */
 int ns2_recv_vc(struct gprs_ns2_inst *nsi,
 		struct gprs_ns2_vc *nsvc,
 		struct msgb *msg)
@@ -893,7 +920,9 @@ int ns2_recv_vc(struct gprs_ns2_inst *nsi,
 	return rc;
 }
 
-/* notify a nse about the change of a nsvc */
+/*! Notify a nse about the change of a NS-VC.
+ *  \param[in] nsvc NS-VC which has detected the change (and shall not be notified).
+ *  \param[in] unblocked whether the NSE should be marked as unblocked (true) or blocked (false) */
 void ns2_nse_notify_unblocked(struct gprs_ns2_vc *nsvc, bool unblocked)
 {
 	struct gprs_ns2_nse *nse = nsvc->nse;
@@ -928,11 +957,10 @@ void ns2_nse_notify_unblocked(struct gprs_ns2_vc *nsvc, bool unblocked)
 }
 
 /*! Create a new GPRS NS instance
- *  \param[in] ctx a talloc context
- *  \param[in] cb Call-back function for incoming BSSGP data
- *  \param[in] cb_data Call-back data
- *  \returns dynamically allocated gprs_ns_inst
- */
+ *  \param[in] ctx a talloc context to allocate NS instance from
+ *  \param[in] cb Call-back function for dispatching primitives to the user
+ *  \param[in] cb_data transparent user data passed to Call-back
+ *  \returns dynamically allocated gprs_ns_inst; NULL on error */
 struct gprs_ns2_inst *gprs_ns2_instantiate(void *ctx, osmo_prim_cb cb, void *cb_data)
 {
 	struct gprs_ns2_inst *nsi;
@@ -958,6 +986,8 @@ struct gprs_ns2_inst *gprs_ns2_instantiate(void *ctx, osmo_prim_cb cb, void *cb_
 	return nsi;
 }
 
+/*! Destroy a NS Instance (including all its NSEs, binds, ...).
+ *  \param[in] nsi NS instance to destroy */
 void gprs_ns2_free(struct gprs_ns2_inst *nsi)
 {
 	struct gprs_ns2_vc_bind *bind, *tbind;
@@ -975,11 +1005,10 @@ void gprs_ns2_free(struct gprs_ns2_inst *nsi)
 	}
 }
 
-/*!
- * \brief gprs_ns2_dynamic_create_nse
- * \param nsi the instance to modify
- * \param create_nse if NSE can be created on receiving package. SGSN set this.
- * \return
+/*! Configure whether a NS Instance should dynamically create NSEs based on incoming traffic.
+ *  \param nsi the instance to modify
+ *  \param create_nse if NSE can be created on receiving package. SGSN set this.
+ *  \return 0 on success; negative on error
  */
 int gprs_ns2_dynamic_create_nse(struct gprs_ns2_inst *nsi, bool create_nse)
 {
@@ -988,6 +1017,8 @@ int gprs_ns2_dynamic_create_nse(struct gprs_ns2_inst *nsi, bool create_nse)
 	return 0;
 }
 
+/*! Start the NS-ALIVE FSM in all NS-VCs of given NSE.
+ *  \param[in] nse NS Entity in whihc to start NS-ALIVE FSMs */
 void gprs_ns2_start_alive_all_nsvcs(struct gprs_ns2_nse *nse)
 {
 	struct gprs_ns2_vc *nsvc;
@@ -1001,11 +1032,16 @@ void gprs_ns2_start_alive_all_nsvcs(struct gprs_ns2_nse *nse)
 	}
 }
 
+/*! Set the mode of given bind.
+ *  \param[in] bind the bind we want to set the mode of
+ *  \param[in] modde mode to set bind to */
 void gprs_ns2_bind_set_mode(struct gprs_ns2_vc_bind *bind, enum gprs_ns2_vc_mode mode)
 {
 	bind->vc_mode = mode;
 }
 
+/*! Destroy a given bind.
+ *  \param[in] bind the bind we want to destroy */
 void gprs_ns2_free_bind(struct gprs_ns2_vc_bind *bind)
 {
 	struct gprs_ns2_vc *nsvc, *tmp;
diff --git a/src/gb/gprs_ns2_frgre.c b/src/gb/gprs_ns2_frgre.c
index 2b19157b..715c41a6 100644
--- a/src/gb/gprs_ns2_frgre.c
+++ b/src/gb/gprs_ns2_frgre.c
@@ -528,11 +528,18 @@ static int frgre_fd_cb(struct osmo_fd *bfd, unsigned int what)
 	return rc;
 }
 
+/*! determine if given bind is for FR-GRE encapsulation. */
 int gprs_ns2_is_frgre_bind(struct gprs_ns2_vc_bind *bind)
 {
 	return (bind->driver == &vc_driver_frgre);
 }
 
+/*! Create a new bind for NS over FR-GRE.
+ *  \param[in] nsi NS instance in which to create the bind
+ *  \param[in] local local address on which to bind
+ *  \param[in] dscp DSCP/TOS bits to use for transmitted data on this bind
+ *  \param[out] result pointer to created bind
+ *  \return 0 on success; negative on error */
 int gprs_ns2_frgre_bind(struct gprs_ns2_inst *nsi,
 			struct osmo_sockaddr *local,
 			int dscp,
diff --git a/src/gb/gprs_ns2_message.c b/src/gb/gprs_ns2_message.c
index 7742404e..b4063f5e 100644
--- a/src/gb/gprs_ns2_message.c
+++ b/src/gb/gprs_ns2_message.c
@@ -202,11 +202,10 @@ static int ns2_tx_simple(struct gprs_ns2_vc *nsvc, uint8_t pdu_type)
 	return nsvc->bind->send_vc(nsvc, msg);
 }
 
-/*! Transmit a NS-BLOCK on a given NS-VC
+/*! Transmit a NS-BLOCK on a given NS-VC.
  *  \param[in] vc NS-VC on which the NS-BLOCK is to be transmitted
  *  \param[in] cause Numeric NS Cause value
- *  \returns 0 in case of success
- */
+ *  \returns 0 in case of success */
 int ns2_tx_block(struct gprs_ns2_vc *nsvc, uint8_t cause)
 {
 	struct msgb *msg;
@@ -236,10 +235,9 @@ int ns2_tx_block(struct gprs_ns2_vc *nsvc, uint8_t cause)
 	return nsvc->bind->send_vc(nsvc, msg);
 }
 
-/*! Transmit a NS-BLOCK-ACK on a given NS-VC
+/*! Transmit a NS-BLOCK-ACK on a given NS-VC.
  *  \param[in] nsvc NS-VC on which the NS-BLOCK is to be transmitted
- *  \returns 0 in case of success
- */
+ *  \returns 0 in case of success */
 int ns2_tx_block_ack(struct gprs_ns2_vc *nsvc)
 {
 	struct msgb *msg;
@@ -266,10 +264,10 @@ int ns2_tx_block_ack(struct gprs_ns2_vc *nsvc)
 	return nsvc->bind->send_vc(nsvc, msg);
 }
 
-/*! Transmit a NS-RESET on a given NSVC
+/*! Transmit a NS-RESET on a given NS-VC.
  *  \param[in] nsvc NS-VC used for transmission
  *  \paam[in] cause Numeric NS cause value
- */
+ *  \returns 0 in case of success */
 int ns2_tx_reset(struct gprs_ns2_vc *nsvc, uint8_t cause)
 {
 	struct msgb *msg;
@@ -299,13 +297,16 @@ int ns2_tx_reset(struct gprs_ns2_vc *nsvc, uint8_t cause)
 	return nsvc->bind->send_vc(nsvc, msg);
 }
 
-/* Section 9.2.6 */
+/*! Transmit a NS-RESET-ACK on a given NS-VC.
+ *  \param[in] nsvc NS-VC used for transmission
+ *  \returns 0 in case of success */
 int ns2_tx_reset_ack(struct gprs_ns2_vc *nsvc)
 {
 	struct msgb *msg;
 	struct gprs_ns_hdr *nsh;
 	uint16_t nsvci, nsei;
 
+	/* Section 9.2.6 */
 	log_set_context(LOG_CTX_GB_NSVC, nsvc);
 
 	ERR_IF_NSVC_USES_SNS(nsvc, "transmit NS RESET ACK");
@@ -331,10 +332,9 @@ int ns2_tx_reset_ack(struct gprs_ns2_vc *nsvc)
 	return nsvc->bind->send_vc(nsvc, msg);
 }
 
-/*! Transmit a NS-UNBLOCK on a given NS-VC
+/*! Transmit a NS-UNBLOCK on a given NS-VC.
  *  \param[in] nsvc NS-VC on which the NS-UNBLOCK is to be transmitted
- *  \returns 0 in case of success
- */
+ *  \returns 0 in case of success */
 int ns2_tx_unblock(struct gprs_ns2_vc *nsvc)
 {
 	log_set_context(LOG_CTX_GB_NSVC, nsvc);
@@ -348,10 +348,9 @@ int ns2_tx_unblock(struct gprs_ns2_vc *nsvc)
 }
 
 
-/*! Transmit a NS-UNBLOCK-ACK on a given NS-VC
+/*! Transmit a NS-UNBLOCK-ACK on a given NS-VC.
  *  \param[in] nsvc NS-VC on which the NS-UNBLOCK-ACK is to be transmitted
- *  \returns 0 in case of success
- */
+ *  \returns 0 in case of success */
 int ns2_tx_unblock_ack(struct gprs_ns2_vc *nsvc)
 {
 	log_set_context(LOG_CTX_GB_NSVC, nsvc);
@@ -364,10 +363,9 @@ int ns2_tx_unblock_ack(struct gprs_ns2_vc *nsvc)
 	return ns2_tx_simple(nsvc, NS_PDUT_UNBLOCK_ACK);
 }
 
-/*! Transmit a NS-ALIVE on a given NS-VC
+/*! Transmit a NS-ALIVE on a given NS-VC.
  *  \param[in] nsvc NS-VC on which the NS-ALIVE is to be transmitted
- *  \returns 0 in case of success
- */
+ *  \returns 0 in case of success */
 int ns2_tx_alive(struct gprs_ns2_vc *nsvc)
 {
 	log_set_context(LOG_CTX_GB_NSVC, nsvc);
@@ -377,10 +375,9 @@ int ns2_tx_alive(struct gprs_ns2_vc *nsvc)
 	return ns2_tx_simple(nsvc, NS_PDUT_ALIVE);
 }
 
-/*! Transmit a NS-ALIVE-ACK on a given NS-VC
+/*! Transmit a NS-ALIVE-ACK on a given NS-VC.
  *  \param[in] nsvc NS-VC on which the NS-ALIVE-ACK is to be transmitted
- *  \returns 0 in case of success
- */
+ *  \returns 0 in case of success */
 int ns2_tx_alive_ack(struct gprs_ns2_vc *nsvc)
 {
 	log_set_context(LOG_CTX_GB_NSVC, nsvc);
@@ -390,6 +387,12 @@ int ns2_tx_alive_ack(struct gprs_ns2_vc *nsvc)
 	return ns2_tx_simple(nsvc, NS_PDUT_ALIVE_ACK);
 }
 
+/*! Transmit NS-UNITDATA on a given NS-VC.
+ *  \param[in] nsvc NS-VC on which the NS-UNITDATA is to be transmitted
+ *  \param[in] bvci BVCI to encode in NS-UNITDATA header
+ *  \param[in] sducontrol SDU control octet of NS header
+ *  \param[in] msg message buffer containing payload
+ *  \returns 0 in case of success */
 int ns2_tx_unit_data(struct gprs_ns2_vc *nsvc,
 		     uint16_t bvci, uint8_t sducontrol,
 		     struct msgb *msg)
@@ -414,11 +417,12 @@ int ns2_tx_unit_data(struct gprs_ns2_vc *nsvc,
 	return nsvc->bind->send_vc(nsvc, msg);
 }
 
-/*! Transmit a NS-STATUS on a given NSVC
+/*! Transmit a NS-STATUS on a given NS-VC.
  *  \param[in] nsvc NS-VC to be used for transmission
  *  \param[in] cause Numeric NS cause value
  *  \param[in] bvci BVCI to be reset within NSVC
- *  \param[in] orig_msg message causing the STATUS */
+ *  \param[in] orig_msg message causing the STATUS
+ *  \returns 0 in case of success */
 int ns2_tx_status(struct gprs_ns2_vc *nsvc, uint8_t cause,
 		       uint16_t bvci, struct msgb *orig_msg)
 {
diff --git a/src/gb/gprs_ns2_sns.c b/src/gb/gprs_ns2_sns.c
index d4bed84c..812200dc 100644
--- a/src/gb/gprs_ns2_sns.c
+++ b/src/gb/gprs_ns2_sns.c
@@ -1198,6 +1198,10 @@ static struct osmo_fsm gprs_ns2_sns_bss_fsm = {
 	.log_subsys = DLNS,
 };
 
+/*! Allocate an IP-SNS FSM for the BSS side.
+ *  \param[in] nse NS Entity in which the FSM runs
+ *  \param[in] id string identifier
+ *  \retruns FSM instance on success; NULL on error */
 struct osmo_fsm_inst *ns2_sns_bss_fsm_alloc(struct gprs_ns2_nse *nse,
 					    const char *id)
 {
@@ -1221,6 +1225,11 @@ err:
 	return NULL;
 }
 
+/*! Start an IP-SNS FSM.
+ *  \param[in] nse NS Entity whose IP-SNS FSM shall be started
+ *  \param[in] nsvc Initial NS-VC
+ *  \param[in] remote remote (SGSN) address
+ *  \returns 0 on success; negative on error */
 int ns2_sns_bss_fsm_start(struct gprs_ns2_nse *nse, struct gprs_ns2_vc *nsvc, struct osmo_sockaddr *remote)
 {
 	struct osmo_fsm_inst *fi = nse->bss_sns_fi;
@@ -1340,7 +1349,11 @@ err:
 	return -1;
 }
 
-/* main entry point for receiving SNS messages from the network */
+/*! main entry point for receiving SNS messages from the network.
+ *  \param[in] nsvc NS-VC on which the message was received
+ *  \param[in] msg message buffer of the IP-SNS message
+ *  \param[in] tp parsed TLV structure of message
+ *  \retruns 0 on success; negative on error */
 int gprs_ns2_sns_rx(struct gprs_ns2_vc *nsvc, struct msgb *msg, struct tlv_parsed *tp)
 {
 	struct gprs_ns2_nse *nse = nsvc->nse;
@@ -1418,6 +1431,10 @@ static void vty_dump_sns_ip6(struct vty *vty, const struct gprs_ns_ie_ip6_elem *
 		ip_addr, ntohs(ip6->udp_port), ip6->sig_weight, ip6->data_weight, VTY_NEWLINE);
 }
 
+/*! Dump the IP-SNS state to a vty.
+ *  \param[in] vty VTY to which the state shall be printed
+ *  \param[in] nse NS Entity whose IP-SNS state shall be printed
+ *  \param[in] stats Whether or not statistics shall also be printed */
 void gprs_ns2_sns_dump_vty(struct vty *vty, const struct gprs_ns2_nse *nse, bool stats)
 {
 	struct ns2_sns_state *gss;
diff --git a/src/gb/gprs_ns2_udp.c b/src/gb/gprs_ns2_udp.c
index f317219d..bb421a75 100644
--- a/src/gb/gprs_ns2_udp.c
+++ b/src/gb/gprs_ns2_udp.c
@@ -78,6 +78,11 @@ static void free_vc(struct gprs_ns2_vc *nsvc)
 	nsvc->priv = NULL;
 }
 
+/*! Find a NS-VC by its remote socket address.
+ *  \param[in] bind in which to search
+ *  \param[in] saddr remote peer socket adddress to search
+ *  \param[out] result pointer to result
+ *  \returns 0 on success; 1 if no NS-VC was found; negative on error */
 int gprs_ns2_find_vc_by_sockaddr(struct gprs_ns2_vc_bind *bind, struct osmo_sockaddr *saddr, struct gprs_ns2_vc **result)
 {
 	struct gprs_ns2_vc *nsvc;
@@ -115,12 +120,10 @@ static inline int nsip_sendmsg(struct gprs_ns2_vc_bind *bind,
 	return rc;
 }
 
-/*!
- * \brief nsip_vc_sendmsg will send the msg and free msgb afterwards.
- * \param vc
- * \param msg
- * \return < 0 on erros, otherwise the bytes sent.
- */
+/*! send the msg and free it afterwards.
+ * \param nsvc NS-VC on which the message shall be sent
+ * \param msg message to be sent
+ * \return number of bytes transmitted; negative on error */
 static int nsip_vc_sendmsg(struct gprs_ns2_vc *nsvc, struct msgb *msg)
 {
 	int rc;
@@ -241,13 +244,12 @@ static int nsip_fd_cb(struct osmo_fd *bfd, unsigned int what)
 	return rc;
 }
 
-/*!
- * \brief bind to an IPv4/IPv6 address
- * \param[in] nsi NS Instance in which to create the NSVC
- * \param[in] address the address to bind to
- * \param[out] result if set, returns the bind object
- * \return
- */
+/*! Bind to an IPv4/IPv6 address
+ *  \param[in] nsi NS Instance in which to create the NSVC
+ *  \param[in] local the local address to bind to
+ *  \param[in] dscp the DSCP/TOS bits used for transmitted data
+ *  \param[out] result if set, returns the bind object
+ *  \return 0 on success; negative in case of error */
 int gprs_ns2_ip_bind(struct gprs_ns2_inst *nsi,
 		     struct osmo_sockaddr *local,
 		     int dscp,
@@ -310,6 +312,11 @@ int gprs_ns2_ip_bind(struct gprs_ns2_inst *nsi,
 	return 0;
 }
 
+/*! Create new NS-VC to a given remote address
+ *  \param[in] bind the bind we want to connect
+ *  \param[in] nse NS entity to be used for the new NS-VC
+ *  \param[in] remote remote address to connect to
+ *  \return pointer to newly-allocated and connected NS-VC; NULL on error */
 struct gprs_ns2_vc *gprs_ns2_ip_bind_connect(struct gprs_ns2_vc_bind *bind,
 					     struct gprs_ns2_nse *nse,
 					     struct osmo_sockaddr *remote)
@@ -332,6 +339,9 @@ struct gprs_ns2_vc *gprs_ns2_ip_bind_connect(struct gprs_ns2_vc_bind *bind,
 	return nsvc;
 }
 
+/*! Return the socket address of the remote peer of a NS-VC.
+ *  \param[in] nsvc NS-VC whose remote peer we want to know
+ *  \return address of the remote peer; NULL in case of error */
 struct osmo_sockaddr *gprs_ns2_ip_vc_sockaddr(struct gprs_ns2_vc *nsvc)
 {
 	struct priv_vc *priv;
@@ -343,6 +353,9 @@ struct osmo_sockaddr *gprs_ns2_ip_vc_sockaddr(struct gprs_ns2_vc *nsvc)
 	return &priv->remote;
 }
 
+/*! Return the locally bound socket address of the bind.
+ *  \param[in] bind The bind whose local address we want to know
+ *  \return address of the local bind */
 struct osmo_sockaddr *gprs_ns2_ip_bind_sockaddr(struct gprs_ns2_vc_bind *bind)
 {
 	struct priv_bind *priv;
@@ -351,11 +364,13 @@ struct osmo_sockaddr *gprs_ns2_ip_bind_sockaddr(struct gprs_ns2_vc_bind *bind)
 	return &priv->addr;
 }
 
+/*! Is the given bind an IP bind? */
 int gprs_ns2_is_ip_bind(struct gprs_ns2_vc_bind *bind)
 {
 	return (bind->driver == &vc_driver_ip);
 }
 
+/*! Set the DSCP (TOS) bit value of the given bind. */
 int gprs_ns2_ip_bind_set_dscp(struct gprs_ns2_vc_bind *bind, int dscp)
 {
 	struct priv_bind *priv;
diff --git a/src/gb/gprs_ns2_vc_fsm.c b/src/gb/gprs_ns2_vc_fsm.c
index 7487ecde..33a0328b 100644
--- a/src/gb/gprs_ns2_vc_fsm.c
+++ b/src/gb/gprs_ns2_vc_fsm.c
@@ -584,11 +584,9 @@ struct osmo_fsm_inst *gprs_ns2_vc_fsm_alloc(struct gprs_ns2_vc *nsvc,
 	return fi;
 }
 
-/*!
- * \brief gprs_ns2_vc_fsm_start start the FSM
- * \param vc the virtual circuit
- * \return 0 on success
- */
+/*! Start a NS-VC FSM.
+ *  \param nsvc the virtual circuit
+ *  \return 0 on success; negative on error */
 int gprs_ns2_vc_fsm_start(struct gprs_ns2_vc *nsvc)
 {
 	/* allows to call this function even for started nsvc by gprs_ns2_start_alive_all_nsvcs */
@@ -597,13 +595,11 @@ int gprs_ns2_vc_fsm_start(struct gprs_ns2_vc *nsvc)
 	return 0;
 }
 
-/*!
- * \brief gprs_ns2_vc_rx entry point for messages from the driver/VL
- * \param vc the virtual circuit on which is recived
- * \param msg the message
- * \param tp the parsed TLVs
- * \return 0 on success
- */
+/*! entry point for messages from the driver/VL
+ *  \param nsvc virtual circuit on which the message was received
+ *  \param msg message that was received
+ *  \param tp parsed TLVs of the received message
+ *  \return 0 on success; negative on error */
 int gprs_ns2_vc_rx(struct gprs_ns2_vc *nsvc, struct msgb *msg, struct tlv_parsed *tp)
 {
 	struct gprs_ns_hdr *nsh = (struct gprs_ns_hdr *) msg->l2h;
@@ -658,11 +654,7 @@ int gprs_ns2_vc_rx(struct gprs_ns2_vc *nsvc, struct msgb *msg, struct tlv_parsed
 	return 0;
 }
 
-/*!
- * \brief gprs_ns2_vc_is_alive says if this
- * \param vc
- * \return
- */
+/*! is the given NS-VC unblocked? */
 int gprs_ns2_vc_is_unblocked(struct gprs_ns2_vc *nsvc)
 {
 	return (nsvc->fi->state == GPRS_NS2_ST_UNBLOCKED);