daemon/session2: documentation edits

diff --git a/daemon/session2.c b/daemon/session2.c
index 2f112b189d38d2e26299c31991eb153a7fba0333..278e74895def768be22983392eaf01e97d59d7bf 100644 (file)
--- a/daemon/session2.c
+++ b/daemon/session2.c
@@ -32,6 +32,7 @@ static uint32_t next_log_id = 1;
 
 struct protolayer_globals protolayer_globals[PROTOLAYER_PROTOCOL_COUNT] = {{0}};
 
+
 static const enum protolayer_protocol protolayer_grp_doudp[] = {
        PROTOLAYER_PROTOCOL_UDP,
        PROTOLAYER_PROTOCOL_DNS_DGRAM,
@@ -59,6 +60,20 @@ static const enum protolayer_protocol protolayer_grp_doh[] = {
        PROTOLAYER_PROTOCOL_NULL
 };
 
+/** Sequences of layers, mapped by `enum protolayer_grp`.
+ *
+ * To define a new group, add a new entry in the `PROTOLAYER_GRP_MAP` macro and
+ * create a new static `protolayer_grp_*` array above, similarly to the already
+ * existing ones. Each array must end with `PROTOLAYER_GRP_NULL`, to indicate
+ * the end of the list of protocol layers. The array name's suffix must be the
+ * one defined as *Variable name* (2nd parameter) in the `PROTOLAYER_GRP_MAP`
+ * macro. */
+static const enum protolayer_protocol *protolayer_grps[PROTOLAYER_GRP_COUNT] = {
+#define XX(cid, vid, name) [PROTOLAYER_GRP_ ## cid] = protolayer_grp_ ## vid,
+       PROTOLAYER_GRP_MAP(XX)
+#undef XX
+};
+
 
 const char *protolayer_protocol_name(enum protolayer_protocol p)
 {
@@ -74,20 +89,6 @@ const char *protolayer_protocol_name(enum protolayer_protocol p)
        }
 }
 
-/** Sequences of layers, mapped by `enum protolayer_grp`.
- *
- * To define a new group, add a new entry in the `PROTOLAYER_GRP_MAP` macro and
- * create a new static `protolayer_grp_*` array above, similarly to the already
- * existing ones. Each array must end with `PROTOLAYER_GRP_NULL`, to indicate
- * the end of the list of protocol layers. The array name's suffix must be the
- * one defined as *Variable name* (2nd parameter) in the `PROTOLAYER_GRP_MAP`
- * macro. */
-static const enum protolayer_protocol *protolayer_grps[PROTOLAYER_GRP_COUNT] = {
-#define XX(cid, vid, name) [PROTOLAYER_GRP_ ## cid] = protolayer_grp_ ## vid,
-       PROTOLAYER_GRP_MAP(XX)
-#undef XX
-};
-
 const char *protolayer_grp_name(enum protolayer_grp g)
 {
        switch (g) {

diff --git a/daemon/session2.h b/daemon/session2.h
index 401d5c58cc9bc67088b1ef60db55a9c696d1c137..4f07cb49e88a6dd465e5ec3098b6e9716e2ce75b 100644 (file)
--- a/daemon/session2.h
+++ b/daemon/session2.h
@@ -88,7 +88,8 @@ struct comm_info {
        const struct sockaddr *dst_addr;
 
        /** Data parsed from a PROXY header. May be `NULL` if the communication
-        * did not come through a proxy, or if the PROXYv2 protocol was not used. */
+        * did not come through a proxy, or if the PROXYv2 protocol was not
+        * used. */
        const struct proxy_result *proxy;
 
        /** Pointer to protolayer-specific data, e.g. a key to decide, which
@@ -184,7 +185,6 @@ static inline size_t wire_buf_free_space_length(const struct wire_buf *wb)
 }
 
 
-
 /** Protocol layer types map - an enumeration of individual protocol layer
  * implementations
  *
@@ -244,9 +244,10 @@ const char *protolayer_protocol_name(enum protolayer_protocol p);
  * For defining new groups, see the docs of `protolayer_grps[]` in
  * `daemon/session2.h`.
  *
- * Parameters are:
- *   1. Constant name (for e.g. PROTOLAYER_GRP_* enum values)
- *   2. Variable name (for e.g. protolayer_grp_* arrays - in `session2.c`)
+ * Parameters for XX are:
+ *   1. Constant name (for e.g. PROTOLAYER_GRP_* enum value identifiers)
+ *   2. Variable name (for e.g. protolayer_grp_* array identifiers - defined in
+ *      `session2.c`)
  *   3. Human-readable name for logging */
 #define PROTOLAYER_GRP_MAP(XX) \
        XX(DOUDP, doudp, "DNS UDP") \
@@ -289,9 +290,11 @@ enum protolayer_direction {
        PROTOLAYER_WRAP,
 };
 
+/** Returned by a successful call to `session2_wrap()` or `session2_unwrap()`
+ * functions. */
 enum protolayer_ret {
        /** Returned when a protolayer context iteration has finished
-        * processing, i.e. with _BREAK. */
+        * processing, i.e. with `protolayer_break()`. */
        PROTOLAYER_RET_NORMAL = 0,
 
        /** Returned when a protolayer context iteration is waiting for an
@@ -299,10 +302,6 @@ enum protolayer_ret {
         * passed to `protolayer_finished_cb`, only returned by
         * `session2_unwrap` or `session2_wrap`. */
        PROTOLAYER_RET_ASYNC,
-
-       /** Returned when a protolayer context iteration has ended on a layer
-        * that needs more data from another buffer. */
-       PROTOLAYER_RET_WAITING,
 };
 
 /** Called when a payload iteration (started by `session2_unwrap` or