[or-cvs] [tor/master 15/15] Add some missing documentation for things added in nodes branch

[nickm at torproject.org]

Author: Nick Mathewson <nickm at torproject.org>
Date: Thu, 7 Oct 2010 17:10:06 -0400
Subject: Add some missing documentation for things added in nodes branch
Commit: c9dece14ae7d9c14c17df6685f7504c23eb65899

---
 src/or/or.h       |   11 +++++++++--
 src/or/policies.c |   12 ++++++++----
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/src/or/or.h b/src/or/or.h
index c8616be..96d0d79 100644
--- a/src/or/or.h
+++ b/src/or/or.h
@@ -1648,15 +1648,22 @@ typedef struct routerstatus_t {
 
 } routerstatus_t;
 
-/** DOCDOC */
+/** A single entry in a parsed policy summary, describing a range of ports. */
 typedef struct short_policy_entry_t {
   uint16_t min_port, max_port;
 } short_policy_entry_t;
 
-/** DOCDOC */
+/** A short_poliy_t is the parsed version of a policy summary. */
 typedef struct short_policy_t {
+  /** True if the members of 'entries' are port ranges to accept; false if
+   * they are port ranges to reject */
   unsigned int is_accept : 1;
+  /** The actual number of values in 'entries'. */
   unsigned int n_entries : 31;
+  /** An array of (probably more than 1!) short_policy_entry_t values,
+   * each descriping a range of ports that this policy accepts or rejects
+   * (depending on the value of is_accept).
+   */
   short_policy_entry_t entries[1];
 } short_policy_t;
 
diff --git a/src/or/policies.c b/src/or/policies.c
index a5b71c9..2ae66df 100644
--- a/src/or/policies.c
+++ b/src/or/policies.c
@@ -1315,7 +1315,8 @@ policy_summarize(smartlist_t *policy)
   return result;
 }
 
-/** DOCDOC */
+/** Convert a summarized policy string into a short_policy_t.  Return NULL
+ * if the string is not well-formed. */
 short_policy_t *
 parse_short_policy(const char *summary)
 {
@@ -1408,14 +1409,17 @@ parse_short_policy(const char *summary)
   return result;
 }
 
-/** DOCDOC */
+/** Release all storage held in <b>policy</b>. */
 void
 short_policy_free(short_policy_t *policy)
 {
   tor_free(policy);
 }
 
-/** DOCDOC */
+/** See whether the <b>addr</b>:<b>port</b> address is likely to be accepted
+ * or rejected by the summarized policy <b>policy</b>.  Return values are as
+ * for compare_tor_addr_to_addr_policy.  Unlike the regular addr_policy
+ * functions, requires the <b>port</b> be specified. */
 addr_policy_result_t
 compare_tor_addr_to_short_policy(const tor_addr_t *addr, uint16_t port,
                                  const short_policy_t *policy)
@@ -1452,7 +1456,7 @@ compare_tor_addr_to_short_policy(const tor_addr_t *addr, uint16_t port,
     return ADDR_POLICY_REJECTED;
 }
 
-/* DOCDOC */
+/** Return true iff <b>policy</b> seems reject all ports */
 int
 short_policy_is_reject_star(const short_policy_t *policy)
 {
-- 
1.7.1