From 9498eb1c15c7e92c50675e7a951c0c0ea73cd93d Mon Sep 17 00:00:00 2001
From: Andre Noll <maan@tuebingen.mpg.de>
Date: Tue, 16 May 2017 23:16:44 +0200
Subject: [PATCH] recv: Explain user data mechanism.

This is not obvious, so it deserves a comment in recv_init(). The
patch also adds a reference to each of the four instances of struct
receiver, reducing the number of doxygen warnings when EXTRACT_ALL
is set to NO in Doxyfile.
---
 afh_recv.c    | 1 +
 dccp_recv.c   | 1 +
 http_recv.c   | 1 +
 recv_common.c | 6 ++++++
 udp_recv.c    | 1 +
 5 files changed, 10 insertions(+)

diff --git a/afh_recv.c b/afh_recv.c
index 9d6effe1..d2d8b52b 100644
--- a/afh_recv.c
+++ b/afh_recv.c
@@ -237,6 +237,7 @@ out:
 	return ret;
 }
 
+/** See \ref recv_init(). */
 const struct receiver lsg_recv_cmd_com_afh_user_data = {
 	.init = afh_init,
 	.open = afh_recv_open,
diff --git a/dccp_recv.c b/dccp_recv.c
index 318969af..3385d66c 100644
--- a/dccp_recv.c
+++ b/dccp_recv.c
@@ -155,6 +155,7 @@ out:
 	return ret;
 }
 
+/** See \ref recv_init(). */
 const struct receiver lsg_recv_cmd_com_dccp_user_data = {
 	.open = dccp_recv_open,
 	.close = dccp_recv_close,
diff --git a/http_recv.c b/http_recv.c
index d49cf2a8..a5bbed63 100644
--- a/http_recv.c
+++ b/http_recv.c
@@ -167,6 +167,7 @@ static int http_recv_open(struct receiver_node *rn)
 	return 1;
 }
 
+/** See \ref recv_init(). */
 const struct receiver lsg_recv_cmd_com_http_user_data = {
 	.open = http_recv_open,
 	.close = http_recv_close,
diff --git a/recv_common.c b/recv_common.c
index d48b3476..1ad84438 100644
--- a/recv_common.c
+++ b/recv_common.c
@@ -21,6 +21,12 @@
 
 /**
  * Call the init function of each paraslash receiver.
+ *
+ * Receivers employ the user_data feature of the lopsub library: Each receiver
+ * of the recv_cmd suite defines a struct receiver as its user data.
+ * recv_init() obtains a pointer to this structure by calling lls_user_data().
+ * If the receiver has an init function (i.e., if ->init is not NULL), ->init()
+ * is called to initialize the receiver.
  */
 void recv_init(void)
 {
diff --git a/udp_recv.c b/udp_recv.c
index a5dfc879..4620d61a 100644
--- a/udp_recv.c
+++ b/udp_recv.c
@@ -190,6 +190,7 @@ err:
 	return ret;
 }
 
+/** See \ref recv_init(). */
 const struct receiver lsg_recv_cmd_com_udp_user_data = {
 	.open = udp_recv_open,
 	.close = udp_recv_close,
-- 
2.39.5