r14108@tombo: nickm | 2008-02-10 20:09:10 -0500

 add some documentation


svn:r13462

src/or/command.c

@@ -447,8 +447,8 @@ command_process_destroy_cell(cell_t *cell, or_connection_t *conn)
 
 /** Process a 'versions' cell.  The current link protocol version must be 0
  * to indicate that no version has yet been negotiated.  We compare the versions
- * cell to the list of versions we support, and pick the highest version we
- * have in common.
+ * cell to the list of versions we support, pick the highest version we
+ * have in common, and continue the negotiation from there.
  */
 static void
 command_process_versions_cell(var_cell_t *cell, or_connection_t *conn)
@@ -477,6 +477,7 @@ command_process_versions_cell(var_cell_t *cell, or_connection_t *conn)
     connection_mark_for_close(TO_CONN(conn));
     return;
   } else if (highest_supported_version == 1) {
+    /*XXXXX020 consider this carefully. */
     log_fn(LOG_PROTOCOL_WARN, LD_OR,
            "Used version negotiation protocol to negotiate a v1 connection. "
            "That's crazily non-compliant. Closing connection.");
@@ -500,7 +501,8 @@ command_process_versions_cell(var_cell_t *cell, or_connection_t *conn)
   }
 }
 
-/** Process a 'netinfo' cell. DOCDOC say more. */
+/** Process a 'netinfo' cell: read and act on its contents, and set the
+ * connection state to "open". */
 static void
 command_process_netinfo_cell(cell_t *cell, or_connection_t *conn)
 {

src/or/connection_or.c

@@ -846,7 +846,8 @@ connection_tls_finish_handshake(or_connection_t *conn)
   }
 }
 
-/** DOCDOC */
+/** Allocate a new connection handshake state for the connection
+ * <b>conn</b>.  Return 0 on success, -1 on failure. */
 static int
 connection_init_or_handshake_state(or_connection_t *conn, int started_here)
 {
@@ -856,7 +857,7 @@ connection_init_or_handshake_state(or_connection_t *conn, int started_here)
   return 0;
 }
 
-/** DOCDOC */
+/** Free all storage held by <b>state</b>. */
 void
 or_handshake_state_free(or_handshake_state_t *state)
 {
@@ -865,7 +866,9 @@ or_handshake_state_free(or_handshake_state_t *state)
   tor_free(state);
 }
 
-/**DOCDOC*/
+/** Set <b>conn</b>'s state to OR_CONN_STATE_OPEN, and tell other subsystems
+ * as appropriate.  Called when we are done with all TLS and OR handshaking.
+ */
 int
 connection_or_set_state_open(or_connection_t *conn)
 {

src/or/or.h

@@ -887,12 +887,17 @@ typedef struct connection_t {
 
 } connection_t;
 
-/** DOCDOC */
+/** Stores flags and information related to the portion of a v2 Tor OR
+ * connection handshake that happens after the TLS handshake is finished.
+ */
 typedef struct or_handshake_state_t {
+  /** When was the VERSIONS cell sent on this connection?  Used to get
+   * an estimate of the skew in the returning NETINFO reply. */
   time_t sent_versions_at;
+  /** True iff we originated this connection */
   unsigned int started_here : 1;
+  /** True iff we have received and processed a VERSIONS cell. */
   unsigned int received_versions : 1;
-
 } or_handshake_state_t;
 
 /** Subtype of connection_t for an "OR connection" -- that is, one that speaks
@@ -917,14 +922,15 @@ typedef struct or_connection_t {
                                   * connection, which half of the space should
                                   * we use? */
   unsigned int is_canonical:1; /**< DOCDOC */
-  unsigned int have_renegotiated:1; /**DOCDOC */
+  unsigned int have_renegotiated:1; /**< DOCDOC */
   uint8_t link_proto; /**< What protocol version are we using? 0 for
                        * "none negotiated yet." */
   uint16_t next_circ_id; /**< Which circ_id do we try to use next on
                           * this connection?  This is always in the
                           * range 0..1<<15-1. */
 
-  or_handshake_state_t *handshake_state;/**< DOCDOC */
+  or_handshake_state_t *handshake_state; /**< If we are setting this connection
+                                          * up, state information to do so. */
   time_t timestamp_lastempty; /**< When was the outbuf last completely empty?*/
   time_t timestamp_last_added_nonpadding; /** When did we last add a
                                            * non-padding cell to the outbuf? */