[or-cvs] [tor/master 25/38] Documentation for a few bufferevent functions.

[nickm@xxxxxxxxxxxxxx]

Author: Nick Mathewson <nickm@xxxxxxxxxxxxxx>
Date: Sun, 23 Aug 2009 11:39:34 -0400
Subject: Documentation for a few bufferevent functions.
Commit: c74a4ab515990701800755b88c097f8239cc3811

---
 src/common/tortls.c |   26 ++++++++++++++++++++++++--
 src/or/connection.c |   14 ++++++++++----
 2 files changed, 34 insertions(+), 6 deletions(-)

diff --git a/src/common/tortls.c b/src/common/tortls.c
index 47f6adb..06533ca 100644
--- a/src/common/tortls.c
+++ b/src/common/tortls.c
@@ -1205,6 +1205,14 @@ tor_tls_handshake(tor_tls_t *tls)
   return r;
 }
 
+/** Perform the final part of the intial TLS handshake on <b>tls</b>.  This
+ * should be called for the first handshake only: it determiens whether the v1
+ * or the v2 handshake was used, and adjusts things for the renegotiation
+ * handshake as appropriate.
+ *
+ * tor_tls_handshake() calls this on its own; you only need to call this if
+ * bufferevent is doing the handshake for you.
+ */
 int
 tor_tls_finish_handshake(tor_tls_t *tls)
 {
@@ -1258,7 +1266,8 @@ tor_tls_finish_handshake(tor_tls_t *tls)
 }
 
 #ifdef USE_BUFFEREVENTS
-/** DOCDOC */
+/** Put <b>tls</b>, which must be a client connection, into renegotiation
+ * mode. */
 int
 tor_tls_start_renegotiating(tor_tls_t *tls)
 {
@@ -1660,7 +1669,20 @@ tor_tls_get_buffer_sizes(tor_tls_t *tls,
 }
 
 #ifdef USE_BUFFEREVENTS
-/** DOCDOC may free bufev_in */
+/** Construct and return an TLS-encrypting bufferevent to send data over
+ * <b>socket</b>, which must match the socket of the underlying bufferevent
+ * <b>bufev_in</b>.  The TLS object <b>tls</b> is used for encryption.
+ *
+ * This function will either create a filtering bufferevent that wraps around
+ * <b>bufev_in</b>, or it will free bufev_in and return a new bufferevent that
+ * uses the <b>tls</b> to talk to the network directly.  Do not use
+ * <b>bufev_in</b> after calling this function.
+ *
+ * The connection will start out doing a server handshake if <b>receiving</b>
+ * is strue, and a client handshake otherwise.
+ *
+ * Returns NULL on failure.
+ */
 struct bufferevent *
 tor_tls_init_bufferevent(tor_tls_t *tls, struct bufferevent *bufev_in,
                          evutil_socket_t socket, int receiving)
diff --git a/src/or/connection.c b/src/or/connection.c
index b397630..43f6c47 100644
--- a/src/or/connection.c
+++ b/src/or/connection.c
@@ -2633,6 +2633,9 @@ connection_read_to_buf(connection_t *conn, int *max_to_read, int *socket_error)
 #ifdef USE_BUFFEREVENTS
 /* XXXX These generic versions could be simplified by making them
    type-specific */
+
+/** Callback: Invoked whenever bytes are added to or drained from an input
+ * evbuffer.  Used to track the number of bytes read. */
 static void
 evbuffer_inbuf_callback(struct evbuffer *buf,
                         const struct evbuffer_cb_info *info, void *arg)
@@ -2653,7 +2656,8 @@ evbuffer_inbuf_callback(struct evbuffer *buf,
   }
 }
 
-/** DOCDOC */
+/** Callback: Invoked whenever bytes are added to or drained from an output
+ * evbuffer.  Used to track the number of bytes written. */
 static void
 evbuffer_outbuf_callback(struct evbuffer *buf,
                          const struct evbuffer_cb_info *info, void *arg)
@@ -2673,7 +2677,7 @@ evbuffer_outbuf_callback(struct evbuffer *buf,
   }
 }
 
-/** DOCDOC */
+/** Callback: invoked whenever a bufferevent has read data. */
 void
 connection_handle_read_cb(struct bufferevent *bufev, void *arg)
 {
@@ -2684,7 +2688,7 @@ connection_handle_read_cb(struct bufferevent *bufev, void *arg)
       connection_mark_for_close(conn);
 }
 
-/** DOCDOC */
+/** Callback: invoked whenever a bufferevent has written data. */
 void
 connection_handle_write_cb(struct bufferevent *bufev, void *arg)
 {
@@ -2708,7 +2712,8 @@ connection_handle_write_cb(struct bufferevent *bufev, void *arg)
   }
 }
 
-/** DOCDOC */
+/** Callback: invoked whenever a bufferevent has had an event (like a
+ * connection, or an eof, or an error) occur. */
 void
 connection_handle_event_cb(struct bufferevent *bufev, short event, void *arg)
 {
@@ -2746,6 +2751,7 @@ connection_handle_event_cb(struct bufferevent *bufev, short event, void *arg)
   }
 }
 
+/** Set up the generic callbacks for the bufferevent on <b>conn</b>. */
 void
 connection_configure_bufferevent_callbacks(connection_t *conn)
 {
-- 
1.7.1