From beee9ca608e860ee71446e4923bf4f673eb012e3 Mon Sep 17 00:00:00 2001
From: teor <teor@torproject.org>
Date: Tue, 17 Mar 2020 17:41:26 +1000
Subject: [PATCH] relay: Improve the comments on onionskin_answer()

Part of 33633.
---
 src/feature/relay/circuitbuild_relay.c | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/src/feature/relay/circuitbuild_relay.c b/src/feature/relay/circuitbuild_relay.c
index 9da89953fb..85a05a8651 100644
--- a/src/feature/relay/circuitbuild_relay.c
+++ b/src/feature/relay/circuitbuild_relay.c
@@ -193,8 +193,24 @@ circuit_extend(struct cell_t *cell, struct circuit_t *circ)
   return 0;
 }
 
-/** Given a response payload and keys, initialize, then send a created
- * cell back.
+/** On a relay, accept a create cell, initialise a circuit, and send a
+ * created cell back.
+ *
+ * Given:
+ *   - a response payload consisting of:
+ *     - the <b>created_cell</b> and
+ *     - an optional <b>rend_circ_nonce</b>, and
+ *   - <b>keys</b> of length <b>keys_len</b>, which must be
+ *     CPATH_KEY_MATERIAL_LEN;
+ * then:
+ *   - initialize the circuit <b>circ</b>'s cryptographic material,
+ *   - set the circuit's state to open, and
+ *   - send a created cell back on that circuit.
+ *
+ * If we haven't found our ORPorts reachable yet, and the channel meets the
+ * necessary conditions, mark the relevant ORPorts as reachable.
+ *
+ * Returns -1 if cell or circuit initialisation fails.
  */
 int
 onionskin_answer(struct or_circuit_t *circ,