From b0d7b100886ef14a785f6ca1de968df9a884d0a7 Mon Sep 17 00:00:00 2001
From: Nick Mathewson <nickm@torproject.org>
Date: Thu, 16 Jul 2020 09:57:52 -0400
Subject: [PATCH] Improve documentation for our TO_*_CONN() cast functions.

Preliminary work for #40046.
---
 src/core/mainloop/connection.c    |  8 ++++++--
 src/core/or/connection_edge.c     | 20 ++++++++++++++++++--
 src/core/or/connection_or.c       |  7 +++++--
 src/feature/control/control.c     |  8 ++++++--
 src/feature/dircommon/directory.c |  8 ++++++--
 5 files changed, 41 insertions(+), 10 deletions(-)

diff --git a/src/core/mainloop/connection.c b/src/core/mainloop/connection.c
index 282d90c2b0..216aeb68d1 100644
--- a/src/core/mainloop/connection.c
+++ b/src/core/mainloop/connection.c
@@ -220,8 +220,12 @@ static smartlist_t *outgoing_addrs = NULL;
 
 /**************************************************************/
 
-/** Convert a connection_t* to an listener_connection_t*; assert if the cast
- * is invalid. */
+/**
+ * Cast a `connection_t *` to a `listener_connection_t *`.
+ *
+ * Exit with an assertion failure if the input is not a
+ * `listener_connection_t`.
+ **/
 listener_connection_t *
 TO_LISTENER_CONN(connection_t *c)
 {
diff --git a/src/core/or/connection_edge.c b/src/core/or/connection_edge.c
index 8eb9f8ba0f..30cfb18f0f 100644
--- a/src/core/or/connection_edge.c
+++ b/src/core/or/connection_edge.c
@@ -166,8 +166,12 @@ static int connection_exit_connect_dir(edge_connection_t *exitconn);
 static int consider_plaintext_ports(entry_connection_t *conn, uint16_t port);
 static int connection_ap_supports_optimistic_data(const entry_connection_t *);
 
-/** Convert a connection_t* to an edge_connection_t*; assert if the cast is
- * invalid. */
+/**
+ * Cast a `connection_t *` to an `edge_connection_t *`.
+ *
+ * Exit with an assertion failure if the input is not an
+ * `edge_connection_t`.
+ **/
 edge_connection_t *
 TO_EDGE_CONN(connection_t *c)
 {
@@ -176,6 +180,12 @@ TO_EDGE_CONN(connection_t *c)
   return DOWNCAST(edge_connection_t, c);
 }
 
+/**
+ * Cast a `connection_t *` to an `entry_connection_t *`.
+ *
+ * Exit with an assertion failure if the input is not an
+ * `entry_connection_t`.
+ **/
 entry_connection_t *
 TO_ENTRY_CONN(connection_t *c)
 {
@@ -183,6 +193,12 @@ TO_ENTRY_CONN(connection_t *c)
   return (entry_connection_t*) SUBTYPE_P(c, entry_connection_t, edge_.base_);
 }
 
+/**
+ * Cast an `edge_connection_t *` to an `entry_connection_t *`.
+ *
+ * Exit with an assertion failure if the input is not an
+ * `entry_connection_t`.
+ **/
 entry_connection_t *
 EDGE_TO_ENTRY_CONN(edge_connection_t *c)
 {
diff --git a/src/core/or/connection_or.c b/src/core/or/connection_or.c
index e62c28821a..e6dc62a475 100644
--- a/src/core/or/connection_or.c
+++ b/src/core/or/connection_or.c
@@ -99,8 +99,11 @@ static void connection_or_check_canonicity(or_connection_t *conn,
 
 /**************************************************************/
 
-/** Convert a connection_t* to an or_connection_t*; assert if the cast is
- * invalid. */
+/**
+ * Cast a `connection_t *` to an `or_connection_t *`.
+ *
+ * Exit with an assertion failure if the input is not an `or_connnection_t`.
+ **/
 or_connection_t *
 TO_OR_CONN(connection_t *c)
 {
diff --git a/src/feature/control/control.c b/src/feature/control/control.c
index ee1026359d..b5d4c31525 100644
--- a/src/feature/control/control.c
+++ b/src/feature/control/control.c
@@ -61,8 +61,12 @@
 #include <sys/stat.h>
 #endif
 
-/** Convert a connection_t* to an control_connection_t*; assert if the cast is
- * invalid. */
+/**
+ * Cast a `connection_t *` to a `control_connection_t *`.
+ *
+ * Exit with an assertion failure if the input is not a
+ * `control_connection_t`.
+ **/
 control_connection_t *
 TO_CONTROL_CONN(connection_t *c)
 {
diff --git a/src/feature/dircommon/directory.c b/src/feature/dircommon/directory.c
index 7f9f157a49..bb9264eaf9 100644
--- a/src/feature/dircommon/directory.c
+++ b/src/feature/dircommon/directory.c
@@ -79,8 +79,12 @@
  *   connection_finished_connecting() in connection.c
  */
 
-/** Convert a connection_t* to a dir_connection_t*; assert if the cast is
- * invalid. */
+/**
+ * Cast a `connection_t *` to a `dir_connection_t *`.
+ *
+ * Exit with an assertion failure if the input is not a
+ * `dir_connection_t`.
+ **/
 dir_connection_t *
 TO_DIR_CONN(connection_t *c)
 {