[tor-commits] [tor/master] Document several issues found by Taylor

[asn at torproject.org]

commit 3d6bf7b36e419bbabd48b4bed82f12fca1a922b3
Author: Nick Mathewson <nickm at torproject.org>
Date:   Tue Mar 12 18:53:24 2019 -0400

    Document several issues found by Taylor
---
 src/lib/pubsub/pub_binding_st.h | 4 +++-
 src/lib/pubsub/pubsub.h         | 3 +++
 src/lib/pubsub/pubsub_connect.h | 3 ++-
 src/lib/pubsub/pubsub_macros.h  | 6 ++++--
 4 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/src/lib/pubsub/pub_binding_st.h b/src/lib/pubsub/pub_binding_st.h
index e8c0d47ef..4f5df8ff3 100644
--- a/src/lib/pubsub/pub_binding_st.h
+++ b/src/lib/pubsub/pub_binding_st.h
@@ -5,8 +5,10 @@
 /* See LICENSE for licensing information */
 
 /**
- * @file pubsub_build.h
+ * @file pub_binding_st.h
  * @brief Declaration of pub_binding_t.
+ *
+ * This is an internal type for the pubsub implementation.
  */
 
 #ifndef TOR_PUB_BINDING_ST_H
diff --git a/src/lib/pubsub/pubsub.h b/src/lib/pubsub/pubsub.h
index 1c51f7a78..08e3f42f7 100644
--- a/src/lib/pubsub/pubsub.h
+++ b/src/lib/pubsub/pubsub.h
@@ -30,6 +30,9 @@
  * Rather than using the dispatch module directly, a publishing module
  * receives a "binding" object that it uses to send messages with the right
  * settings.
+ *
+ * Most users of this module will want to use this header, and the
+ * pubsub_macros.h header for convenience.
  */
 
 /*
diff --git a/src/lib/pubsub/pubsub_connect.h b/src/lib/pubsub/pubsub_connect.h
index b63f9dc43..f3de74c87 100644
--- a/src/lib/pubsub/pubsub_connect.h
+++ b/src/lib/pubsub/pubsub_connect.h
@@ -9,7 +9,8 @@
  * @brief Header for functions that add relationships to a pubsub builder.
  *
  * These functions are used by modules that need to add publication and
- * subscription requests.
+ * subscription requests.  Most users will want to call these functions
+ * indirectly, via the macros in pubsub_macros.h.
  **/
 
 #ifndef TOR_PUBSUB_CONNECT_H
diff --git a/src/lib/pubsub/pubsub_macros.h b/src/lib/pubsub/pubsub_macros.h
index aed9c5128..4d0638d1d 100644
--- a/src/lib/pubsub/pubsub_macros.h
+++ b/src/lib/pubsub/pubsub_macros.h
@@ -175,7 +175,8 @@
  * Use this macro in a header to declare the existence of a given message,
  * taking a pointer as auxiliary data.
  *
- * "messagename" is a unique identifier for the message.
+ * "messagename" is a unique identifier for the message; it must be a valid
+ * C identifier.
  *
  * "typename" is a unique identifier for the type of the auxiliary data.
  *
@@ -199,7 +200,8 @@
  * Use this macro in a header to declare the existence of a given message,
  * taking an integer as auxiliary data.
  *
- * "messagename" is a unique identifier for the message.
+ * "messagename" is a unique identifier for the message; it must be a valid
+ * C identifier.
  *
  * "typename" is a unique identifier for the type of the auxiliary data.
  *