mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-01-26 05:56:14 +01:00
Merge branch 'improve-documentation' into 'main'
gprintf/gstrfuncs: Improve and port doc comments to gi-docgen See merge request GNOME/glib!3807
This commit is contained in:
Philip Withnall
commit
96b1298871
151
glib/gprintf.c
151
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: (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
|
||||
**/
|
||||
|
||||
853
glib/gstrfuncs.c
853
glib/gstrfuncs.c
File diff suppressed because it is too large
Load Diff
@ -412,8 +412,8 @@ gboolean g_strv_equal (const gchar * const *strv1,
|
||||
|
||||
/**
|
||||
* GNumberParserError:
|
||||
* @G_NUMBER_PARSER_ERROR_INVALID: String was not a valid number.
|
||||
* @G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS: String was a number, but out of bounds.
|
||||
* @G_NUMBER_PARSER_ERROR_INVALID: string was not a valid number
|
||||
* @G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS: string was a number, but out of bounds
|
||||
*
|
||||
* Error codes returned by functions converting a string to a number.
|
||||
*
|
||||
|
||||
Loading…
Reference in New Issue
Block a user