From 1691657cb3b283c3d97bfec8dcde6adfe86e052d Mon Sep 17 00:00:00 2001
From: Roberto Leinardi <leinardi@gmail.com>
Date: Thu, 5 Dec 2024 16:26:55 +0100
Subject: [PATCH 1/2] gmessages: Add nullable annotation for `log_domain` in
 `GLogFunc`

Add a missing `(nullable)` annotation for the `log_domain` parameter in the
`GLogFunc` callback. This ensures consistency with the documentation and
usage in functions like `g_log_set_handler`, where `log_domain` can be `NULL`.

Without this annotation, the GIR file generated from the C source does not
reflect the nullability of `log_domain`, leading to potential issues in
language bindings and other introspection-based tools.

This change updates the documentation in `glib/gmessages.c` to include the
nullable annotation and clarifies the expected behavior of the `GLogFunc`
callback.

Fixes #3552
---
 glib/gmessages.c | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/glib/gmessages.c b/glib/gmessages.c
index e4210604b..7a84b6620 100644
--- a/glib/gmessages.c
+++ b/glib/gmessages.c
@@ -129,7 +129,7 @@
 
 /**
  * GLogFunc:
- * @log_domain: the log domain of the message
+ * @log_domain: (nullable): the log domain of the message
  * @log_level: the log level of the message (including the
  *   fatal and recursion flags)
  * @message: the message to process
@@ -143,6 +143,9 @@
  * code do not need modifying to add a new-line character to the message if the
  * log handler is changed.
  *
+ * The `log_domain` parameter can be set to `NULL` or an empty string to use the default
+ * application domain.
+ *
  * This is not used if structured logging is enabled; see
  * [Using Structured Logging](logging.html#using-structured-logging).
  */

From 78b4b66e9a02a36781955ecf8706ae3e6b53d0bd Mon Sep 17 00:00:00 2001
From: Roberto Leinardi <leinardi@gmail.com>
Date: Thu, 5 Dec 2024 17:12:36 +0100
Subject: [PATCH 2/2] gmessages: Clarify `log_domain` behavior in function
 descriptions

Move details about the `log_domain` parameter being `NULL` or an empty string
for the default application domain from argument descriptions to the main
function descriptions.

This ensures concise argument descriptions while providing a clear
explanation of exceptions in the function body.
---
 glib/gmessages.c | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/glib/gmessages.c b/glib/gmessages.c
index 7a84b6620..839361718 100644
--- a/glib/gmessages.c
+++ b/glib/gmessages.c
@@ -658,7 +658,7 @@ g_log_set_fatal_mask (const gchar   *log_domain,
 
 /**
  * g_log_set_handler:
- * @log_domain: (nullable): the log domain, or `NULL` for the default `""`
+ * @log_domain: (nullable): the log domain
  *    application domain
  * @log_levels: the log levels to apply the log handler for.
  *    To handle fatal and recursive messages as well, combine
@@ -680,6 +680,9 @@ g_log_set_fatal_mask (const gchar   *log_domain,
  * This has no effect if structured logging is enabled; see
  * [Using Structured Logging](logging.html#using-structured-logging).
  *
+ * The `log_domain` parameter can be set to `NULL` or an empty string to use the default
+ * application domain.
+ *
  * Here is an example for adding a log handler for all warning messages
  * in the default domain:
  *
@@ -715,7 +718,7 @@ g_log_set_handler (const gchar	 *log_domain,
 
 /**
  * g_log_set_handler_full: (rename-to g_log_set_handler)
- * @log_domain: (nullable): the log domain, or `NULL` for the default `""`
+ * @log_domain: (nullable): the log domain
  *   application domain
  * @log_levels: the log levels to apply the log handler for.
  *   To handle fatal and recursive messages as well, combine
@@ -730,6 +733,9 @@ g_log_set_handler (const gchar	 *log_domain,
  * This has no effect if structured logging is enabled; see
  * [Using Structured Logging](logging.html#using-structured-logging).
  *
+ * The `log_domain` parameter can be set to `NULL` or an empty string to use the default
+ * application domain.
+ *
  * Returns: the ID of the new handler
  *
  * Since: 2.46
@@ -1128,7 +1134,7 @@ static GSList *expected_messages = NULL;
 
 /**
  * g_logv:
- * @log_domain: (nullable): the log domain, or `NULL` for the default `""`
+ * @log_domain: (nullable): the log domain
  *   application domain
  * @log_level: the log level
  * @format: the message format. See the `printf()` documentation
@@ -1146,6 +1152,9 @@ static GSList *expected_messages = NULL;
  *
  * If [structured logging is enabled](logging.html#using-structured-logging) this will
  * output via the structured log writer function (see [func@GLib.log_set_writer_func]).
+ *
+ * The `log_domain` parameter can be set to `NULL` or an empty string to use the default
+ * application domain.
  */
 void
 g_logv (const gchar   *log_domain,