From bae3dec78acef58fb7eb7deeefae6ca0bb20ee2a Mon Sep 17 00:00:00 2001
From: Marcus Weseloh <marcus@weseloh.cc>
Date: Tue, 10 Nov 2020 23:58:44 +0100
Subject: [PATCH] Logging interface

---
 include/fluidsynth/log.h | 37 ++++++++++++++++++++-----------------
 1 file changed, 20 insertions(+), 17 deletions(-)

diff --git a/include/fluidsynth/log.h b/include/fluidsynth/log.h
index 05043948..ec553ba4 100644
--- a/include/fluidsynth/log.h
+++ b/include/fluidsynth/log.h
@@ -28,26 +28,30 @@ extern "C" {
 
 
 /**
- * @defgroup Logging Logging
- * @brief Logging interface
+ * @defgroup logging Logging
  *
- * The default logging function of the fluidsynth prints its messages
- * to the stderr. The synthesizer uses five level of messages: #FLUID_PANIC,
+ * Logging interface
+ *
+ * The default logging function of the fluidsynth prints its messages to the
+ * stderr. The synthesizer uses five level of messages: #FLUID_PANIC,
  * #FLUID_ERR, #FLUID_WARN, #FLUID_INFO, and #FLUID_DBG.
  *
- * A client application can install a new log function to handle the
- * messages differently. In the following example, the application
- * sets a callback function to display #FLUID_PANIC messages in a dialog,
- * and ignores all other messages by setting the log function to
- * NULL:
+ * A client application can install a new log function to handle the messages
+ * differently. In the following example, the application sets a callback
+ * function to display #FLUID_PANIC messages in a dialog, and ignores all other
+ * messages by setting the log function to NULL:
  *
  * @code
- *   fluid_set_log_function(FLUID_PANIC, show_dialog, (void*) root_window);
- *   fluid_set_log_function(FLUID_ERR, NULL, NULL);
- *   fluid_set_log_function(FLUID_WARN, NULL, NULL);
- *   fluid_set_log_function(FLUID_DBG, NULL, NULL);
+ * fluid_set_log_function(FLUID_PANIC, show_dialog, (void*) root_window);
+ * fluid_set_log_function(FLUID_ERR, NULL, NULL);
+ * fluid_set_log_function(FLUID_WARN, NULL, NULL);
+ * fluid_set_log_function(FLUID_DBG, NULL, NULL);
  * @endcode
  *
+ * @note The logging configuration is global and not tied to a specific
+ * synthesizer instance. That means that all synthesizer instances created in
+ * the same process share the same logging configuration.
+ *
  * @{
  */
 
@@ -61,13 +65,13 @@ enum fluid_log_level
     FLUID_WARN,    /**< Warning */
     FLUID_INFO,    /**< Verbose informational messages */
     FLUID_DBG,     /**< Debugging messages */
-#ifndef __DOXYGEN__
-    LAST_LOG_LEVEL /**< @warning This symbol is not part of the public API and ABI stability guarantee and may change at any time! */
-#endif
+    LAST_LOG_LEVEL /**< @internal This symbol is not part of the public API and ABI
+                     stability guarantee and may change at any time! */
 };
 
 /**
  * Log function handler callback type used by fluid_set_log_function().
+ *
  * @param level Log level (#fluid_log_level)
  * @param message Log message text
  * @param data User data pointer supplied to fluid_set_log_function().
@@ -84,7 +88,6 @@ FLUIDSYNTH_API int fluid_log(int level, const char *fmt, ...)
 __attribute__ ((format (printf, 2, 3)))
 #endif
 ;
-
 /* @} */
 
 #ifdef __cplusplus