log: docs: document the log topic definition macros

lib/wp/log.c

@@ -17,6 +17,41 @@ WP_DEFINE_LOCAL_LOG_TOPIC ("wp-log")
  * \defgroup wplog Debug Logging
  * \{
  */
+/*!
+ * \def WP_DEFINE_LOCAL_LOG_TOPIC(name)
+ * \brief Defines a static \em WpLogTopic* variable called \em WP_LOCAL_LOG_TOPIC
+ *
+ * The log topic is automatically intialized to the given topic \a name when
+ * it is first used. The default logging macros expect this variable to be
+ * defined, so it is a good coding practice in the WirePlumber codebase to
+ * start all files at the top with:
+ * \code
+ * WP_DEFINE_LOCAL_LOG_TOPIC ("some-topic")
+ * \endcode
+ *
+ * \param name The name of the log topic
+ */
+/*!
+ * \def WP_LOG_TOPIC_STATIC(var, name)
+ * \brief Defines a static \em WpLogTopic* variable called \a var with the given
+ * topic \a name
+ * \param var The name of the variable to define
+ * \param name The name of the log topic
+ */
+/*!
+ * \def WP_LOG_TOPIC(var, name)
+ * \brief Defines a \em WpLogTopic* variable called \a var with the given
+ * topic \a name. Unlike WP_LOG_TOPIC_STATIC(), the variable defined here is
+ * not static, so it can be linked to by other object files.
+ * \param var The name of the variable to define
+ * \param name The name of the log topic
+ */
+/*!
+ * \def WP_LOG_TOPIC_EXTERN(var)
+ * \brief Declares an extern \em WpLogTopic* variable called \a var.
+ * This variable is meant to be defined in a .c file with WP_LOG_TOPIC()
+ * \param var The name of the variable to declare
+ */
 /*!
  * \def WP_OBJECT_FORMAT
  * \brief A format string to print GObjects with WP_OBJECT_ARGS()

lib/wp/log.h

@@ -61,16 +61,16 @@ struct _WpLogTopic {
 #define WP_LOG_TOPIC_EXTERN(var) \
   extern WpLogTopic * var;
 
-#define WP_LOG_TOPIC(var, t) \
+#define WP_LOG_TOPIC(var, name) \
-  WpLogTopic var##_struct = { .topic_name = t, .flags = WP_LOG_TOPIC_FLAG_STATIC };  \
+  WpLogTopic var##_struct = { .topic_name = name, .flags = WP_LOG_TOPIC_FLAG_STATIC };  \
   WpLogTopic * var = &(var##_struct);
 
-#define WP_LOG_TOPIC_STATIC(var, t) \
+#define WP_LOG_TOPIC_STATIC(var, name) \
-  static WpLogTopic var##_struct = { .topic_name = t, .flags = WP_LOG_TOPIC_FLAG_STATIC }; \
+  static WpLogTopic var##_struct = { .topic_name = name, .flags = WP_LOG_TOPIC_FLAG_STATIC }; \
   static G_GNUC_UNUSED WpLogTopic * var = &(var##_struct);
 
-#define WP_DEFINE_LOCAL_LOG_TOPIC(t) \
+#define WP_DEFINE_LOCAL_LOG_TOPIC(name) \
-  WP_LOG_TOPIC_STATIC(WP_LOCAL_LOG_TOPIC, t)
+  WP_LOG_TOPIC_STATIC(WP_LOCAL_LOG_TOPIC, name)
 
 /* make glib log functions also use the local log topic */
 #ifdef WP_USE_LOCAL_LOG_TOPIC_IN_G_LOG