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.

diff --git a/afh_recv.c b/afh_recv.c
index 9d6effe1e25f6cc40ad0ccf5386ee997bce94862..d2d8b52bb86d18d70d356fdcb43044b064590de6 100644 (file)
--- 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 318969afe3c123c611638e3954c4556d29c82e14..3385d66c42d113b382d18eb3fc8c4a7c60b44f74 100644 (file)
--- 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 d49cf2a853b3043edc09e5e419632b7cce2da6be..a5bbed634c2d6599fc8e7498d2f2bd7d32dd115a 100644 (file)
--- 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 d48b3476f883bd9ca830aa97bc92dc0112433341..1ad84438026ce8f724ddf8d1fba8547a96276fb6 100644 (file)
--- 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 a5dfc8794f6bab030a2c29c7d48e42961c9c9e02..4620d61a4603e46561881a3b7c0976a09c7788d9 100644 (file)
--- 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,