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

Merge branch 'improve-documentation' into 'main'

Browse Source 
gprintf/gstrfuncs: Improve and port doc comments to gi-docgen

See merge request GNOME/glib!3807
This commit is contained in:
Philip Withnall
2024-01-25 12:16:57 +00:00
parent c92c1502d2 66cd331172
commit 96b1298871
3 changed files with 506 additions and 502 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
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
**/ **/
@@ -96,22 +96,22 @@ 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
**/ **/
@@ -255,33 +255,33 @@ g_vsprintf (gchar *string,
/** /**
* 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: (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
* @format: (not nullable): 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 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
**/ **/

781
glib/gstrfuncs.c
View File

File diff suppressed because it is too large Load Diff

4
glib/gstrfuncs.h
View File

@@ -412,8 +412,8 @@ gboolean g_strv_equal (const gchar * const *strv1,
/** /**
* GNumberParserError: * GNumberParserError:
* @G_NUMBER_PARSER_ERROR_INVALID: String was not a valid number. * @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_OUT_OF_BOUNDS: string was a number, but out of bounds
* *
* Error codes returned by functions converting a string to a number. * Error codes returned by functions converting a string to a number.
* *