r11826@catbus: nickm | 2007-02-16 14:58:38 -0500

 Resolve 56 DOCDOC comments.


svn:r9594

1 files changed, 54 insertions, 21 deletions

diff --git a/src/or/control.c b/src/or/control.c
index d3f07a9107..b3ae38cc36 100644
--- a/src/or/control.c
+++ b/src/or/control.c
@@ -11,10 +11,13 @@ const char control_c_id[] =
 
 #include "or.h"
 
-/** DOCDOC */
+/** Yield true iff <b>s</b> is the state of a control_connection_t that has
+ * finished authentication and is accepting commands. */
 #define STATE_IS_OPEN(s) ((s) == CONTROL_CONN_STATE_OPEN_V0 ||          \
                           (s) == CONTROL_CONN_STATE_OPEN_V1)
-/** DOCDOC */
+/** Yield trie iff <b>s</b> is the state of a control_connection_t that is
+ * speaking the V0 protocol.
+ */
 #define STATE_IS_V0(s) ((s) == CONTROL_CONN_STATE_NEEDAUTH_V0 ||        \
                         (s) == CONTROL_CONN_STATE_OPEN_V0)
 
@@ -712,7 +715,17 @@ send_control1_event_string(uint16_t event, event_format_t which,
   }
 }
 
-/** DOCDOC */
+/** Helper for send_control1_event and send_control1_event_extended:
+ * Send an event to all v1 controllers that are listening for code
+ * <b>event</b>.  The event's body is created by the printf-style format in
+ * <b>format</b>, and other arguments as provided.
+ *
+ * If <b>extended</b> is true, and the format contains a single '@' character,
+ * it will be replaced with a space and all text after that character will be
+ * sent only to controllers that have enabled extended events.
+ *
+ * Currently the length of the message is limited to 1024 (including the
+ * ending \n\r\0. */
 static void
 send_control1_event_impl(uint16_t event, event_format_t which, int extended,
                          const char *format, va_list ap)
@@ -1482,7 +1495,8 @@ handle_control_mapaddress(control_connection_t *conn, uint32_t len,
   return 0;
 }
 
-/** DOCDOC */
+/** Implementation helper for GETINFO: knows the answers for various
+ * trivial-to-implement questions. */
 static int
 getinfo_helper_misc(control_connection_t *conn, const char *question,
                     char **answer)
