From 8caf6a627180810438df1eb15a9e3c9fd52a4bde Mon Sep 17 00:00:00 2001
From: George Kiagiadakis <george.kiagiadakis@collabora.com>
Date: Sat, 9 Mar 2024 17:56:44 +0200
Subject: [PATCH] log: docs: document the log topic definition macros

---
 lib/wp/log.c | 35 +++++++++++++++++++++++++++++++++++
 lib/wp/log.h | 12 ++++++------
 2 files changed, 41 insertions(+), 6 deletions(-)

diff --git a/lib/wp/log.c b/lib/wp/log.c
index 1759d12b..3e5b9a29 100644
--- a/lib/wp/log.c
+++ b/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()
diff --git a/lib/wp/log.h b/lib/wp/log.h
index 73d28981..f839ff63 100644
--- a/lib/wp/log.h
+++ b/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) \
-  WpLogTopic var##_struct = { .topic_name = t, .flags = WP_LOG_TOPIC_FLAG_STATIC };  \
+#define WP_LOG_TOPIC(var, name) \
+  WpLogTopic var##_struct = { .topic_name = name, .flags = WP_LOG_TOPIC_FLAG_STATIC };  \
   WpLogTopic * var = &(var##_struct);
 
-#define WP_LOG_TOPIC_STATIC(var, t) \
-  static WpLogTopic var##_struct = { .topic_name = t, .flags = WP_LOG_TOPIC_FLAG_STATIC }; \
+#define WP_LOG_TOPIC_STATIC(var, name) \
+  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) \
-  WP_LOG_TOPIC_STATIC(WP_LOCAL_LOG_TOPIC, t)
+#define WP_DEFINE_LOCAL_LOG_TOPIC(name) \
+  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