[or-cvs] r13462: add some documentation (in tor/trunk: . src/or)

[nickm@xxxxxxxx]

Author: nickm
Date: 2008-02-10 20:09:24 -0500 (Sun, 10 Feb 2008)
New Revision: 13462

Modified:
   tor/trunk/
   tor/trunk/src/or/command.c
   tor/trunk/src/or/connection_or.c
   tor/trunk/src/or/or.h
Log:
 r14108@tombo:  nickm | 2008-02-10 20:09:10 -0500
 add some documentation



Property changes on: tor/trunk
___________________________________________________________________
 svk:merge ticket from /tor/trunk [r14108] on 49666b30-7950-49c5-bedf-9dc8f3168102

Modified: tor/trunk/src/or/command.c
===================================================================
--- tor/trunk/src/or/command.c	2008-02-10 19:18:29 UTC (rev 13461)
+++ tor/trunk/src/or/command.c	2008-02-11 01:09:24 UTC (rev 13462)
@@ -447,8 +447,8 @@
 
 /** 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 @@
     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 @@
   }
 }
 
-/** 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)
 {

Modified: tor/trunk/src/or/connection_or.c
===================================================================
--- tor/trunk/src/or/connection_or.c	2008-02-10 19:18:29 UTC (rev 13461)
+++ tor/trunk/src/or/connection_or.c	2008-02-11 01:09:24 UTC (rev 13462)
@@ -846,7 +846,8 @@
   }
 }
 
-/** 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 @@
   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 @@
   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)
 {

Modified: tor/trunk/src/or/or.h
===================================================================
--- tor/trunk/src/or/or.h	2008-02-10 19:18:29 UTC (rev 13461)
+++ tor/trunk/src/or/or.h	2008-02-11 01:09:24 UTC (rev 13462)
@@ -887,12 +887,17 @@
 
 } 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 @@
                                   * 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? */