[or-cvs] r10992: More documentation (in tor/trunk: . doc/spec src/or)

Mon Jul 30 17:46:14 UTC 2007

Author: nickm
Date: 2007-07-30 13:46:14 -0400 (Mon, 30 Jul 2007)
New Revision: 10992

Modified:
   tor/trunk/
   tor/trunk/doc/spec/control-spec.txt
   tor/trunk/src/or/connection_edge.c
   tor/trunk/src/or/control.c
   tor/trunk/src/or/routerlist.c
   tor/trunk/src/or/routerparse.c
Log:
 r14016 at catbus:  nickm | 2007-07-30 13:45:55 -0400
 More documentation



Property changes on: tor/trunk
___________________________________________________________________
 svk:merge ticket from /tor/trunk [r14016] on 8246c3cf-6607-4228-993b-4d95d33730f1

Modified: tor/trunk/doc/spec/control-spec.txt
===================================================================

--- tor/trunk/doc/spec/control-spec.txt	2007-07-30 17:46:12 UTC (rev 10991)
+++ tor/trunk/doc/spec/control-spec.txt	2007-07-30 17:46:14 UTC (rev 10992)
@@ -505,6 +505,12 @@
       states. See Section 4.1.10 for explanations. (Only a few of the
       status events are available as getinfo's currently. Let us know if
       you want more exposed.)
+    "status/version/recommended" -- List of currently recommended versions
+    "status/version/current" -- Status of the current version. One of:
+        new, old, unrecommended, recommended, new in series, obsolete.
+    "status/version/num-versioning" -- Number of versioning authorities
+    "status/version/num-concurring" -- Number of versioning authorities
+        agreeing on the status of the current version
 
   Examples:
      C: GETINFO version desc/name/moria1

Modified: tor/trunk/src/or/connection_edge.c
===================================================================
--- tor/trunk/src/or/connection_edge.c	2007-07-30 17:46:12 UTC (rev 10991)
+++ tor/trunk/src/or/connection_edge.c	2007-07-30 17:46:14 UTC (rev 10992)
@@ -654,8 +654,9 @@
 /** Look at address, and rewrite it until it doesn't want any
  * more rewrites; but don't get into an infinite loop.
  * Don't write more than maxlen chars into address.  Return true if the
- * address changed; false otherwise.
- * DOCDOC expires_out
+ * address changed; false otherwise.  Set *<b>expires_out</b> to the
+ * expiry time of the result, or to <b>time_max</b> if the result does
+ * not expire.
  */
 int
 addressmap_rewrite(char *address, size_t maxlen, time_t *expires_out)
@@ -693,8 +694,9 @@
 
 /** If we have a cached reverse DNS entry for the address stored in the
  * <b>maxlen</b>-byte buffer <b>address</b> (typically, a dotted quad) then
- * rewrite to the cached value and return 1.  Otherwise return 0.
- * DOCDOC expires_out */
+ * rewrite to the cached value and return 1.  Otherwise return 0.  Set
+ * *<b>expires_out</b> to the expiry time of the result, or to <b>time_max</b>
+ * if the result does not expire. */
 static int
 addressmap_rewrite_reverse(char *address, size_t maxlen, time_t *expires_out)
 {

Modified: tor/trunk/src/or/control.c
===================================================================
--- tor/trunk/src/or/control.c	2007-07-30 17:46:12 UTC (rev 10991)
+++ tor/trunk/src/or/control.c	2007-07-30 17:46:14 UTC (rev 10992)
@@ -1613,7 +1613,6 @@
   DOC("status/enough-dir-info",
       "Whether we have enough up-to-date directory information to build "
       "circuits."),
-  /* DOCDOC specify status/version/ */
   DOC("status/version/recommended", "List of currently recommended versions."),
   DOC("status/version/current", "Status of the current version."),
   DOC("status/version/num-versioning", "Number of versioning authorities."),

Modified: tor/trunk/src/or/routerlist.c
===================================================================
--- tor/trunk/src/or/routerlist.c	2007-07-30 17:46:12 UTC (rev 10991)
+++ tor/trunk/src/or/routerlist.c	2007-07-30 17:46:14 UTC (rev 10992)
@@ -65,7 +65,7 @@
  * about.  This list is kept sorted by published_on. */
 static smartlist_t *networkstatus_list = NULL;
 
-/** DOCDOC */
+/** Most recently received v3 consensus network status. */
 static networkstatus_vote_t *current_consensus = NULL;
 
 /** Global list of local_routerstatus_t for each router, known or unknown.
@@ -284,12 +284,13 @@
   trusted_dir_servers_certs_changed = 0;
 }
 
-/** DOCDOC */
+/** Remove all v3 authority certificates that have been superseded for more
+ * than 48 hours.  (If the most recent cert was published more than 48 hours
+ * ago, then we aren't going to get any consensuses signed with older
+ * keys.) */
 static void
 trusted_dirs_remove_old_certs(void)
 {
-  /* Any certificate that has been superseded for more than 48 hours is
-   * irrelevant. */
 #define OLD_CERT_LIFETIME (48*60*60)
   SMARTLIST_FOREACH(trusted_dir_servers, trusted_dir_server_t *, ds,
     {
@@ -313,7 +314,9 @@
   trusted_dirs_flush_certs_to_disk();
 }
 
-/** DOCDOC */
+/** Return the v3 authority certificate with signing key matching
+ * <b>sk_digest</b>, for the authority with identity digest <b>id_digest</b>.
+ * Return NULL if no such authority is known. */
 authority_cert_t *
 authority_cert_get_by_digests(const char *id_digest,
                               const char *sk_digest)
@@ -3816,14 +3819,16 @@
   return NULL;
 }
 
-/** DOCDOC */
+/** Return the most recent consensus that we have downloaded, or NULL if we
+ * don't have one. */
 networkstatus_vote_t *
 networkstatus_get_latest_consensus(void)
 {
   return current_consensus;
 }
 
-/** DOCDOC */
+/** Return the most recent consensus that we have downloaded, or NULL if it is
+ * no longer live. */
 networkstatus_vote_t *
 networkstatus_get_live_consensus(time_t now)
 {

Modified: tor/trunk/src/or/routerparse.c
===================================================================
--- tor/trunk/src/or/routerparse.c	2007-07-30 17:46:12 UTC (rev 10991)
+++ tor/trunk/src/or/routerparse.c	2007-07-30 17:46:14 UTC (rev 10992)
@@ -1787,7 +1787,9 @@
   return ns;
 }
 
-/** DOCDOC */
+/** Parse a v3 networkstatus vote (if <b>is_vote</b> is true) or a v3
+ * networkstatus consensus (if <b>is_vote</b> is false) from <b>s</b>, and
+ * return the result.  Return NULL on failure. */
 networkstatus_vote_t *
 networkstatus_parse_vote_from_string(const char *s, int is_vote)
 {
@@ -2103,7 +2105,8 @@
   return ns;
 }
 
-/** DOCDOC */
+/** Parse a detached v3 networkstatus signature document between <b>s</b> and
+ * <b>eos</b> and return the result.  Return -1 on failure. */
 ns_detached_signatures_t *
 networkstatus_parse_detached_signatures(const char *s, const char *eos)
 {

