Document several issues found by Taylor

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

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.
  */
 
 /*

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

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.
  *