Merge branch '3740-win32-error-message-docs' into 'main'

gwin32: Document fallback behaviour of g_win32_error_message()

Closes #3740

See merge request GNOME/glib!4716

glib/gwin32.c

@@ -194,16 +194,23 @@ 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
+ * Translate a Win32 error code into a human readable message.
- * 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().
  *
- * 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.
+ *
+ * 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 *
 g_win32_error_message (gint error)