commit 3d6bf7b36e419bbabd48b4bed82f12fca1a922b3 Author: Nick Mathewson nickm@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. *