gprintf: Port doc comments to gi-docgen

Fixes broken links, and removes `%` and `#` notation in favor of inline code, and limits indentation to two to prevent accidental formatting. Fixes some style issues too, mainly removing periods at the end of parameter and return descriptions. Also removes trailing whitespace from the doc comments. Helps: #3037
2025-02-24 11:12:11 +01:00 · 2024-01-06 16:50:42 +01:00 · 2024-01-06 16:50:42 +01:00 · 8d2d12bd52
commit 8d2d12bd52
parent 2b22befc4f
1 changed files with 76 additions and 75 deletions
--- a/glib/gprintf.c
+++ b/glib/gprintf.c
@ -30,20 +30,20 @@

 /**
 * g_printf:
- * @format: a standard printf() format string, but notice 
- *          [string precision pitfalls](string-utils.html#string-precision-pitfalls)
- * @...: the arguments to insert in the output.
+ * @format: a standard `printf()` format string, but notice
+ *   [string precision pitfalls](string-utils.html#string-precision-pitfalls)
+ * @...: the arguments to insert in the output
 *
- * An implementation of the standard printf() function which supports 
+ * An implementation of the standard `printf()` function which supports
 * positional parameters, as specified in the Single Unix Specification.
 *
- * As with the standard printf(), this does not automatically append a trailing
+ * As with the standard `printf()`, this does not automatically append a trailing
 * new-line character to the message, so typically @format should end with its
 * own new-line character.
 *
 * `glib/gprintf.h` must be explicitly included in order to use this function.
 *
- * Returns: the number of bytes printed.
+ * Returns: the number of bytes printed
 *
 * Since: 2.2
 **/
