From 764aaae3914bd498b46185dcb339166a8e7ad660 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Fri, 25 Jul 2025 10:21:04 +0100 Subject: [PATCH 1/2] gwin32: Reformat documentation for g_win32_error_message() Port it to gi-docgen format and improve it to match the documentation style guide. Signed-off-by: Philip Withnall Helps: #3740 --- glib/gwin32.c | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/glib/gwin32.c b/glib/gwin32.c index 0cd4b2323..dcc973448 100644 --- a/glib/gwin32.c +++ b/glib/gwin32.c @@ -194,16 +194,20 @@ g_win32_getlocale (void) /** * g_win32_error_message: - * @error: error code. + * @error: Win32 error code * - * Translate a Win32 error code (as returned by GetLastError() or - * WSAGetLastError()) into the corresponding message. The message is - * either language neutral, or in the thread's language, or the user's - * language, the system's language, or US English (see docs for - * FormatMessage()). The returned string is in UTF-8. It should be - * deallocated with g_free(). + * Translate a Win32 error code into a human readable message. * - * Returns: newly-allocated error message + * The error code could be as returned by + * [`GetLastError()`](https://learn.microsoft.com/en-us/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror) + * or [`WSAGetLastError()`](https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-wsagetlasterror). + * + * The message is either language neutral, or in the thread’s language, or the + * user’s language, the system’s language, or US English (see documentation for + * [`FormatMessage()`](https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-formatmessagew)). + * The returned string is in UTF-8. + * + * Returns: (transfer full) (not nullable): newly-allocated error message **/ gchar * g_win32_error_message (gint error) From 3d0b142bf6e7be7b220dbaa5072e1bf4e5f149ff Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Fri, 25 Jul 2025 10:23:04 +0100 Subject: [PATCH 2/2] gwin32: Document fallback behaviour of g_win32_error_message() Signed-off-by: Philip Withnall Fixes: #3740 --- glib/gwin32.c | 3 +++ 1 file changed, 3 insertions(+) diff --git a/glib/gwin32.c b/glib/gwin32.c index dcc973448..409a3220f 100644 --- a/glib/gwin32.c +++ b/glib/gwin32.c @@ -207,6 +207,9 @@ g_win32_getlocale (void) * [`FormatMessage()`](https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-formatmessagew)). * The returned string is in UTF-8. * + * If a human readable message cannot be found for the given @error, an empty + * string is returned. + * * Returns: (transfer full) (not nullable): newly-allocated error message **/ gchar *