@@ -1497,7 +1511,8 @@ getinfo_helper_misc(control_connection_t *conn, const char *question,
   } else if (!strcmp(question, "events/names")) {
     *answer = tor_strdup("CIRC STREAM ORCONN BW DEBUG INFO NOTICE WARN ERR "
                          "NEWDESC ADDRMAP AUTHDIR_NEWDESCS DESCCHANGED "
-                         "NS STATUS_GENERAL STATUS_CLIENT STATUS_SERVER");
+                         "NS STATUS_GENERAL STATUS_CLIENT STATUS_SERVER "
+                         "GUARD STREAM_BW");
   } else if (!strcmp(question, "features/names")) {
     *answer = tor_strdup("VERBOSE_NAMES EXTENDED_EVENTS");
   } else if (!strcmp(question, "address")) {
@@ -1520,7 +1535,8 @@ getinfo_helper_misc(control_connection_t *conn, const char *question,
   return 0;
 }
 
-/** DOCDOC */
+/** Implementatino helper for GETINFO: knows the answers for questions about
+ * directory information. */
 static int
 getinfo_helper_dir(control_connection_t *control_conn,
                    const char *question, char **answer)
@@ -1628,7 +1644,8 @@ getinfo_helper_dir(control_connection_t *control_conn,
   return 0;
 }
 
-/** DOCDOC */
+/** Implementation helper for GETINFO: knows how to generate summaries of the
+ * current states of things we send events about. */
 static int
 getinfo_helper_events(control_connection_t *control_conn,
                       const char *question, char **answer)
@@ -1774,23 +1791,29 @@ getinfo_helper_events(control_connection_t *control_conn,
   return 0;
 }
 
-/** DOCDOC */
+/** Callback function for GETINFO: on a given control connection, try to
+ * answer the question <b>q</b> and store the newly-allocated answer in
+ * *<b>a</b>.  If there's no answer, or an error occurs, just don't set
+ * <b>a</b>.  Return 0.
+ */
 typedef int (*getinfo_helper_t)(control_connection_t *,
                                 const char *q, char **a);
 
-/** DOCDOC */
+/** A single item for the GETINFO question-to-answer-function table. */
 typedef struct getinfo_item_t {
-  const char *varname;
-  getinfo_helper_t fn;
-  const char *desc;
-  int is_prefix;
+  const char *varname; /**< The value (or prefix) of the question */
+  getinfo_helper_t fn; /**< The function that knows the answer: NULL if
+                        * this entry is documentation-only. */
+  const char *desc; /**< Description of the variable. */
+  int is_prefix; /** Must varname match exactly, or must it be a prefix? */
 } getinfo_item_t;
 
 #define ITEM(name, fn, desc) { name, getinfo_helper_##fn, desc, 0 }
 #define PREFIX(name, fn, desc) { name, getinfo_helper_##fn, desc, 1 }
 #define DOC(name, desc) { name, NULL, desc, 0 }
 
-/** DOCDOC */
+/** Table mapping questions accepted by GETINFO to the functions that know how
+ * to answer them. */
 static const getinfo_item_t getinfo_items[] = {
   ITEM("version", misc, "The current version of Tor."),
   ITEM("config-file", misc, "Current location of the \"torrc\" file."),
@@ -1851,6 +1874,7 @@ static const getinfo_item_t getinfo_items[] = {
   { NULL, NULL, NULL, 0 }
 };
 
+/** Allocate and return a list of recognized GETINFO options. */
 static char *
 list_getinfo_options(void)
 {
@@ -2588,7 +2612,8 @@ handle_control_closecircuit(control_connection_t *conn, uint32_t len,
   return 0;
 }
 
-/** DOCDOC */
+/** Called when we get a USEFEATURE command: parse the feature list, and
+ * set up the control_connection's options properly. */
 static int
 handle_control_usefeature(control_connection_t *conn,
                           uint32_t len,
@@ -3028,7 +3053,8 @@ connection_control_process_inbuf(control_connection_t *conn)
     return connection_control_process_inbuf_v1(conn);
 }
 
-/** DOCDOC */
+/** Convert a numeric reason for destroying a circuit into a string for a
+ * CIRCUIT event. */
 static const char *
 circuit_end_reason_to_string(int reason)
 {
@@ -3298,7 +3324,9 @@ control_event_stream_status(edge_connection_t *conn, stream_status_event_t tp,
   return 0;
 }
 
-/** DOCDOC */
+/** Figure out best name for the target router of an OR connection, and write
+ * it into the <b>len</b>-character buffer <b>name</b>.  Use verbose names if
+ * <b>long_names</b> is set. */
 static void
 orconn_target_get_name(int long_names,
                        char *name, size_t len, or_connection_t *conn)
@@ -3325,7 +3353,7 @@ orconn_target_get_name(int long_names,
   }
 }
 
-/** DOCDOC */
+/** Convert a TOR_TLS error code into an END_OR_CONN_* reason. */
 int
 control_tls_error_to_reason(int e)
 {
@@ -3350,7 +3378,8 @@ control_tls_error_to_reason(int e)
   }
 }
 
-/** DOCDOC */
+/** Convert the reason for ending an OR connection <b>r</b> into the format
+ * used in ORCONN events. Return NULL if the reason is unrecognized. */
 static const char *
 or_conn_end_reason_to_string(int r)
 {
@@ -3379,9 +3408,13 @@ or_conn_end_reason_to_string(int r)
   }
 }
 
-/** DOCDOC */
+/** Called when the status of an OR connection <b>conn</b> changes: tell any
+ * interested control connections. <b>tp</b> is the new status for the
+ * connection.  If <b>conn</b> has just closed or failed, then <b>reason</b>
+ * may be the reason why.
+ */
 int
-control_event_or_conn_status(or_connection_t *conn,or_conn_status_event_t tp,
+control_event_or_conn_status(or_connection_t *conn, or_conn_status_event_t tp,
         int reason)
 {
   char buf[HEX_DIGEST_LEN+3]; /* status, dollar, identity, NUL */