@ -63,17 +63,17 @@ g_printf (gchar const *format,

 /**
 * g_fprintf:
- * @file: (not nullable): the stream to write to.
- * @format: a standard printf() format string, but notice 
- *          [string precision pitfalls](string-utils.html#string-precision-pitfalls)
- * @...: the arguments to insert in the output.
+ * @file: (not nullable): the stream to write to
+ * @format: a standard `printf()` format string, but notice
+ *   [string precision pitfalls](string-utils.html#string-precision-pitfalls)
+ * @...: the arguments to insert in the output
 *
- * An implementation of the standard fprintf() function which supports 
+ * An implementation of the standard `fprintf()` function which supports
 * positional parameters, as specified in the Single Unix Specification.
 *
 * `glib/gprintf.h` must be explicitly included in order to use this function.
 *
- * Returns: the number of bytes printed.
+ * Returns: the number of bytes printed
 *
 * Since: 2.2
 **/
@ -95,23 +95,23 @@ g_fprintf (FILE        *file,
 /**
 * g_sprintf:
 * @string: A pointer to a memory buffer to contain the resulting string. It
- *          is up to the caller to ensure that the allocated buffer is large
- *          enough to hold the formatted result
- * @format: a standard printf() format string, but notice
- *          [string precision pitfalls](string-utils.html#string-precision-pitfalls)
- * @...: the arguments to insert in the output.
+ *   is up to the caller to ensure that the allocated buffer is large
+ *   enough to hold the formatted result.
+ * @format: a standard `printf()` format string, but notice
+ *   [string precision pitfalls](string-utils.html#string-precision-pitfalls)
+ * @...: the arguments to insert in the output
 *
- * An implementation of the standard sprintf() function which supports
+ * An implementation of the standard `sprintf()` function which supports
 * positional parameters, as specified in the Single Unix Specification.
 *
- * Note that it is usually better to use g_snprintf(), to avoid the
+ * Note that it is usually better to use [func@GLib.snprintf], to avoid the
 * risk of buffer overflow.
 *
 * `glib/gprintf.h` must be explicitly included in order to use this function.
 *
- * See also g_strdup_printf().
+ * See also [func@GLib.strdup_printf].
 *
- * Returns: the number of bytes printed.
+ * Returns: the number of bytes printed
 *
 * Since: 2.2
 **/
@ -132,18 +132,18 @@ g_sprintf (gchar       *string,

 /**
 * g_snprintf:
- * @string: the buffer to hold the output.
+ * @string: the buffer to hold the output
 * @n: the maximum number of bytes to produce (including the
- *     terminating nul character).
- * @format: a standard printf() format string, but notice
- *          [string precision pitfalls](string-utils.html#string-precision-pitfalls)
- * @...: the arguments to insert in the output.
+ *   terminating nul character)
+ * @format: a standard `printf()` format string, but notice
+ *   [string precision pitfalls](string-utils.html#string-precision-pitfalls)
+ * @...: the arguments to insert in the output
 *
 * A safer form of the standard sprintf() function. The output is guaranteed
 * to not exceed @n characters (including the terminating nul character), so
 * it is easy to ensure that a buffer overflow cannot occur.
 *
- * See also g_strdup_printf().
+ * See also [func@GLib.strdup_printf].
 *
 * In versions of GLib prior to 1.2.3, this function may return -1 if the
 * output was truncated, and the truncated string may not be nul-terminated.
@ -152,13 +152,13 @@ g_sprintf (gchar       *string,
 *
 * The return value of g_snprintf() conforms to the snprintf()
 * function as standardized in ISO C99. Note that this is different from
- * traditional snprintf(), which returns the length of the output string.
+ * traditional `snprintf()`, which returns the length of the output string.
 *
 * The format string may contain positional parameters, as specified in
 * the Single Unix Specification.
 *
 * Returns: the number of bytes which would be produced if the buffer
- *     was large enough.
+ *   was large enough
 **/
 gint
 g_snprintf (gchar	*string,
@ -178,16 +178,16 @@ g_snprintf (gchar	*string,

 /**
 * g_vprintf:
- * @format: a standard printf() format string, but notice 
- *          [string precision pitfalls](string-utils.html#string-precision-pitfalls)
- * @args: the list of arguments to insert in the output.
+ * @format: a standard `printf()` format string, but notice
+ *   [string precision pitfalls](string-utils.html#string-precision-pitfalls)
+ * @args: the list of arguments to insert in the output
 *
- * An implementation of the standard vprintf() function which supports 
+ * An implementation of the standard `vprintf()` function which supports
 * positional parameters, as specified in the Single Unix Specification.
 *
 * `glib/gprintf.h` must be explicitly included in order to use this function.
 *
- * Returns: the number of bytes printed.
+ * Returns: the number of bytes printed
 *
 * Since: 2.2
 **/
@ -202,17 +202,17 @@ g_vprintf (gchar const *format,

 /**
 * g_vfprintf:
- * @file: (not nullable): the stream to write to.
- * @format: a standard printf() format string, but notice 
- *          [string precision pitfalls](string-utils.html#string-precision-pitfalls)
- * @args: the list of arguments to insert in the output.
+ * @file: (not nullable): the stream to write to
+ * @format: a standard `printf()` format string, but notice
+ *   [string precision pitfalls](string-utils.html#string-precision-pitfalls)
+ * @args: the list of arguments to insert in the output
 *
- * An implementation of the standard fprintf() function which supports 
+ * An implementation of the standard `fprintf()` function which supports
 * positional parameters, as specified in the Single Unix Specification.
 *
 * `glib/gprintf.h` must be explicitly included in order to use this function.
 *
- * Returns: the number of bytes printed.
+ * Returns: the number of bytes printed
 *
 * Since: 2.2
 **/
@ -228,17 +228,17 @@ g_vfprintf (FILE        *file,

 /**
 * g_vsprintf:
- * @string: the buffer to hold the output.
- * @format: a standard printf() format string, but notice 
- *          [string precision pitfalls](string-utils.html#string-precision-pitfalls)
- * @args: the list of arguments to insert in the output.
+ * @string: the buffer to hold the output
+ * @format: a standard `printf()` format string, but notice
+ *   [string precision pitfalls](string-utils.html#string-precision-pitfalls)
+ * @args: the list of arguments to insert in the output
 *
- * An implementation of the standard vsprintf() function which supports 
+ * An implementation of the standard `vsprintf()` function which supports
 * positional parameters, as specified in the Single Unix Specification.
 *
 * `glib/gprintf.h` must be explicitly included in order to use this function.
 *
- * Returns: the number of bytes printed.
+ * Returns: the number of bytes printed
 *
 * Since: 2.2
 **/
@ -255,33 +255,33 @@ g_vsprintf (gchar	 *string,

 /**
 * g_vsnprintf:
- * @string: the buffer to hold the output.
+ * @string: the buffer to hold the output
 * @n: the maximum number of bytes to produce (including the
- *     terminating nul character).
- * @format: a standard printf() format string, but notice 
- *          [string precision pitfalls](string-utils.html#string-precision-pitfalls)
- * @args: the list of arguments to insert in the output.
+ *   terminating nul character)
+ * @format: a standard `printf()` format string, but notice
+ *   [string precision pitfalls](string-utils.html#string-precision-pitfalls)
+ * @args: the list of arguments to insert in the output
 *
- * A safer form of the standard vsprintf() function. The output is guaranteed
+ * A safer form of the standard `vsprintf()` function. The output is guaranteed
 * to not exceed @n characters (including the terminating nul character), so
 * it is easy to ensure that a buffer overflow cannot occur.
 *
- * See also g_strdup_vprintf().
+ * See also [func@GLib.strdup_vprintf].
 *
 * In versions of GLib prior to 1.2.3, this function may return -1 if the
 * output was truncated, and the truncated string may not be nul-terminated.
 * In versions prior to 1.3.12, this function returns the length of the output
 * string.
 *
- * The return value of g_vsnprintf() conforms to the vsnprintf() function 
+ * The return value of `g_vsnprintf()` conforms to the `vsnprintf()` function
 * as standardized in ISO C99. Note that this is different from traditional
- * vsnprintf(), which returns the length of the output string.
+ * `vsnprintf()`, which returns the length of the output string.
 *
 * The format string may contain positional parameters, as specified in
 * the Single Unix Specification.
 *
 * Returns: the number of bytes which would be produced if the buffer
- *  was large enough.
+ *  was large enough
 */
 gint
 g_vsnprintf (gchar	 *string,
@ -297,25 +297,26 @@ g_vsnprintf (gchar	 *string,

 /**
 * g_vasprintf:
- * @string: (out) (not optional) (nullable): the return location for the newly-allocated string,
- *   which will be %NULL if (and only if) this function fails
- * @format: (not nullable): a standard printf() format string, but notice
- *          [string precision pitfalls](string-utils.html#string-precision-pitfalls)
- * @args: the list of arguments to insert in the output.
+ * @string: (out) (not optional) (nullable): the return location for the
+ *   newly-allocated string, which will be `NULL` if (and only if)
+ *   this function fails
+ * @format: (not nullable): a standard `printf()` format string, but notice
+ *   [string precision pitfalls](string-utils.html#string-precision-pitfalls)
+ * @args: the list of arguments to insert in the output
 *
- * An implementation of the GNU vasprintf() function which supports 
+ * An implementation of the GNU `vasprintf()` function which supports
 * positional parameters, as specified in the Single Unix Specification.
- * This function is similar to g_vsprintf(), except that it allocates a 
+ * This function is similar to [func@GLib.vsprintf], except that it allocates a
 * string to hold the output, instead of putting the output in a buffer
 * you allocate in advance.
 *
- * The returned value in @string is guaranteed to be non-NULL, unless
+ * The returned value in @string is guaranteed to be non-`NULL`, unless
 * @format contains `%lc` or `%ls` conversions, which can fail if no
 * multibyte representation is available for the given character.
 *
 * `glib/gprintf.h` must be explicitly included in order to use this function.
 *
- * Returns: the number of bytes printed, or `-1` on failure
+ * Returns: the number of bytes printed, or -1 on failure
 *
 * Since: 2.4
 **/