Improve documentation for our TO_*_CONN() cast functions.

Preliminary work for #40046.

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)
 {

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)
 {

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)
 {

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)
 {

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)
 {