[tor-commits] [tor/master] versions: Improve the protover summary comments

[nickm at torproject.org]

commit 277baf676be4b869e43e7db8aa1a18930506e622
Author: teor <teor at riseup.net>
Date:   Fri May 15 23:34:00 2020 +1000

    versions: Improve the protover summary comments
    
    Part of 33222.
---
 src/core/or/versions.c | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/src/core/or/versions.c b/src/core/or/versions.c
index 410a009ba..11e2504e1 100644
--- a/src/core/or/versions.c
+++ b/src/core/or/versions.c
@@ -408,6 +408,10 @@ static strmap_t *protover_summary_map = NULL;
 /**
  * Helper.  Given a non-NULL protover string <b>protocols</b>, set <b>out</b>
  * to its summary, and memoize the result in <b>protover_summary_map</b>.
+ *
+ * If the protover string does not contain any recognised protocols, sets
+ * protocols_known, but does not set any other flags. (Empty strings are also
+ * treated this way.)
  */
 static void
 memoize_protover_summary(protover_summary_flags_t *out,
@@ -485,6 +489,13 @@ memoize_protover_summary(protover_summary_flags_t *out,
 
 /** Summarize the protocols listed in <b>protocols</b> into <b>out</b>,
  * falling back or correcting them based on <b>version</b> as appropriate.
+ *
+ * If protocols and version are both NULL, returns a summary with no flags
+ * set.
+ *
+ * If the protover string does not contain any recognised protocols, and the
+ * version is not recognised, sets protocols_known, but does not set any other
+ * flags. (Empty strings are also treated this way.)
  */
 void
 summarize_protover_flags(protover_summary_flags_t *out,