From: Oto Šťáva <oto.stava@nic.cz>
Date: Tue, 4 Jun 2024 08:49:49 +0000 (+0200)
Subject: daemon/session2.h: clarify `struct session2` docs
X-Git-Tag: v6.0.8~14^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4d57c6381e88bc8ba6959df14d21cca28b84c247;p=thirdparty%2Fknot-resolver.git

daemon/session2.h: clarify `struct session2` docs

As pointed out by @lukas.ondracek, the wording could be confusing when
mentioning *bottommost* and *topmost* layers. The original wording was
meant to reference the way the arrays in `daemon/session2.c` are laid
out, but never explicitly mentioned that, so one could be implicitly
think it was in reference to the widely known ISO/OSI or TCP/IP models,
which could be interpreted incorrectly (the layers are traditionally
laid out the other way around there).
---

diff --git a/daemon/session2.h b/daemon/session2.h
index 931dd6ee0..dc602cca0 100644
--- a/daemon/session2.h
+++ b/daemon/session2.h
@@ -755,15 +755,16 @@ enum session2_transport_type {
  * A session processes data in two directions:
  *
  *  - `_UNWRAP` deals with raw data received from the session's transport. It
- *    strips the ceremony of individual protocols from the buffers. The last
- *    (bottommost) layer is generally responsible for submitting the unwrapped
- *    data to be processed by an internal system, e.g. to be resolved as a DNS
- *    query.
+ *  strips the ceremony of individual protocols from the buffers, retaining any
+ *  required metadata in an iteration context (`struct protolayer_iter_ctx`).
+ *  The last layer (as defined by a `protolayer_grp_*` array in `session2.c`) in
+ *  a sequence is generally responsible for submitting the unwrapped data to be
+ *  processed by an internal system, e.g. to be resolved as a DNS query.
  *
  *  - `_WRAP` deals with data generated by an internal system. It adds the
- *    required protocol ceremony to it (e.g. encryption). The first (topmost)
- *    layer is responsible for preparing the data to be sent through the
- *    session's transport. */
+ *  required protocol ceremony to it (e.g. encryption). The first layer (as
+ *  defined by a `protolayer_grp_*` array in `session2.c`) is responsible for
+ *  preparing the data to be sent through the session's transport. */
 struct session2 {
 	/** Data for sending data out in the `wrap` direction and receiving new
 	 * data in the `unwrap` direction. */