luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-24 03:02:10 +01:00
Code Issues Packages Projects Releases Wiki Activity

gprintf: Port doc comments to gi-docgen

Browse Source 
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
This commit is contained in:
velsinki 2024-01-06 16:50:42 +01:00 committed by Philip Withnall
parent 2b22befc4f
commit 8d2d12bd52
1 changed files with 76 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

151
glib/gprintf.c
View File

@ -30,20 +30,20 @@
/** /**
* g_printf: * g_printf:
* @format: a standard printf() format string, but notice * @format: a standard `printf()` format string, but notice
* [string precision pitfalls](string-utils.html#string-precision-pitfalls) * [string precision pitfalls](string-utils.html#string-precision-pitfalls)
* @...: the arguments to insert in the output. * @...: 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. * 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 * new-line character to the message, so typically @format should end with its
* own new-line character. * own new-line character.
* *
* `glib/gprintf.h` must be explicitly included in order to use this function. * `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 * Since: 2.2
**/ **/
@ -63,17 +63,17 @@ g_printf (gchar const *format,
/** /**
* g_fprintf: * g_fprintf:
* @file: (not nullable): the stream to write to. * @file: (not nullable): the stream to write to
* @format: a standard printf() format string, but notice * @format: a standard `printf()` format string, but notice
* [string precision pitfalls](string-utils.html#string-precision-pitfalls) * [string precision pitfalls](string-utils.html#string-precision-pitfalls)
* @...: the arguments to insert in the output. * @...: 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. * positional parameters, as specified in the Single Unix Specification.
* *
* `glib/gprintf.h` must be explicitly included in order to use this function. * `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 * Since: 2.2
**/ **/
@ -95,23 +95,23 @@ g_fprintf (FILE *file,
/** /**
* g_sprintf: * g_sprintf:
* @string: A pointer to a memory buffer to contain the resulting string. It * @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 * is up to the caller to ensure that the allocated buffer is large
* enough to hold the formatted result * enough to hold the formatted result.
* @format: a standard printf() format string, but notice * @format: a standard `printf()` format string, but notice
* [string precision pitfalls](string-utils.html#string-precision-pitfalls) * [string precision pitfalls](string-utils.html#string-precision-pitfalls)
* @...: the arguments to insert in the output. * @...: 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. * 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. * risk of buffer overflow.
* *
* `glib/gprintf.h` must be explicitly included in order to use this function. * `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 * Since: 2.2
**/ **/
@ -132,18 +132,18 @@ g_sprintf (gchar *string,
/** /**
* g_snprintf: * 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 * @n: the maximum number of bytes to produce (including the
* terminating nul character). * terminating nul character)
* @format: a standard printf() format string, but notice * @format: a standard `printf()` format string, but notice
* [string precision pitfalls](string-utils.html#string-precision-pitfalls) * [string precision pitfalls](string-utils.html#string-precision-pitfalls)
* @...: the arguments to insert in the output. * @...: the arguments to insert in the output
* *
* A safer form of the standard sprintf() function. The output is guaranteed * A safer form of the standard sprintf() function. The output is guaranteed
* to not exceed @n characters (including the terminating nul character), so * to not exceed @n characters (including the terminating nul character), so
* it is easy to ensure that a buffer overflow cannot occur. * 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 * 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. * 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() * The return value of g_snprintf() conforms to the snprintf()
* function as standardized in ISO C99. Note that this is different from * 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 format string may contain positional parameters, as specified in
* the Single Unix Specification. * the Single Unix Specification.
* *
* Returns: the number of bytes which would be produced if the buffer * Returns: the number of bytes which would be produced if the buffer
* was large enough. * was large enough
**/ **/
gint gint
g_snprintf (gchar *string, g_snprintf (gchar *string,
@ -178,16 +178,16 @@ g_snprintf (gchar *string,
/** /**
* g_vprintf: * g_vprintf:
* @format: a standard printf() format string, but notice * @format: a standard `printf()` format string, but notice
* [string precision pitfalls](string-utils.html#string-precision-pitfalls) * [string precision pitfalls](string-utils.html#string-precision-pitfalls)
* @args: the list of arguments to insert in the output. * @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. * positional parameters, as specified in the Single Unix Specification.
* *
* `glib/gprintf.h` must be explicitly included in order to use this function. * `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 * Since: 2.2
**/ **/
@ -202,17 +202,17 @@ g_vprintf (gchar const *format,
/** /**
* g_vfprintf: * g_vfprintf:
* @file: (not nullable): the stream to write to. * @file: (not nullable): the stream to write to
* @format: a standard printf() format string, but notice * @format: a standard `printf()` format string, but notice
* [string precision pitfalls](string-utils.html#string-precision-pitfalls) * [string precision pitfalls](string-utils.html#string-precision-pitfalls)
* @args: the list of arguments to insert in the output. * @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. * positional parameters, as specified in the Single Unix Specification.
* *
* `glib/gprintf.h` must be explicitly included in order to use this function. * `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 * Since: 2.2
**/ **/
@ -228,17 +228,17 @@ g_vfprintf (FILE *file,
/** /**
* g_vsprintf: * g_vsprintf:
* @string: the buffer to hold the output. * @string: the buffer to hold the output
* @format: a standard printf() format string, but notice * @format: a standard `printf()` format string, but notice
* [string precision pitfalls](string-utils.html#string-precision-pitfalls) * [string precision pitfalls](string-utils.html#string-precision-pitfalls)
* @args: the list of arguments to insert in the output. * @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. * positional parameters, as specified in the Single Unix Specification.
* *
* `glib/gprintf.h` must be explicitly included in order to use this function. * `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 * Since: 2.2
**/ **/
@ -253,35 +253,35 @@ g_vsprintf (gchar *string,
return _g_vsprintf (string, format, args); return _g_vsprintf (string, format, args);
} }
/** /**
* g_vsnprintf: * 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 * @n: the maximum number of bytes to produce (including the
* terminating nul character). * terminating nul character)
* @format: a standard printf() format string, but notice * @format: a standard `printf()` format string, but notice
* [string precision pitfalls](string-utils.html#string-precision-pitfalls) * [string precision pitfalls](string-utils.html#string-precision-pitfalls)
* @args: the list of arguments to insert in the output. * @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 * to not exceed @n characters (including the terminating nul character), so
* it is easy to ensure that a buffer overflow cannot occur. * 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 * 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. * 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 * In versions prior to 1.3.12, this function returns the length of the output
* string. * 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 * 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 format string may contain positional parameters, as specified in
* the Single Unix Specification. * the Single Unix Specification.
* *
* Returns: the number of bytes which would be produced if the buffer * Returns: the number of bytes which would be produced if the buffer
* was large enough. * was large enough
*/ */
gint gint
g_vsnprintf (gchar *string, g_vsnprintf (gchar *string,
@ -297,25 +297,26 @@ g_vsnprintf (gchar *string,
/** /**
* g_vasprintf: * g_vasprintf:
* @string: (out) (not optional) (nullable): the return location for the newly-allocated string, * @string: (out) (not optional) (nullable): the return location for the
* which will be %NULL if (and only if) this function fails * newly-allocated string, which will be `NULL` if (and only if)
* @format: (not nullable): a standard printf() format string, but notice * this function fails
* [string precision pitfalls](string-utils.html#string-precision-pitfalls) * @format: (not nullable): a standard `printf()` format string, but notice
* @args: the list of arguments to insert in the output. * [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. * 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 * string to hold the output, instead of putting the output in a buffer
* you allocate in advance. * 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 * @format contains `%lc` or `%ls` conversions, which can fail if no
* multibyte representation is available for the given character. * multibyte representation is available for the given character.
* *
* `glib/gprintf.h` must be explicitly included in order to use this function. * `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 * Since: 2.4
**/ **/