diff --git a/glib/gprintf.c b/glib/gprintf.c index 34ba8e92f..c9a99142a 100644 --- 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. + * Returns: the number of bytes which would be produced if the buffer + * 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 **/ @@ -253,35 +253,35 @@ g_vsprintf (gchar *string, return _g_vsprintf (string, format, args); } -/** +/** * g_vsnprintf: - * @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. + * @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 * - * A safer form of the standard vsprintf() function. The output is guaranteed - * to not exceed @n characters (including the terminating nul character), so + * 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 + * 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 + * 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 - * as standardized in ISO C99. Note that this is different from traditional - * vsnprintf(), which returns the length of the output string. + * 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. * - * The format string may contain positional parameters, as specified in + * 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. + * Returns: the number of bytes which would be produced if the buffer + * 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 - * string to hold the output, instead of putting the output in a buffer + * 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 **/