move more docs into our code

svn:r4406

src/or/buffers.c

@@ -477,6 +477,23 @@ read_to_buf_tls_impl(tor_tls *tls, size_t at_most, buf_t *buf, char *next)
 }
 
 /** As read_to_buf, but reads from a TLS connection.
+ *
+ * Using TLS on OR connections complicates matters in two ways.
+ *
+ * First, a TLS stream has its own read buffer independent of the
+ * connection's read buffer.  (TLS needs to read an entire frame from
+ * the network before it can decrypt any data.  Thus, trying to read 1
+ * byte from TLS can require that several KB be read from the network
+ * and decrypted.  The extra data is stored in TLS's decrypt buffer.)
+ * Because the data hasn't been read by Tor (it's still inside the TLS),
+ * this means that sometimes a connection "has stuff to read" even when
+ * poll() didn't return POLLIN. The tor_tls_get_pending_bytes function is
+ * used in connection.c to detect TLS objects with non-empty internal
+ * buffers and read from them again.
+ *
+ * Second, the TLS stream's events do not correspond directly to network
+ * events: sometimes, before a TLS stream can read, the network must be
+ * ready to write -- or vice versa.
  */
 int read_to_buf_tls(tor_tls *tls, size_t at_most, buf_t *buf) {
   int r;

src/or/connection.c

@@ -1094,7 +1094,7 @@ static int connection_read_to_buf(connection_t *conn, int *max_to_read) {
     pending = tor_tls_get_pending_bytes(conn->tls);
     if (pending) {
       /* XXXX If we have any pending bytes, read them now.  This *can*
-       * take us over our read alotment, but really we shouldn't be
+       * take us over our read allotment, but really we shouldn't be
        * believing that SSL bytes are the same as TCP bytes anyway. */
       int r2 = read_to_buf_tls(conn->tls, pending, conn->inbuf);
       if (r2<0) {

src/or/or.h

@@ -182,21 +182,23 @@ typedef enum {
 #define _CONN_TYPE_MIN 3
 /** Type for sockets listening for OR connections. */
 #define CONN_TYPE_OR_LISTENER 3
-/** Type for OR-to-OR or OP-to-OR connections. */
+/** A bidirectional TLS connection transmitting a sequence of cells.
+ * May be from an OR to an OR, or from an OP to an OR. */
 #define CONN_TYPE_OR 4
-/** Type for connections from final OR to chosen destination. */
+/** A TCP connection from an onion router to a stream's destination. */
 #define CONN_TYPE_EXIT 5
 /** Type for sockets listening for SOCKS connections. */
 #define CONN_TYPE_AP_LISTENER 6
-/** Type for SOCKS connections to OP. */
+/** A SOCKS proxy connection from the user application to the onion
+ * proxy. */
 #define CONN_TYPE_AP 7
 /** Type for sockets listening for HTTP connections to the directory server. */
 #define CONN_TYPE_DIR_LISTENER 8
 /** Type for HTTP connections to the directory server. */
 #define CONN_TYPE_DIR 9
-/** Type for connections to local dnsworker processes. */
+/** Connection from the main process to a DNS worker process. */
 #define CONN_TYPE_DNSWORKER 10
-/** Type for connections to local cpuworker processes. */
+/** Connection from the main process to a CPU worker process. */
 #define CONN_TYPE_CPUWORKER 11
 /** Type for listenting for connections from user interface process */
 #define CONN_TYPE_CONTROL_LISTENER 12
@@ -538,8 +540,26 @@ typedef struct buf_t buf_t;
 typedef struct socks_request_t socks_request_t;
 
 #define CONNECTION_MAGIC 0x7C3C304Eu
+
 /** Description of a connection to another host or process, and associated
- * data. */
+ * data.
+ *
+ * A connection is named based on what it's connected to -- an "OR
+ * connection" has an onion router on the other end, an "OP connection"
+ * (nearly obsolete) has an onion proxy on the other end, an "exit
+ * connection" has a website or other server on the other end, and an
+ * "AP connection" has an application proxy (and thus a user) on the
+ * other end.
+ *
+ * Every connection has a type and a state.  Connections never change
+ * their type, but can go through many state changes in their lifetime.
+ *
+ * Every connection has two associated input and output buffers.
+ * Listeners don't use them.  For non-listener connections, incoming
+ * data is appended to conn->inbuf, and outgoing data is taken from
+ * conn->outbuf.  Connections differ primarily in the functions called
+ * to fill and drain these buffers.
+ */
 struct connection_t {
   uint32_t magic; /**< For memory debugging: must equal CONNECTION_MAGIC. */
 
@@ -816,7 +836,29 @@ typedef struct {
 } cpath_build_state_t;
 
 #define CIRCUIT_MAGIC 0x35315243u
-/** Struct for a path (circuit) through the onion routing network. */
+
+/**
+ * A circuit is a path over the onion routing
+ * network. Applications can connect to one end of the circuit, and can
+ * create exit connections at the other end of the circuit. AP and exit
+ * connections have only one circuit associated with them (and thus these
+ * connection types are closed when the circuit is closed), whereas
+ * OR connections multiplex many circuits at once, and stay standing even
+ * when there are no circuits running over them.
+ *
+ * A circuit_t structure fills two roles.  First, a circuit_t links two
+ * connections together: either an edge connection and an OR connection,
+ * or two OR connections.  (When joined to an OR connection, a circuit_t
+ * affects only cells sent to a particular circID on that connection.  When
+ * joined to an edge connection, a circuit_t affects all data.)
+
+ * Second, a circuit_t holds the cipher keys and state for sending data
+ * along a given circuit.  At the OP, it has a sequence of ciphers, each
+ * of which is shared with a single OR along the circuit.  Separate
+ * ciphers are used for data going "forward" (away from the OP) and
+ * "backward" (towards the OP).  At the OR, a circuit has only two stream
+ * ciphers: one for data going forward, and one for data going backward.
+ */
 struct circuit_t {
   uint32_t magic; /**< For memory debugging: must equal CIRCUIT_MAGIC. */