From c575d24dfb78d956e66a522524c7b1d82d0adde7 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 31 Jan 2014 14:56:10 -0500 Subject: [PATCH] Docs: Don't use the note tag More markup avoidance. --- gio/gioscheduler.c | 8 +- gio/gsettingsbackend.c | 6 +- gio/gsimpleasyncresult.c | 8 +- gio/gthemedicon.c | 4 - glib/docs.c | 271 +++++++--------- glib/garray.c | 676 ++++++++++++++++++++------------------- glib/ggettext.c | 24 +- glib/gkeyfile.c | 7 +- glib/glib-unix.c | 18 +- glib/glist.c | 31 +- glib/gmacros.h | 52 ++- glib/gmem.c | 17 +- glib/gqueue.c | 7 +- glib/gsequence.c | 8 - glib/gslist.c | 30 +- glib/gspawn.c | 161 +++++----- glib/gstrfuncs.c | 219 +++++++------ glib/gthread-posix.c | 7 +- glib/gthread.c | 10 +- glib/gutils.c | 28 +- gobject/gbinding.c | 48 +-- gobject/gobject.c | 2 - 22 files changed, 773 insertions(+), 869 deletions(-) diff --git a/gio/gioscheduler.c b/gio/gioscheduler.c index ab8afa17c..97c4bd230 100644 --- a/gio/gioscheduler.c +++ b/gio/gioscheduler.c @@ -29,14 +29,12 @@ * @short_description: I/O Scheduler * @include: gio/gio.h * - * - * As of GLib 2.36, the g_io_scheduler methods - * are deprecated in favor of #GThreadPool and #GTask. - * + * As of GLib 2.36, #GIOScheduler is deprecated in favor of + * #GThreadPool and #GTask. * * Schedules asynchronous I/O operations. #GIOScheduler integrates * into the main event loop (#GMainLoop) and uses threads. - **/ + */ struct _GIOSchedulerJob { GList *active_link; diff --git a/gio/gsettingsbackend.c b/gio/gsettingsbackend.c index 8c1d2677e..9c9640159 100644 --- a/gio/gsettingsbackend.c +++ b/gio/gsettingsbackend.c @@ -75,13 +75,11 @@ static gboolean g_settings_has_backend; * g_settings_backend_create_tree() is a convenience function to create * suitable trees. * - * - * The #GSettingsBackend API is exported to allow third-party + * The GSettingsBackend API is exported to allow third-party * implementations, but does not carry the same stability guarantees * as the public GIO API. For this reason, you have to define the - * C preprocessor symbol #G_SETTINGS_ENABLE_BACKEND before including + * C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including * gio/gsettingsbackend.h - * **/ static gboolean diff --git a/gio/gsimpleasyncresult.c b/gio/gsimpleasyncresult.c index 017e240bc..f5e4b2ad8 100644 --- a/gio/gsimpleasyncresult.c +++ b/gio/gsimpleasyncresult.c @@ -34,12 +34,10 @@ * SECTION:gsimpleasyncresult * @short_description: Simple asynchronous results implementation * @include: gio/gio.h - * @see_also: #GAsyncResult + * @see_also: #GAsyncResult, #GTask * - * - * As of GLib 2.36, #GSimpleAsyncResult is deprecated in favor of - * #GTask, which provides a simpler API. - * + * As of GLib 2.36, #GSimpleAsyncResult is deprecated in favor of + * #GTask, which provides a simpler API. * * #GSimpleAsyncResult implements #GAsyncResult. * diff --git a/gio/gthemedicon.c b/gio/gthemedicon.c index 1b171c97a..499076658 100644 --- a/gio/gthemedicon.c +++ b/gio/gthemedicon.c @@ -390,10 +390,8 @@ g_themed_icon_get_names (GThemedIcon *icon) * * Append a name to the list of icons from within @icon. * - * * Note that doing so invalidates the hash computed by prior calls * to g_icon_hash(). - * */ void g_themed_icon_append_name (GThemedIcon *icon, @@ -419,10 +417,8 @@ g_themed_icon_append_name (GThemedIcon *icon, * * Prepend a name to the list of icons from within @icon. * - * * Note that doing so invalidates the hash computed by prior calls * to g_icon_hash(). - * * * Since: 2.18 */ diff --git a/glib/docs.c b/glib/docs.c index ac57f1226..2b14de15c 100644 --- a/glib/docs.c +++ b/glib/docs.c @@ -409,11 +409,9 @@ * for scanning and printing values of type #gint64 or #guint64. * It is a string literal. * - * - * Some platforms do not support printing 64 bit integers, even - * though the types are supported. On such platforms #G_GINT64_MODIFIER + * Some platforms do not support printing 64-bit integers, even + * though the types are supported. On such platforms %G_GINT64_MODIFIER * is not defined. - * * * Since: 2.4 */ @@ -424,20 +422,18 @@ * This is the platform dependent conversion specifier for scanning * and printing values of type #gint64. See also #G_GINT16_FORMAT. * - * - * Some platforms do not support scanning and printing 64 bit integers, - * even though the types are supported. On such platforms #G_GINT64_FORMAT - * is not defined. Note that scanf() may not support 64 bit integers, even - * if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() + * Some platforms do not support scanning and printing 64-bit integers, + * even though the types are supported. On such platforms %G_GINT64_FORMAT + * is not defined. Note that scanf() may not support 64-bit integers, even + * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() * is not recommended for parsing anyway; consider using g_ascii_strtoull() * instead. - * */ /** * guint64: * - * An unsigned integer guaranteed to be 64 bits on all platforms. + * An unsigned integer guaranteed to be 64-bits on all platforms. * Values of this type can range from 0 to #G_MAXUINT64 * (= 18,446,744,073,709,551,615). * @@ -457,14 +453,12 @@ * This is the platform dependent conversion specifier for scanning * and printing values of type #guint64. See also #G_GINT16_FORMAT. * - * - * Some platforms do not support scanning and printing 64 bit integers, - * even though the types are supported. On such platforms #G_GUINT64_FORMAT - * is not defined. Note that scanf() may not support 64 bit integers, even - * if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() + * Some platforms do not support scanning and printing 64-bit integers, + * even though the types are supported. On such platforms %G_GUINT64_FORMAT + * is not defined. Note that scanf() may not support 64-bit integers, even + * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() * is not recommended for parsing anyway; consider using g_ascii_strtoull() * instead. - * */ /** @@ -498,7 +492,7 @@ * The minimum positive value which can be held in a #gfloat. * * If you are interested in the smallest value which can be held - * in a #gfloat, use -G_MAXFLOAT. + * in a #gfloat, use -%G_MAXFLOAT. */ /** @@ -520,7 +514,7 @@ * The minimum positive value which can be held in a #gdouble. * * If you are interested in the smallest value which can be held - * in a #gdouble, use -G_MAXDOUBLE. + * in a #gdouble, use -%G_MAXDOUBLE. */ /** @@ -535,8 +529,8 @@ * An unsigned integer type of the result of the sizeof operator, * corresponding to the size_t type defined in C99. * This type is wide enough to hold the numeric value of a pointer, - * so it is usually 32bit wide on a 32bit platform and 64bit wide - * on a 64bit platform. Values of this type can range from 0 to + * so it is usually 32 bit wide on a 32-bit platform and 64 bit wide + * on a 64-bit platform. Values of this type can range from 0 to * #G_MAXSIZE. * * To print or scan values of this type, use @@ -815,7 +809,7 @@ * Extracts a #gsize from a pointer. The #gsize must have * been stored in the pointer with GSIZE_TO_POINTER(). */ - + /* Byte order {{{1 */ /** @@ -1419,7 +1413,7 @@ * * Returns: @val converted to the opposite byte order */ - + /* Numerical Definitions {{{1 */ /** @@ -1518,7 +1512,7 @@ * * Multiplying the base 2 exponent by this number yields the base 10 exponent. */ - + /* Macros {{{1 */ /** @@ -1710,8 +1704,8 @@ * macro will not work on an array allocated on the heap, only static * arrays or arrays on the stack. */ - -/* Miscellaneous Macros {{{1 */ + +/ * Miscellaneous Macros {{{1 */ /** * SECTION:macros_misc @@ -1727,7 +1721,7 @@ * * This macro is used to export function prototypes so they can be linked * with an external version when no inlining is performed. The file which - * implements the functions should define G_IMPLEMENTS_INLINES + * implements the functions should define %G_IMPLEMENTS_INLINES * before including the headers which contain %G_INLINE_FUNC declarations. * Since inlining is very compiler-dependent using these macros correctly * is very difficult. Their use is strongly discouraged. @@ -1755,7 +1749,7 @@ * G_BEGIN_DECLS: * * Used (along with #G_END_DECLS) to bracket header files. If the - * compiler in use is a C++ compiler, adds extern "C" + * compiler in use is a C++ compiler, adds extern "C" * around the header. */ @@ -1763,7 +1757,7 @@ * G_END_DECLS: * * Used (along with #G_BEGIN_DECLS) to bracket header files. If the - * compiler in use is a C++ compiler, adds extern "C" + * compiler in use is a C++ compiler, adds extern "C" * around the header. */ @@ -1804,7 +1798,7 @@ * @identifier2: an identifier * * Yields a new preprocessor pasted identifier - * identifier1identifier2 from its expanded + * @identifier1identifier2 from its expanded * arguments @identifier1 and @identifier2. For example, * the following code: * |[ @@ -1828,18 +1822,14 @@ * G_STATIC_ASSERT: * @expr: a constant expression * - * The G_STATIC_ASSERT macro lets the programmer check + * The G_STATIC_ASSERT() macro lets the programmer check * a condition at compile time, the condition needs to * be compile time computable. The macro can be used in - * any place where a typedef is valid. + * any place where a typedef is valid. * - * - * A typedef is generally allowed in - * exactly the same places that a variable declaration is - * allowed. For this reason, you should not use - * G_STATIC_ASSERT in the middle of - * blocks of code. - * + * A typedef is generally allowed in exactly the same places that + * a variable declaration is allowed. For this reason, you should + * not use G_STATIC_ASSERT() in the middle of blocks of code. * * The macro should only be used once per source code line. * @@ -1850,15 +1840,14 @@ * G_STATIC_ASSERT_EXPR: * @expr: a constant expression * - * The G_STATIC_ASSERT_EXPR macro lets the programmer check + * The G_STATIC_ASSERT_EXPR() macro lets the programmer check * a condition at compile time. The condition needs to be * compile time computable. * - * Unlike G_STATIC_ASSERT, this macro - * evaluates to an expression and, as such, can be used in - * the middle of other expressions. Its value should be - * ignored. This can be accomplished by placing it as - * the first argument of a comma expression. + * Unlike G_STATIC_ASSERT(), this macro evaluates to an expression + * and, as such, can be used in the middle of other expressions. + * Its value should be ignored. This can be accomplished by placing + * it as the first argument of a comma expression. * * |[ * #define ADD_ONE_TO_INT(x) \ @@ -1871,41 +1860,37 @@ /** * G_GNUC_EXTENSION: * - * Expands to __extension__ when gcc - * is used as the compiler. This simply tells gcc not - * to warn about the following non-standard code when compiling with the - * option. + * Expands to __extension__ when gcc is used as the compiler. This simply + * tells gcc not to warn about the following non-standard code when compiling + * with the option. */ /** * G_GNUC_CONST: * - * Expands to the GNU C const function attribute if - * the compiler is gcc. Declaring a function as const - * enables better optimization of calls to the function. A const function - * doesn't examine any values except its parameters, and has no effects - * except its return value. + * Expands to the GNU C const function attribute if the compiler is gcc. + * Declaring a function as const enables better optimization of calls to + * the function. A const function doesn't examine any values except its + * parameters, and has no effects except its return value. * * Place the attribute after the declaration, just before the semicolon. * * See the GNU C documentation for more details. * - * * A function that has pointer arguments and examines the data pointed to - * must not be declared const. Likewise, a function - * that calls a non-const function usually must not be const. It doesn't - * make sense for a const function to return void. - * + * must not be declared const. Likewise, a function that calls a non-const + * function usually must not be const. It doesn't make sense for a const + * function to return void. */ /** * G_GNUC_PURE: * - * Expands to the GNU C pure function attribute if the - * compiler is gcc. Declaring a function as pure enables - * better optimization of calls to the function. A pure function has no - * effects except its return value and the return value depends only on - * the parameters and/or global variables. + * Expands to the GNU C pure function attribute if the compiler is gcc. + * Declaring a function as pure enables better optimization of calls to + * the function. A pure function has no effects except its return value + * and the return value depends only on the parameters and/or global + * variables. * * Place the attribute after the declaration, just before the semicolon. * @@ -1915,12 +1900,11 @@ /** * G_GNUC_MALLOC: * - * Expands to the GNU C malloc function attribute if the - * compiler is gcc. Declaring a function as malloc enables - * better optimization of the function. A function can have the malloc - * attribute if it returns a pointer which is guaranteed to not alias with - * any other pointer when the function returns (in practice, this means newly - * allocated memory). + * Expands to the GNU C malloc function attribute if the compiler is gcc. + * Declaring a function as malloc enables better optimization of the function. + * A function can have the malloc attribute if it returns a pointer which is + * guaranteed to not alias with any other pointer when the function returns + * (in practice, this means newly allocated memory). * * Place the attribute after the declaration, just before the semicolon. * @@ -1933,10 +1917,10 @@ * G_GNUC_ALLOC_SIZE: * @x: the index of the argument specifying the allocation size * - * Expands to the GNU C alloc_size function attribute - * if the compiler is a new enough gcc. This attribute - * tells the compiler that the function returns a pointer to memory of a - * size that is specified by the @xth function parameter. + * Expands to the GNU C alloc_size function attribute if the compiler is + * a new enough gcc. This attribute tells the compiler that the function + * returns a pointer to memory of a size that is specified by the @xth + * function parameter. * * Place the attribute after the function declaration, just before the * semicolon. @@ -1951,10 +1935,10 @@ * @x: the index of the argument specifying one factor of the allocation size * @y: the index of the argument specifying the second factor of the allocation size * - * Expands to the GNU C alloc_size function attribute - * if the compiler is a new enough gcc. This attribute - * tells the compiler that the function returns a pointer to memory of a - * size that is specified by the product of two function parameters. + * Expands to the GNU C alloc_size function attribute if the compiler is a + * new enough gcc. This attribute tells the compiler that the function returns + * a pointer to memory of a size that is specified by the product of two + * function parameters. * * Place the attribute after the function declaration, just before the * semicolon. @@ -1967,11 +1951,10 @@ /** * G_GNUC_DEPRECATED: * - * Expands to the GNU C deprecated attribute if the - * compiler is gcc. It can be used to mark typedefs, - * variables and functions as deprecated. When called with the - * option, the compiler will - * generate warnings when deprecated interfaces are used. + * Expands to the GNU C deprecated attribute if the compiler is gcc. + * It can be used to mark typedefs, variables and functions as deprecated. + * When called with the option, + * gcc will generate warnings when deprecated interfaces are used. * * Place the attribute after the declaration, just before the semicolon. * @@ -1986,8 +1969,8 @@ * such as the name of a function * * Like %G_GNUC_DEPRECATED, but names the intended replacement for the - * deprecated symbol if the version of gcc in use is - * new enough to support custom deprecation messages. + * deprecated symbol if the version of gcc in use is new enough to support + * custom deprecation messages. * * Place the attribute after the declaration, just before the semicolon. * @@ -2003,12 +1986,11 @@ /** * G_GNUC_BEGIN_IGNORE_DEPRECATIONS: * - * Tells gcc (if it is a new enough version) to - * temporarily stop emitting warnings when functions marked with - * %G_GNUC_DEPRECATED or %G_GNUC_DEPRECATED_FOR are called. This is - * useful for when you have one deprecated function calling another - * one, or when you still have regression tests for deprecated - * functions. + * Tells gcc (if it is a new enough version) to temporarily stop emitting + * warnings when functions marked with %G_GNUC_DEPRECATED or + * %G_GNUC_DEPRECATED_FOR are called. This is useful for when you have + * one deprecated function calling another one, or when you still have + * regression tests for deprecated functions. * * Use %G_GNUC_END_IGNORE_DEPRECATIONS to begin warning again. (If you * are not compiling with -Wdeprecated-declarations @@ -2024,8 +2006,8 @@ * G_GNUC_END_IGNORE_DEPRECATIONS: * * Undoes the effect of %G_GNUC_BEGIN_IGNORE_DEPRECATIONS, telling - * gcc to begin outputting warnings again - * (assuming those warnings had been enabled to begin with). + * gcc to begin outputting warnings again (assuming those warnings + * had been enabled to begin with). * * This macro can be used either inside or outside of a function body, * but must appear on a line by itself. @@ -2049,8 +2031,8 @@ * @f: the name of the function that this function was deprecated for * * This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark - * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it is - * meant to be portable across different compilers and must be placed + * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it + * is meant to be portable across different compilers and must be placed * before the function declaration. * * Since: 2.32 @@ -2079,10 +2061,9 @@ /** * G_GNUC_NORETURN: * - * Expands to the GNU C noreturn function attribute - * if the compiler is gcc. It is used for declaring - * functions which never return. It enables optimization of the function, - * and avoids possible compiler warnings. + * Expands to the GNU C noreturn function attribute if the compiler is gcc. + * It is used for declaring functions which never return. It enables + * optimization of the function, and avoids possible compiler warnings. * * Place the attribute after the declaration, just before the semicolon. * @@ -2092,10 +2073,9 @@ /** * G_GNUC_UNUSED: * - * Expands to the GNU C unused function attribute if - * the compiler is gcc. It is used for declaring - * functions and arguments which may never be used. It avoids possible compiler - * warnings. + * Expands to the GNU C unused function attribute if the compiler is gcc. + * It is used for declaring functions and arguments which may never be used. + * It avoids possible compiler warnings. * * For functions, place the attribute after the declaration, just before the * semicolon. For arguments, place the attribute at the beginning of the @@ -2115,11 +2095,10 @@ * format string (The arguments are numbered from 1) * @arg_idx: the index of the first of the format arguments * - * Expands to the GNU C format function attribute - * if the compiler is gcc. This is used for declaring - * functions which take a variable number of arguments, with the same - * syntax as printf(). It allows the compiler to type-check the arguments - * passed to the function. + * Expands to the GNU C format function attribute if the compiler is gcc. + * This is used for declaring functions which take a variable number of + * arguments, with the same syntax as printf(). It allows the compiler + * to type-check the arguments passed to the function. * * Place the attribute after the function declaration, just before the * semicolon. @@ -2140,25 +2119,25 @@ * the format string (The arguments are numbered from 1) * @arg_idx: the index of the first of the format arguments * - * Expands to the GNU C format function attribute - * if the compiler is gcc. This is used for declaring - * functions which take a variable number of arguments, with the same - * syntax as scanf(). It allows the compiler to type-check the arguments - * passed to the function. See the GNU C documentation for details. + * Expands to the GNU C format function attribute if the compiler is gcc. + * This is used for declaring functions which take a variable number of + * arguments, with the same syntax as scanf(). It allows the compiler + * to type-check the arguments passed to the function. + * + * See the GNU C documentation for details. */ /** * G_GNUC_FORMAT: * @arg_idx: the index of the argument * - * Expands to the GNU C format_arg function attribute - * if the compiler is gcc. This function attribute - * specifies that a function takes a format string for a printf(), - * scanf(), strftime() or strfmon() style function and modifies it, - * so that the result can be passed to a printf(), scanf(), strftime() - * or strfmon() style function (with the remaining arguments to the - * format function the same as they would have been for the unmodified - * string). + * Expands to the GNU C format_arg function attribute if the compiler + * is gcc. This function attribute specifies that a function takes a + * format string for a printf(), scanf(), strftime() or strfmon() style + * function and modifies it, so that the result can be passed to a printf(), + * scanf(), strftime() or strfmon() style function (with the remaining + * arguments to the format function the same as they would have been + * for the unmodified string). * * Place the attribute after the function declaration, just before the * semicolon. @@ -2173,9 +2152,8 @@ /** * G_GNUC_NULL_TERMINATED: * - * Expands to the GNU C sentinel function attribute - * if the compiler is gcc, or "" if it isn't. This - * function attribute only applies to variadic functions and instructs + * Expands to the GNU C sentinel function attribute if the compiler is gcc. + * This function attribute only applies to variadic functions and instructs * the compiler to check that the argument list is terminated with an * explicit %NULL. * @@ -2189,10 +2167,9 @@ /** * G_GNUC_WARN_UNUSED_RESULT: * - * Expands to the GNU C warn_unused_result function - * attribute if the compiler is gcc, or "" if it isn't. - * This function attribute makes the compiler emit a warning if the result - * of a function call is ignored. + * Expands to the GNU C warn_unused_result function attribute if the compiler + * is gcc. This function attribute makes the compiler emit a warning if the + * result of a function call is ignored. * * Place the attribute after the declaration, just before the semicolon. * @@ -2204,30 +2181,28 @@ /** * G_GNUC_FUNCTION: * - * Expands to "" on all modern compilers, and to - * __FUNCTION__ on gcc version 2.x. - * Don't use it. + * Expands to "" on all modern compilers, and to __FUNCTION__ on gcc + * version 2.x. Don't use it. * - * Deprecated: 2.16: Use #G_STRFUNC instead + * Deprecated: 2.16: Use G_STRFUNC() instead */ /** * G_GNUC_PRETTY_FUNCTION: * - * Expands to "" on all modern compilers, and to - * __PRETTY_FUNCTION__ on gcc - * version 2.x. Don't use it. + * Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__ + * on gcc version 2.x. Don't use it. * - * Deprecated: 2.16: Use #G_STRFUNC instead + * Deprecated: 2.16: Use G_STRFUNC() instead */ /** * G_GNUC_NO_INSTRUMENT: * - * Expands to the GNU C no_instrument_function function - * attribute if the compiler is gcc. Functions with this - * attribute will not be instrumented for profiling, when the compiler is - * called with the option. + * Expands to the GNU C no_instrument_function function attribute if the + * compiler is gcc. Functions with this attribute will not be instrumented + * for profiling, when the compiler is called with the + * option. * * Place the attribute after the declaration, just before the semicolon. * @@ -2244,8 +2219,8 @@ * details. * * When using a compiler that supports the GNU C hidden visibility attribute, - * this macro expands to __attribute__((visibility("hidden"))). - * When using the Sun Studio compiler, it expands to __hidden. + * this macro expands to __attribute__((visibility("hidden"))). + * When using the Sun Studio compiler, it expands to __hidden. * * Note that for portability, the attribute should be placed before the * function declaration. While GCC allows the macro after the declaration, @@ -2265,10 +2240,10 @@ /** * G_GNUC_MAY_ALIAS: * - * Expands to the GNU C may_alias type attribute - * if the compiler is gcc. Types with this attribute - * will not be subjected to type-based alias analysis, but are assumed - * to alias with any other type, just like char. + * Expands to the GNU C may_alias type attribute if the compiler is gcc. + * Types with this attribute will not be subjected to type-based alias + * analysis, but are assumed to alias with any other type, just like char. + * * See the GNU C documentation for details. * * Since: 2.14 @@ -2381,6 +2356,6 @@ * * Since: 2.6 */ - -/* Epilogue {{{1 */ + + /* Epilogue {{{1 */ /* vim: set foldmethod=marker: */ diff --git a/glib/garray.c b/glib/garray.c index 9640e1ef8..7c2ad136b 100644 --- a/glib/garray.c +++ b/glib/garray.c @@ -46,7 +46,7 @@ * SECTION:arrays * @title: Arrays * @short_description: arrays of arbitrary elements which grow - * automatically as elements are added + * automatically as elements are added * * Arrays are similar to standard C arrays, except that they grow * automatically as elements are added. @@ -84,7 +84,7 @@ * g_array_free (garray, TRUE); * * - **/ + */ #define MIN_ARRAY_SIZE 16 @@ -93,12 +93,12 @@ typedef struct _GRealArray GRealArray; /** * GArray: * @data: a pointer to the element data. The data may be moved as - * elements are added to the #GArray. + * elements are added to the #GArray. * @len: the number of elements in the #GArray not including the - * possible terminating zero element. + * possible terminating zero element. * - * Contains the public fields of an Array. - **/ + * Contains the public fields of a #GArray. + */ struct _GRealArray { guint8 *data; @@ -113,9 +113,9 @@ struct _GRealArray /** * g_array_index: - * @a: a #GArray. - * @t: the type of the elements. - * @i: the index of the element to return. + * @a: a #GArray + * @t: the type of the elements + * @i: the index of the element to return * * Returns the element of a #GArray at the given index. The return * value is cast to the given type. @@ -130,38 +130,38 @@ struct _GRealArray * * * - * Returns: the element of the #GArray at the index given by @i. - **/ + * Returns: the element of the #GArray at the index given by @i + */ #define g_array_elt_len(array,i) ((array)->elt_size * (i)) #define g_array_elt_pos(array,i) ((array)->data + g_array_elt_len((array),(i))) -#define g_array_elt_zero(array, pos, len) \ +#define g_array_elt_zero(array, pos, len) \ (memset (g_array_elt_pos ((array), pos), 0, g_array_elt_len ((array), len))) -#define g_array_zero_terminate(array) G_STMT_START{ \ - if ((array)->zero_terminated) \ - g_array_elt_zero ((array), (array)->len, 1); \ +#define g_array_zero_terminate(array) G_STMT_START{ \ + if ((array)->zero_terminated) \ + g_array_elt_zero ((array), (array)->len, 1); \ }G_STMT_END static guint g_nearest_pow (gint num) G_GNUC_CONST; static void g_array_maybe_expand (GRealArray *array, - gint len); + gint len); /** * g_array_new: * @zero_terminated: %TRUE if the array should have an extra element at - * the end which is set to 0. + * the end which is set to 0 * @clear_: %TRUE if #GArray elements should be automatically cleared - * to 0 when they are allocated. - * @element_size: the size of each element in bytes. + * to 0 when they are allocated + * @element_size: the size of each element in bytes * * Creates a new #GArray with a reference count of 1. * - * Returns: the new #GArray. - **/ + * Returns: the new #GArray + */ GArray* g_array_new (gboolean zero_terminated, - gboolean clear, - guint elt_size) + gboolean clear, + guint elt_size) { g_return_val_if_fail (elt_size > 0, NULL); @@ -171,23 +171,24 @@ g_array_new (gboolean zero_terminated, /** * g_array_sized_new: * @zero_terminated: %TRUE if the array should have an extra element at - * the end with all bits cleared. + * the end with all bits cleared * @clear_: %TRUE if all bits in the array should be cleared to 0 on - * allocation. - * @element_size: size of each element in the array. - * @reserved_size: number of elements preallocated. + * allocation + * @element_size: size of each element in the array + * @reserved_size: number of elements preallocated * * Creates a new #GArray with @reserved_size elements preallocated and * a reference count of 1. This avoids frequent reallocation, if you * are going to add many elements to the array. Note however that the * size of the array is still 0. * - * Returns: the new #GArray. - **/ -GArray* g_array_sized_new (gboolean zero_terminated, - gboolean clear, - guint elt_size, - guint reserved_size) + * Returns: the new #GArray + */ +GArray* +g_array_sized_new (gboolean zero_terminated, + gboolean clear, + guint elt_size, + guint reserved_size) { GRealArray *array; @@ -243,15 +244,15 @@ g_array_set_clear_func (GArray *array, /** * g_array_ref: - * @array: A #GArray. + * @array: A #GArray * - * Atomically increments the reference count of @array by one. This - * function is MT-safe and may be called from any thread. + * Atomically increments the reference count of @array by one. + * This function is MT-safe and may be called from any thread. * - * Returns: The passed in #GArray. + * Returns: The passed in #GArray * * Since: 2.22 - **/ + */ GArray * g_array_ref (GArray *array) { @@ -273,7 +274,7 @@ static gchar *array_free (GRealArray *, ArrayFreeFlags); /** * g_array_unref: - * @array: A #GArray. + * @array: A #GArray * * Atomically decrements the reference count of @array by one. If the * reference count drops to 0, all memory allocated by the array is @@ -281,7 +282,7 @@ static gchar *array_free (GRealArray *, ArrayFreeFlags); * thread. * * Since: 2.22 - **/ + */ void g_array_unref (GArray *array) { @@ -294,14 +295,14 @@ g_array_unref (GArray *array) /** * g_array_get_element_size: - * @array: A #GArray. + * @array: A #GArray * * Gets the size of the elements in @array. * - * Returns: Size of each element, in bytes. + * Returns: Size of each element, in bytes * * Since: 2.22 - **/ + */ guint g_array_get_element_size (GArray *array) { @@ -314,8 +315,8 @@ g_array_get_element_size (GArray *array) /** * g_array_free: - * @array: a #GArray. - * @free_segment: if %TRUE the actual element data is freed as well. + * @array: a #GArray + * @free_segment: if %TRUE the actual element data is freed as well * * Frees the memory allocated for the #GArray. If @free_segment is * %TRUE it frees the memory block holding the elements as well and @@ -325,15 +326,15 @@ g_array_get_element_size (GArray *array) * is greater than one, the #GArray wrapper is preserved but the size * of @array will be set to zero. * - * If array elements contain dynamically-allocated memory, - * they should be freed separately. + * If array elements contain dynamically-allocated memory, they should + * be freed separately. * * Returns: the element data if @free_segment is %FALSE, otherwise - * %NULL. The element data should be freed using g_free(). - **/ + * %NULL. The element data should be freed using g_free(). + */ gchar* g_array_free (GArray *farray, - gboolean free_segment) + gboolean free_segment) { GRealArray *array = (GRealArray*) farray; ArrayFreeFlags flags; @@ -387,32 +388,32 @@ array_free (GRealArray *array, /** * g_array_append_vals: - * @array: a #GArray. - * @data: a pointer to the elements to append to the end of the array. - * @len: the number of elements to append. + * @array: a #GArray + * @data: a pointer to the elements to append to the end of the array + * @len: the number of elements to append * * Adds @len elements onto the end of the array. * - * Returns: the #GArray. - **/ + * Returns: the #GArray + */ /** * g_array_append_val: - * @a: a #GArray. - * @v: the value to append to the #GArray. + * @a: a #GArray + * @v: the value to append to the #GArray * * Adds the value on to the end of the array. The array will grow in * size automatically if necessary. * - * g_array_append_val() is a macro which uses a reference - * to the value parameter @v. This means that you cannot use it with - * literal values such as "27". You must use variables. + * g_array_append_val() is a macro which uses a reference to the value + * parameter @v. This means that you cannot use it with literal values + * such as "27". You must use variables. * - * Returns: the #GArray. - **/ + * Returns: the #GArray + */ GArray* g_array_append_vals (GArray *farray, - gconstpointer data, - guint len) + gconstpointer data, + guint len) { GRealArray *array = (GRealArray*) farray; @@ -421,7 +422,7 @@ g_array_append_vals (GArray *farray, g_array_maybe_expand (array, len); memcpy (g_array_elt_pos (array, array->len), data, - g_array_elt_len (array, len)); + g_array_elt_len (array, len)); array->len += len; @@ -432,10 +433,9 @@ g_array_append_vals (GArray *farray, /** * g_array_prepend_vals: - * @array: a #GArray. - * @data: a pointer to the elements to prepend to the start of the - * array. - * @len: the number of elements to prepend. + * @array: a #GArray + * @data: a pointer to the elements to prepend to the start of the array + * @len: the number of elements to prepend * * Adds @len elements onto the start of the array. * @@ -443,12 +443,12 @@ g_array_append_vals (GArray *farray, * existing elements in the array have to be moved to make space for * the new elements. * - * Returns: the #GArray. - **/ + * Returns: the #GArray + */ /** * g_array_prepend_val: - * @a: a #GArray. - * @v: the value to prepend to the #GArray. + * @a: a #GArray + * @v: the value to prepend to the #GArray * * Adds the value on to the start of the array. The array will grow in * size automatically if necessary. @@ -457,16 +457,16 @@ g_array_append_vals (GArray *farray, * existing elements in the array have to be moved to make space for * the new element. * - * g_array_prepend_val() is a macro which uses a reference - * to the value parameter @v. This means that you cannot use it with - * literal values such as "27". You must use variables. + * g_array_prepend_val() is a macro which uses a reference to the value + * parameter @v. This means that you cannot use it with literal values + * such as "27". You must use variables. * - * Returns: the #GArray. - **/ + * Returns: the #GArray + */ GArray* g_array_prepend_vals (GArray *farray, - gconstpointer data, - guint len) + gconstpointer data, + guint len) { GRealArray *array = (GRealArray*) farray; @@ -488,34 +488,34 @@ g_array_prepend_vals (GArray *farray, /** * g_array_insert_vals: - * @array: a #GArray. - * @index_: the index to place the elements at. - * @data: a pointer to the elements to insert. - * @len: the number of elements to insert. + * @array: a #GArray + * @index_: the index to place the elements at + * @data: a pointer to the elements to insert + * @len: the number of elements to insert * * Inserts @len elements into a #GArray at the given index. * - * Returns: the #GArray. - **/ + * Returns: the #GArray + */ /** * g_array_insert_val: - * @a: a #GArray. - * @i: the index to place the element at. - * @v: the value to insert into the array. + * @a: a #GArray + * @i: the index to place the element at + * @v: the value to insert into the array * * Inserts an element into an array at the given index. * - * g_array_insert_val() is a macro which uses a reference - * to the value parameter @v. This means that you cannot use it with - * literal values such as "27". You must use variables. + * g_array_insert_val() is a macro which uses a reference to the value + * parameter @v. This means that you cannot use it with literal values + * such as "27". You must use variables. * - * Returns: the #GArray. - **/ + * Returns: the #GArray + */ GArray* g_array_insert_vals (GArray *farray, - guint index_, - gconstpointer data, - guint len) + guint index_, + gconstpointer data, + guint len) { GRealArray *array = (GRealArray*) farray; @@ -538,17 +538,17 @@ g_array_insert_vals (GArray *farray, /** * g_array_set_size: - * @array: a #GArray. - * @length: the new size of the #GArray. + * @array: a #GArray + * @length: the new size of the #GArray * * Sets the size of the array, expanding it if necessary. If the array * was created with @clear_ set to %TRUE, the new elements are set to 0. * - * Returns: the #GArray. - **/ + * Returns: the #GArray + */ GArray* g_array_set_size (GArray *farray, - guint length) + guint length) { GRealArray *array = (GRealArray*) farray; @@ -559,7 +559,7 @@ g_array_set_size (GArray *farray, g_array_maybe_expand (array, length - array->len); if (array->clear) - g_array_elt_zero (array, array->len, length - array->len); + g_array_elt_zero (array, array->len, length - array->len); } else if (length < array->len) g_array_remove_range (farray, length, array->len - length); @@ -573,17 +573,17 @@ g_array_set_size (GArray *farray, /** * g_array_remove_index: - * @array: a #GArray. - * @index_: the index of the element to remove. + * @array: a #GArray + * @index_: the index of the element to remove * * Removes the element at the given index from a #GArray. The following * elements are moved down one place. * - * Returns: the #GArray. - **/ + * Returns: the #GArray + */ GArray* g_array_remove_index (GArray *farray, - guint index_) + guint index_) { GRealArray* array = (GRealArray*) farray; @@ -611,19 +611,19 @@ g_array_remove_index (GArray *farray, /** * g_array_remove_index_fast: - * @array: a @GArray. - * @index_: the index of the element to remove. + * @array: a @GArray + * @index_: the index of the element to remove * * Removes the element at the given index from a #GArray. The last * element in the array is used to fill in the space, so this function * does not preserve the order of the #GArray. But it is faster than * g_array_remove_index(). * - * Returns: the #GArray. - **/ + * Returns: the #GArray + */ GArray* g_array_remove_index_fast (GArray *farray, - guint index_) + guint index_) { GRealArray* array = (GRealArray*) farray; @@ -651,17 +651,17 @@ g_array_remove_index_fast (GArray *farray, /** * g_array_remove_range: - * @array: a @GArray. - * @index_: the index of the first element to remove. - * @length: the number of elements to remove. + * @array: a @GArray + * @index_: the index of the first element to remove + * @length: the number of elements to remove * * Removes the given number of elements starting at the given index * from a #GArray. The following elements are moved to close the gap. * - * Returns: the #GArray. + * Returns: the #GArray * * Since: 2.4 - **/ + */ GArray* g_array_remove_range (GArray *farray, guint index_, @@ -697,8 +697,8 @@ g_array_remove_range (GArray *farray, /** * g_array_sort: - * @array: a #GArray. - * @compare_func: comparison function. + * @array: a #GArray + * @compare_func: comparison function * * Sorts a #GArray using @compare_func which should be a qsort()-style * comparison function (returns less than zero for first arg is less @@ -706,10 +706,10 @@ g_array_remove_range (GArray *farray, * greater than second arg). * * This is guaranteed to be a stable sort since version 2.32. - **/ + */ void g_array_sort (GArray *farray, - GCompareFunc compare_func) + GCompareFunc compare_func) { GRealArray *array = (GRealArray*) farray; @@ -717,17 +717,17 @@ g_array_sort (GArray *farray, /* Don't use qsort as we want a guaranteed stable sort */ g_qsort_with_data (array->data, - array->len, - array->elt_size, - (GCompareDataFunc)compare_func, - NULL); + array->len, + array->elt_size, + (GCompareDataFunc)compare_func, + NULL); } /** * g_array_sort_with_data: - * @array: a #GArray. - * @compare_func: comparison function. - * @user_data: data to pass to @compare_func. + * @array: a #GArray + * @compare_func: comparison function + * @user_data: data to pass to @compare_func * * Like g_array_sort(), but the comparison function receives an extra * user data argument. @@ -737,21 +737,21 @@ g_array_sort (GArray *farray, * There used to be a comment here about making the sort stable by * using the addresses of the elements in the comparison function. * This did not actually work, so any such code should be removed. - **/ + */ void g_array_sort_with_data (GArray *farray, - GCompareDataFunc compare_func, - gpointer user_data) + GCompareDataFunc compare_func, + gpointer user_data) { GRealArray *array = (GRealArray*) farray; g_return_if_fail (array != NULL); g_qsort_with_data (array->data, - array->len, - array->elt_size, - compare_func, - user_data); + array->len, + array->elt_size, + compare_func, + user_data); } /* Returns the smallest power of 2 greater than n, or n if @@ -770,10 +770,10 @@ g_nearest_pow (gint num) static void g_array_maybe_expand (GRealArray *array, - gint len) + gint len) { guint want_alloc = g_array_elt_len (array, array->len + len + - array->zero_terminated); + array->zero_terminated); if (want_alloc > array->alloc) { @@ -793,16 +793,16 @@ g_array_maybe_expand (GRealArray *array, * SECTION:arrays_pointer * @title: Pointer Arrays * @short_description: arrays of pointers to any type of data, which - * grow automatically as new elements are added + * grow automatically as new elements are added * * Pointer Arrays are similar to Arrays but are used only for storing * pointers. * - * If you remove elements from the array, elements at the - * end of the array are moved into the space previously occupied by the - * removed element. This means that you should not rely on the index of - * particular elements remaining the same. You should also be careful - * when deleting elements while iterating over the array. + * If you remove elements from the array, elements at the end of the + * array are moved into the space previously occupied by the removed + * element. This means that you should not rely on the index of particular + * elements remaining the same. You should also be careful when deleting + * elements while iterating over the array. * * To create a pointer array, use g_ptr_array_new(). * @@ -842,11 +842,11 @@ typedef struct _GRealPtrArray GRealPtrArray; /** * GPtrArray: * @pdata: points to the array of pointers, which may be moved when the - * array grows. - * @len: number of pointers in the array. + * array grows + * @len: number of pointers in the array * * Contains the public fields of a pointer array. - **/ + */ struct _GRealPtrArray { gpointer *pdata; @@ -858,28 +858,27 @@ struct _GRealPtrArray /** * g_ptr_array_index: - * @array: a #GPtrArray. - * @index_: the index of the pointer to return. + * @array: a #GPtrArray + * @index_: the index of the pointer to return * * Returns the pointer at the given index of the pointer array. * - * - * This does not perform bounds checking on the given @index_, so you are - * responsible for checking it against the array length. + * This does not perform bounds checking on the given @index_, + * so you are responsible for checking it against the array length. * - * Returns: the pointer at the given index. - **/ + * Returns: the pointer at the given index + */ static void g_ptr_array_maybe_expand (GRealPtrArray *array, - gint len); + gint len); /** * g_ptr_array_new: * * Creates a new #GPtrArray with a reference count of 1. * - * Returns: the new #GPtrArray. - **/ + * Returns: the new #GPtrArray + */ GPtrArray* g_ptr_array_new (void) { @@ -888,15 +887,15 @@ g_ptr_array_new (void) /** * g_ptr_array_sized_new: - * @reserved_size: number of pointers preallocated. + * @reserved_size: number of pointers preallocated * * Creates a new #GPtrArray with @reserved_size pointers preallocated * and a reference count of 1. This avoids frequent reallocation, if * you are going to add many pointers to the array. Note however that * the size of the array is still 0. * - * Returns: the new #GPtrArray. - **/ + * Returns: the new #GPtrArray + */ GPtrArray* g_ptr_array_sized_new (guint reserved_size) { @@ -916,17 +915,18 @@ g_ptr_array_sized_new (guint reserved_size) /** * g_ptr_array_new_with_free_func: - * @element_free_func: (allow-none): A function to free elements with destroy @array or %NULL. + * @element_free_func: (allow-none): A function to free elements with + * destroy @array or %NULL * - * Creates a new #GPtrArray with a reference count of 1 and use @element_free_func - * for freeing each element when the array is destroyed either via - * g_ptr_array_unref(), when g_ptr_array_free() is called with @free_segment - * set to %TRUE or when removing elements. + * Creates a new #GPtrArray with a reference count of 1 and use + * @element_free_func for freeing each element when the array is destroyed + * either via g_ptr_array_unref(), when g_ptr_array_free() is called with + * @free_segment set to %TRUE or when removing elements. * - * Returns: A new #GPtrArray. + * Returns: A new #GPtrArray * * Since: 2.22 - **/ + */ GPtrArray * g_ptr_array_new_with_free_func (GDestroyNotify element_free_func) { @@ -939,21 +939,22 @@ g_ptr_array_new_with_free_func (GDestroyNotify element_free_func) /** * g_ptr_array_new_full: - * @reserved_size: number of pointers preallocated. - * @element_free_func: (allow-none): A function to free elements with destroy @array or %NULL. + * @reserved_size: number of pointers preallocated + * @element_free_func: (allow-none): A function to free elements with + * destroy @array or %NULL * * Creates a new #GPtrArray with @reserved_size pointers preallocated * and a reference count of 1. This avoids frequent reallocation, if * you are going to add many pointers to the array. Note however that * the size of the array is still 0. It also set @element_free_func * for freeing each element when the array is destroyed either via - * g_ptr_array_unref(), when g_ptr_array_free() is called with @free_segment - * set to %TRUE or when removing elements. + * g_ptr_array_unref(), when g_ptr_array_free() is called with + * @free_segment set to %TRUE or when removing elements. * - * Returns: A new #GPtrArray. + * Returns: A new #GPtrArray * * Since: 2.30 - **/ + */ GPtrArray * g_ptr_array_new_full (guint reserved_size, GDestroyNotify element_free_func) @@ -967,15 +968,16 @@ g_ptr_array_new_full (guint reserved_size, /** * g_ptr_array_set_free_func: - * @array: A #GPtrArray. - * @element_free_func: (allow-none): A function to free elements with destroy @array or %NULL. + * @array: A #GPtrArray + * @element_free_func: (allow-none): A function to free elements with + * destroy @array or %NULL * * Sets a function for freeing each element when @array is destroyed * either via g_ptr_array_unref(), when g_ptr_array_free() is called * with @free_segment set to %TRUE or when removing elements. * * Since: 2.22 - **/ + */ void g_ptr_array_set_free_func (GPtrArray *array, GDestroyNotify element_free_func) @@ -1014,7 +1016,7 @@ static gpointer *ptr_array_free (GPtrArray *, ArrayFreeFlags); /** * g_ptr_array_unref: - * @array: A #GPtrArray. + * @array: A #GPtrArray * * Atomically decrements the reference count of @array by one. If the * reference count drops to 0, the effect is the same as calling @@ -1022,7 +1024,7 @@ static gpointer *ptr_array_free (GPtrArray *, ArrayFreeFlags); * is MT-safe and may be called from any thread. * * Since: 2.22 - **/ + */ void g_ptr_array_unref (GPtrArray *array) { @@ -1035,8 +1037,8 @@ g_ptr_array_unref (GPtrArray *array) /** * g_ptr_array_free: - * @array: a #GPtrArray. - * @free_seg: if %TRUE the actual pointer array is freed as well. + * @array: a #GPtrArray + * @free_seg: if %TRUE the actual pointer array is freed as well * * Frees the memory allocated for the #GPtrArray. If @free_seg is %TRUE * it frees the memory block holding the elements as well. Pass %FALSE @@ -1045,16 +1047,16 @@ g_ptr_array_unref (GPtrArray *array) * is greater than one, the #GPtrArray wrapper is preserved but the * size of @array will be set to zero. * - * If array contents point to dynamically-allocated - * memory, they should be freed separately if @free_seg is %TRUE and no - * #GDestroyNotify function has been set for @array. + * If array contents point to dynamically-allocated memory, they should + * be freed separately if @free_seg is %TRUE and no #GDestroyNotify + * function has been set for @array. * * Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL. - * The pointer array should be freed using g_free(). - **/ + * The pointer array should be freed using g_free(). + */ gpointer* g_ptr_array_free (GPtrArray *farray, - gboolean free_segment) + gboolean free_segment) { GRealPtrArray *array = (GRealPtrArray*) farray; ArrayFreeFlags flags; @@ -1063,7 +1065,9 @@ g_ptr_array_free (GPtrArray *farray, flags = (free_segment ? FREE_SEGMENT : 0); - /* if others are holding a reference, preserve the wrapper but do free/return the data */ + /* if others are holding a reference, preserve the wrapper but + * do free/return the data + */ if (!g_atomic_int_dec_and_test (&array->ref_count)) flags |= PRESERVE_WRAPPER; @@ -1103,7 +1107,7 @@ ptr_array_free (GPtrArray *farray, static void g_ptr_array_maybe_expand (GRealPtrArray *array, - gint len) + gint len) { if ((array->len + len) > array->alloc) { @@ -1119,17 +1123,17 @@ g_ptr_array_maybe_expand (GRealPtrArray *array, /** * g_ptr_array_set_size: - * @array: a #GPtrArray. - * @length: the new length of the pointer array. + * @array: a #GPtrArray + * @length: the new length of the pointer array * * Sets the size of the array. When making the array larger, * newly-added elements will be set to %NULL. When making it smaller, * if @array has a non-%NULL #GDestroyNotify function then it will be * called for the removed elements. - **/ + */ void g_ptr_array_set_size (GPtrArray *farray, - gint length) + gint length) { GRealPtrArray* array = (GRealPtrArray*) farray; @@ -1146,7 +1150,7 @@ g_ptr_array_set_size (GPtrArray *farray, * bitwise zero. It of course is silly not to use memset (..,0,..). */ for (i = array->len; i < length; i++) - array->pdata[i] = NULL; + array->pdata[i] = NULL; } else if (length < array->len) g_ptr_array_remove_range (farray, length, array->len - length); @@ -1156,19 +1160,19 @@ g_ptr_array_set_size (GPtrArray *farray, /** * g_ptr_array_remove_index: - * @array: a #GPtrArray. - * @index_: the index of the pointer to remove. + * @array: a #GPtrArray + * @index_: the index of the pointer to remove * - * Removes the pointer at the given index from the pointer array. The - * following elements are moved down one place. If @array has a - * non-%NULL #GDestroyNotify function it is called for the removed + * Removes the pointer at the given index from the pointer array. + * The following elements are moved down one place. If @array has + * a non-%NULL #GDestroyNotify function it is called for the removed * element. * - * Returns: the pointer which was removed. - **/ + * Returns: the pointer which was removed + */ gpointer g_ptr_array_remove_index (GPtrArray *farray, - guint index_) + guint index_) { GRealPtrArray* array = (GRealPtrArray*) farray; gpointer result; @@ -1196,20 +1200,20 @@ g_ptr_array_remove_index (GPtrArray *farray, /** * g_ptr_array_remove_index_fast: - * @array: a #GPtrArray. - * @index_: the index of the pointer to remove. + * @array: a #GPtrArray + * @index_: the index of the pointer to remove * - * Removes the pointer at the given index from the pointer array. The - * last element in the array is used to fill in the space, so this - * function does not preserve the order of the array. But it is faster - * than g_ptr_array_remove_index(). If @array has a non-%NULL + * Removes the pointer at the given index from the pointer array. + * The last element in the array is used to fill in the space, so + * this function does not preserve the order of the array. But it + * is faster than g_ptr_array_remove_index(). If @array has a non-%NULL * #GDestroyNotify function it is called for the removed element. * - * Returns: the pointer which was removed. - **/ + * Returns: the pointer which was removed + */ gpointer g_ptr_array_remove_index_fast (GPtrArray *farray, - guint index_) + guint index_) { GRealPtrArray* array = (GRealPtrArray*) farray; gpointer result; @@ -1248,7 +1252,7 @@ g_ptr_array_remove_index_fast (GPtrArray *farray, * Returns: the @array * * Since: 2.4 - **/ + */ GPtrArray * g_ptr_array_remove_range (GPtrArray *farray, guint index_, @@ -1287,8 +1291,8 @@ g_ptr_array_remove_range (GPtrArray *farray, /** * g_ptr_array_remove: - * @array: a #GPtrArray. - * @data: the pointer to remove. + * @array: a #GPtrArray + * @data: the pointer to remove * * Removes the first occurrence of the given pointer from the pointer * array. The following elements are moved down one place. If @array @@ -1298,12 +1302,12 @@ g_ptr_array_remove_range (GPtrArray *farray, * It returns %TRUE if the pointer was removed, or %FALSE if the * pointer was not found. * - * Returns: %TRUE if the pointer is removed. %FALSE if the pointer is - * not found in the array. - **/ + * Returns: %TRUE if the pointer is removed, %FALSE if the pointer + * is not found in the array + */ gboolean g_ptr_array_remove (GPtrArray *farray, - gpointer data) + gpointer data) { GRealPtrArray* array = (GRealPtrArray*) farray; guint i; @@ -1313,10 +1317,10 @@ g_ptr_array_remove (GPtrArray *farray, for (i = 0; i < array->len; i += 1) { if (array->pdata[i] == data) - { - g_ptr_array_remove_index (farray, i); - return TRUE; - } + { + g_ptr_array_remove_index (farray, i); + return TRUE; + } } return FALSE; @@ -1324,23 +1328,23 @@ g_ptr_array_remove (GPtrArray *farray, /** * g_ptr_array_remove_fast: - * @array: a #GPtrArray. - * @data: the pointer to remove. + * @array: a #GPtrArray + * @data: the pointer to remove * * Removes the first occurrence of the given pointer from the pointer * array. The last element in the array is used to fill in the space, - * so this function does not preserve the order of the array. But it is - * faster than g_ptr_array_remove(). If @array has a non-%NULL + * so this function does not preserve the order of the array. But it + * is faster than g_ptr_array_remove(). If @array has a non-%NULL * #GDestroyNotify function it is called for the removed element. * * It returns %TRUE if the pointer was removed, or %FALSE if the * pointer was not found. * - * Returns: %TRUE if the pointer was found in the array. - **/ + * Returns: %TRUE if the pointer was found in the array + */ gboolean g_ptr_array_remove_fast (GPtrArray *farray, - gpointer data) + gpointer data) { GRealPtrArray* array = (GRealPtrArray*) farray; guint i; @@ -1350,10 +1354,10 @@ g_ptr_array_remove_fast (GPtrArray *farray, for (i = 0; i < array->len; i += 1) { if (array->pdata[i] == data) - { - g_ptr_array_remove_index_fast (farray, i); - return TRUE; - } + { + g_ptr_array_remove_index_fast (farray, i); + return TRUE; + } } return FALSE; @@ -1361,15 +1365,15 @@ g_ptr_array_remove_fast (GPtrArray *farray, /** * g_ptr_array_add: - * @array: a #GPtrArray. - * @data: the pointer to add. + * @array: a #GPtrArray + * @data: the pointer to add * * Adds a pointer to the end of the pointer array. The array will grow * in size automatically if necessary. - **/ + */ void g_ptr_array_add (GPtrArray *farray, - gpointer data) + gpointer data) { GRealPtrArray* array = (GRealPtrArray*) farray; @@ -1382,15 +1386,15 @@ g_ptr_array_add (GPtrArray *farray, /** * g_ptr_array_insert: - * @array: a #GPtrArray. - * @index_: the index to place the new element at, or -1 to append. + * @array: a #GPtrArray + * @index_: the index to place the new element at, or -1 to append * @data: the pointer to add. * * Inserts an element into the pointer array at the given index. The * array will grow in size automatically if necessary. * * Since: 2.40 - **/ + */ void g_ptr_array_insert (GPtrArray *farray, gint index_, @@ -1418,61 +1422,61 @@ g_ptr_array_insert (GPtrArray *farray, /** * g_ptr_array_sort: - * @array: a #GPtrArray. - * @compare_func: comparison function. + * @array: a #GPtrArray + * @compare_func: comparison function * * Sorts the array, using @compare_func which should be a qsort()-style * comparison function (returns less than zero for first arg is less * than second arg, zero for equal, greater than zero if irst arg is * greater than second arg). * - * The comparison function for g_ptr_array_sort() doesn't + * Note that the comparison function for g_ptr_array_sort() doesn't * take the pointers from the array as arguments, it takes pointers to - * the pointers in the array. + * the pointers in the array. * * This is guaranteed to be a stable sort since version 2.32. - **/ + */ void g_ptr_array_sort (GPtrArray *array, - GCompareFunc compare_func) + GCompareFunc compare_func) { g_return_if_fail (array != NULL); /* Don't use qsort as we want a guaranteed stable sort */ g_qsort_with_data (array->pdata, - array->len, - sizeof (gpointer), - (GCompareDataFunc)compare_func, - NULL); + array->len, + sizeof (gpointer), + (GCompareDataFunc)compare_func, + NULL); } /** * g_ptr_array_sort_with_data: - * @array: a #GPtrArray. - * @compare_func: comparison function. - * @user_data: data to pass to @compare_func. + * @array: a #GPtrArray + * @compare_func: comparison function + * @user_data: data to pass to @compare_func * * Like g_ptr_array_sort(), but the comparison function has an extra * user data argument. * - * The comparison function for g_ptr_array_sort_with_data() + * Note that the comparison function for g_ptr_array_sort_with_data() * doesn't take the pointers from the array as arguments, it takes - * pointers to the pointers in the array. + * pointers to the pointers in the array. * * This is guaranteed to be a stable sort since version 2.32. - **/ + */ void g_ptr_array_sort_with_data (GPtrArray *array, - GCompareDataFunc compare_func, - gpointer user_data) + GCompareDataFunc compare_func, + gpointer user_data) { g_return_if_fail (array != NULL); g_qsort_with_data (array->pdata, - array->len, - sizeof (gpointer), - compare_func, - user_data); + array->len, + sizeof (gpointer), + compare_func, + user_data); } /** @@ -1484,7 +1488,7 @@ g_ptr_array_sort_with_data (GPtrArray *array, * Calls a function for each element of a #GPtrArray. * * Since: 2.4 - **/ + */ void g_ptr_array_foreach (GPtrArray *array, GFunc func, @@ -1537,13 +1541,13 @@ g_ptr_array_foreach (GPtrArray *array, * * See #GBytes if you are interested in an immutable object representing a * sequence of bytes. - **/ + */ /** * GByteArray: * @data: a pointer to the element data. The data may be moved as - * elements are added to the #GByteArray. - * @len: the number of elements in the #GByteArray. + * elements are added to the #GByteArray + * @len: the number of elements in the #GByteArray * * The #GByteArray-struct allows access to the public fields of * a #GByteArray. @@ -1554,9 +1558,10 @@ g_ptr_array_foreach (GPtrArray *array, * * Creates a new #GByteArray with a reference count of 1. * - * Returns: (transfer full): the new #GByteArray. - **/ -GByteArray* g_byte_array_new (void) + * Returns: (transfer full): the new #GByteArray + */ +GByteArray* +g_byte_array_new (void) { return (GByteArray*) g_array_sized_new (FALSE, FALSE, 1, 0); } @@ -1593,24 +1598,25 @@ g_byte_array_new_take (guint8 *data, /** * g_byte_array_sized_new: - * @reserved_size: number of bytes preallocated. + * @reserved_size: number of bytes preallocated * * Creates a new #GByteArray with @reserved_size bytes preallocated. * This avoids frequent reallocation, if you are going to add many * bytes to the array. Note however that the size of the array is still * 0. * - * Returns: the new #GByteArray. - **/ -GByteArray* g_byte_array_sized_new (guint reserved_size) + * Returns: the new #GByteArray + */ +GByteArray* +g_byte_array_sized_new (guint reserved_size) { return (GByteArray*) g_array_sized_new (FALSE, FALSE, 1, reserved_size); } /** * g_byte_array_free: - * @array: a #GByteArray. - * @free_segment: if %TRUE the actual byte data is freed as well. + * @array: a #GByteArray + * @free_segment: if %TRUE the actual byte data is freed as well * * Frees the memory allocated by the #GByteArray. If @free_segment is * %TRUE it frees the actual byte data. If the reference count of @@ -1619,9 +1625,10 @@ GByteArray* g_byte_array_sized_new (guint reserved_size) * * Returns: the element data if @free_segment is %FALSE, otherwise * %NULL. The element data should be freed using g_free(). - **/ -guint8* g_byte_array_free (GByteArray *array, - gboolean free_segment) + */ +guint8* +g_byte_array_free (GByteArray *array, + gboolean free_segment) { return (guint8*) g_array_free ((GArray*) array, free_segment); } @@ -1641,8 +1648,8 @@ guint8* g_byte_array_free (GByteArray *array, * * Since: 2.32 * - * Returns: (transfer full): a new immutable #GBytes representing same byte - * data that was in the array + * Returns: (transfer full): a new immutable #GBytes representing same + * byte data that was in the array */ GBytes * g_byte_array_free_to_bytes (GByteArray *array) @@ -1657,15 +1664,15 @@ g_byte_array_free_to_bytes (GByteArray *array) /** * g_byte_array_ref: - * @array: A #GByteArray. + * @array: A #GByteArray * * Atomically increments the reference count of @array by one. This * function is MT-safe and may be called from any thread. * - * Returns: The passed in #GByteArray. + * Returns: The passed in #GByteArray * * Since: 2.22 - **/ + */ GByteArray * g_byte_array_ref (GByteArray *array) { @@ -1674,7 +1681,7 @@ g_byte_array_ref (GByteArray *array) /** * g_byte_array_unref: - * @array: A #GByteArray. + * @array: A #GByteArray * * Atomically decrements the reference count of @array by one. If the * reference count drops to 0, all memory allocated by the array is @@ -1682,7 +1689,7 @@ g_byte_array_ref (GByteArray *array) * thread. * * Since: 2.22 - **/ + */ void g_byte_array_unref (GByteArray *array) { @@ -1691,18 +1698,19 @@ g_byte_array_unref (GByteArray *array) /** * g_byte_array_append: - * @array: a #GByteArray. - * @data: the byte data to be added. - * @len: the number of bytes to add. + * @array: a #GByteArray + * @data: the byte data to be added + * @len: the number of bytes to add * * Adds the given bytes to the end of the #GByteArray. The array will * grow in size automatically if necessary. * - * Returns: the #GByteArray. - **/ -GByteArray* g_byte_array_append (GByteArray *array, - const guint8 *data, - guint len) + * Returns: the #GByteArray + */ +GByteArray* +g_byte_array_append (GByteArray *array, + const guint8 *data, + guint len) { g_array_append_vals ((GArray*) array, (guint8*)data, len); @@ -1711,18 +1719,19 @@ GByteArray* g_byte_array_append (GByteArray *array, /** * g_byte_array_prepend: - * @array: a #GByteArray. - * @data: the byte data to be added. - * @len: the number of bytes to add. + * @array: a #GByteArray + * @data: the byte data to be added + * @len: the number of bytes to add * * Adds the given data to the start of the #GByteArray. The array will * grow in size automatically if necessary. * - * Returns: the #GByteArray. - **/ -GByteArray* g_byte_array_prepend (GByteArray *array, - const guint8 *data, - guint len) + * Returns: the #GByteArray + */ +GByteArray* +g_byte_array_prepend (GByteArray *array, + const guint8 *data, + guint len) { g_array_prepend_vals ((GArray*) array, (guint8*)data, len); @@ -1731,15 +1740,16 @@ GByteArray* g_byte_array_prepend (GByteArray *array, /** * g_byte_array_set_size: - * @array: a #GByteArray. - * @length: the new size of the #GByteArray. + * @array: a #GByteArray + * @length: the new size of the #GByteArray * * Sets the size of the #GByteArray, expanding it if necessary. * - * Returns: the #GByteArray. - **/ -GByteArray* g_byte_array_set_size (GByteArray *array, - guint length) + * Returns: the #GByteArray + */ +GByteArray* +g_byte_array_set_size (GByteArray *array, + guint length) { g_array_set_size ((GArray*) array, length); @@ -1748,16 +1758,17 @@ GByteArray* g_byte_array_set_size (GByteArray *array, /** * g_byte_array_remove_index: - * @array: a #GByteArray. - * @index_: the index of the byte to remove. + * @array: a #GByteArray + * @index_: the index of the byte to remove * * Removes the byte at the given index from a #GByteArray. The * following bytes are moved down one place. * - * Returns: the #GByteArray. + * Returns: the #GByteArray **/ -GByteArray* g_byte_array_remove_index (GByteArray *array, - guint index_) +GByteArray* +g_byte_array_remove_index (GByteArray *array, + guint index_) { g_array_remove_index ((GArray*) array, index_); @@ -1766,18 +1777,19 @@ GByteArray* g_byte_array_remove_index (GByteArray *array, /** * g_byte_array_remove_index_fast: - * @array: a #GByteArray. - * @index_: the index of the byte to remove. + * @array: a #GByteArray + * @index_: the index of the byte to remove * * Removes the byte at the given index from a #GByteArray. The last * element in the array is used to fill in the space, so this function * does not preserve the order of the #GByteArray. But it is faster * than g_byte_array_remove_index(). * - * Returns: the #GByteArray. - **/ -GByteArray* g_byte_array_remove_index_fast (GByteArray *array, - guint index_) + * Returns: the #GByteArray + */ +GByteArray* +g_byte_array_remove_index_fast (GByteArray *array, + guint index_) { g_array_remove_index_fast ((GArray*) array, index_); @@ -1786,17 +1798,17 @@ GByteArray* g_byte_array_remove_index_fast (GByteArray *array, /** * g_byte_array_remove_range: - * @array: a @GByteArray. - * @index_: the index of the first byte to remove. - * @length: the number of bytes to remove. + * @array: a @GByteArray + * @index_: the index of the first byte to remove + * @length: the number of bytes to remove * * Removes the given number of bytes starting at the given index from a * #GByteArray. The following elements are moved to close the gap. * - * Returns: the #GByteArray. + * Returns: the #GByteArray * * Since: 2.4 - **/ + */ GByteArray* g_byte_array_remove_range (GByteArray *array, guint index_, @@ -1811,8 +1823,8 @@ g_byte_array_remove_range (GByteArray *array, /** * g_byte_array_sort: - * @array: a #GByteArray. - * @compare_func: comparison function. + * @array: a #GByteArray + * @compare_func: comparison function * * Sorts a byte array, using @compare_func which should be a * qsort()-style comparison function (returns less than zero for first @@ -1824,27 +1836,27 @@ g_byte_array_remove_range (GByteArray *array, * you want a stable sort) you can write a comparison function that, * if two elements would otherwise compare equal, compares them by * their addresses. - **/ + */ void g_byte_array_sort (GByteArray *array, - GCompareFunc compare_func) + GCompareFunc compare_func) { g_array_sort ((GArray *) array, compare_func); } /** * g_byte_array_sort_with_data: - * @array: a #GByteArray. - * @compare_func: comparison function. - * @user_data: data to pass to @compare_func. + * @array: a #GByteArray + * @compare_func: comparison function + * @user_data: data to pass to @compare_func * * Like g_byte_array_sort(), but the comparison function takes an extra * user data argument. - **/ + */ void g_byte_array_sort_with_data (GByteArray *array, - GCompareDataFunc compare_func, - gpointer user_data) + GCompareDataFunc compare_func, + gpointer user_data) { g_array_sort_with_data ((GArray *) array, compare_func, user_data); } diff --git a/glib/ggettext.c b/glib/ggettext.c index 61d20d1b3..bd5c9d446 100644 --- a/glib/ggettext.c +++ b/glib/ggettext.c @@ -520,11 +520,11 @@ g_dngettext (const gchar *domain, * See the C_() macro for a different way to mark up translatable strings * with context. * - * If you are using the Q_() macro, you need to make sure - * that you pass to xgettext when extracting - * messages. If you are using GNU gettext >= 0.15, you can also use + * If you are using the Q_() macro, you need to make sure that you pass + * to xgettext when extracting messages. + * If you are using GNU gettext >= 0.15, you can also use * to let xgettext split the context - * string off into a msgctxt line in the po file. + * string off into a msgctxt line in the po file. * * Returns: the translated message * @@ -545,10 +545,9 @@ g_dngettext (const gchar *domain, * label2 = C_("Body part", "Back"); * ]| * - * If you are using the C_() macro, you need to make sure - * that you pass to xgettext when - * extracting messages. Note that this only works with GNU - * gettext >= 0.15. + * If you are using the C_() macro, you need to make sure that you pass + * to xgettext when extracting messages. + * Note that this only works with GNU gettext >= 0.15. * * Returns: the translated message * @@ -609,11 +608,10 @@ g_dngettext (const gchar *domain, * } * ]| * - * If you are using the NC_() macro, you need to make sure - * that you pass to xgettext when - * extracting messages. Note that this only works with GNU gettext >= 0.15. - * Intltool has support for the NC_() macro since version 0.40.1. - * + * If you are using the NC_() macro, you need to make sure that you pass + * to xgettext when extracting messages. + * Note that this only works with GNU gettext >= 0.15. Intltool has support + * for the NC_() macro since version 0.40.1. * * Since: 2.18 */ diff --git a/glib/gkeyfile.c b/glib/gkeyfile.c index d7a6648b5..d8c01bbff 100644 --- a/glib/gkeyfile.c +++ b/glib/gkeyfile.c @@ -3561,16 +3561,15 @@ g_key_file_has_key_full (GKeyFile *key_file, * Looks whether the key file has the key @key in the group * @group_name. * - * This function does not follow the rules for #GError strictly; + * Note that this function does not follow the rules for #GError strictly; * the return value both carries meaning and signals an error. To use * this function, you must pass a #GError pointer in @error, and check - * whether it is not %NULL to see if an error occurred. + * whether it is not %NULL to see if an error occurred. * * Language bindings should use g_key_file_get_value() to test whether * or not a key exists. * - * Return value: %TRUE if @key is a part of @group_name, %FALSE - * otherwise. + * Return value: %TRUE if @key is a part of @group_name, %FALSE otherwise * * Since: 2.6 **/ diff --git a/glib/glib-unix.c b/glib/glib-unix.c index ec8cc5cfc..5fad19d99 100644 --- a/glib/glib-unix.c +++ b/glib/glib-unix.c @@ -63,19 +63,17 @@ g_unix_set_error_from_errno (GError **error, /** * g_unix_open_pipe: * @fds: Array of two integers - * @flags: Bitfield of file descriptor flags, see "man 2 fcntl" + * @flags: Bitfield of file descriptor flags, as for fcntl() * @error: a #GError * * Similar to the UNIX pipe() call, but on modern systems like Linux * uses the pipe2() system call, which atomically creates a pipe with - * the configured flags. The only supported flag currently is - * FD_CLOEXEC. If for example you want to configure - * O_NONBLOCK, that must still be done separately with - * fcntl(). + * the configured flags. The only supported flag currently is + * %FD_CLOEXEC. If for example you want to configure %O_NONBLOCK, that + * must still be done separately with fcntl(). * - * This function does *not* take O_CLOEXEC, it takes - * FD_CLOEXEC as if for fcntl(); these are - * different on Linux/glibc. + * This function does not take %O_CLOEXEC, it takes %FD_CLOEXEC as if + * for fcntl(); these are different on Linux/glibc. * * Returns: %TRUE on success, %FALSE if not (and errno will be set). * @@ -138,8 +136,8 @@ g_unix_open_pipe (int *fds, * @error: a #GError * * Control the non-blocking state of the given file descriptor, - * according to @nonblock. On most systems this uses O_NONBLOCK, but - * on some older ones may use O_NDELAY. + * according to @nonblock. On most systems this uses %O_NONBLOCK, but + * on some older ones may use %O_NDELAY. * * Returns: %TRUE if successful * diff --git a/glib/glist.c b/glib/glist.c index 30c0a5b5c..1096f86ac 100644 --- a/glib/glist.c +++ b/glib/glist.c @@ -174,13 +174,10 @@ g_list_alloc (void) * @list: a #GList * * Frees all of the memory used by a #GList. - * The freed elements are returned to the slice allocator + * The freed elements are returned to the slice allocator. * - * - * If list elements contain dynamically-allocated memory, - * you should either use g_list_free_full() or free them manually - * first. - * + * If list elements contain dynamically-allocated memory, you should + * either use g_list_free_full() or free them manually first. */ void g_list_free (GList *list) @@ -299,10 +296,8 @@ g_list_append (GList *list, * list = g_list_prepend (list, "first"); * ]| * - * - * Do not use this function to prepend a new element to a different element - * than the start of the list. Use g_list_insert_before() instead. - * + * Do not use this function to prepend a new element to a different + * element than the start of the list. Use g_list_insert_before() instead. * * Returns: a pointer to the newly prepended element, which is the new * start of the #GList @@ -625,12 +620,10 @@ g_list_delete_link (GList *list, * * Copies a #GList. * - * * Note that this is a "shallow" copy. If the list elements * consist of pointers to data, the pointers are copied but * the actual data is not. See g_list_copy_deep() if you need * to copy the data as well. - * * * Returns: the start of the new list that holds the same data as @list */ @@ -955,11 +948,9 @@ g_list_first (GList *list) * * Gets the number of elements in a #GList. * - * * This function iterates over the whole list to count its elements. - * Use a GQueue instead - * of a GList if you regularly need the number of items. - * + * Use a #GQueue instead of a GList if you regularly need the number + * of items. * * Returns: the number of elements in the #GList */ @@ -1071,12 +1062,10 @@ g_list_insert_sorted_real (GList *list, * Inserts a new element into the list, using the given comparison * function to determine its position. * - * * If you are adding many new elements to a list, and the number of * new elements is much larger than the length of the list, use * g_list_prepend() to add the new items and sort the list afterwards - * with g_list_sort() - * + * with g_list_sort(). * * Returns: the (possibly changed) start of the #GList */ @@ -1101,12 +1090,10 @@ g_list_insert_sorted (GList *list, * Inserts a new element into the list, using the given comparison * function to determine its position. * - * * If you are adding many new elements to a list, and the number of * new elements is much larger than the length of the list, use * g_list_prepend() to add the new items and sort the list afterwards - * with g_list_sort() - * + * with g_list_sort(). * * Returns: the (possibly changed) start of the #GList * diff --git a/glib/gmacros.h b/glib/gmacros.h index a181c97f2..6403a9960 100644 --- a/glib/gmacros.h +++ b/glib/gmacros.h @@ -42,18 +42,16 @@ * "long long" types even in the presence of '-ansi -pedantic'. */ #if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 8) -# define G_GNUC_EXTENSION __extension__ +#define G_GNUC_EXTENSION __extension__ #else -# define G_GNUC_EXTENSION +#define G_GNUC_EXTENSION #endif /* Provide macros to feature the GCC function attribute. */ #if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 96) -#define G_GNUC_PURE \ - __attribute__((__pure__)) -#define G_GNUC_MALLOC \ - __attribute__((__malloc__)) +#define G_GNUC_PURE __attribute__((__pure__)) +#define G_GNUC_MALLOC __attribute__((__malloc__)) #else #define G_GNUC_PURE #define G_GNUC_MALLOC @@ -99,8 +97,7 @@ #endif /* !__GNUC__ */ #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1) -#define G_GNUC_DEPRECATED \ - __attribute__((__deprecated__)) +#define G_GNUC_DEPRECATED __attribute__((__deprecated__)) #else #define G_GNUC_DEPRECATED #endif /* __GNUC__ */ @@ -130,14 +127,13 @@ #endif #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3) -# define G_GNUC_MAY_ALIAS __attribute__((may_alias)) +#define G_GNUC_MAY_ALIAS __attribute__((may_alias)) #else -# define G_GNUC_MAY_ALIAS +#define G_GNUC_MAY_ALIAS #endif #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4) -#define G_GNUC_WARN_UNUSED_RESULT \ - __attribute__((warn_unused_result)) +#define G_GNUC_WARN_UNUSED_RESULT __attribute__((warn_unused_result)) #else #define G_GNUC_WARN_UNUSED_RESULT #endif /* __GNUC__ */ @@ -185,29 +181,29 @@ /* Provide a string identifying the current code position */ #if defined(__GNUC__) && (__GNUC__ < 3) && !defined(__cplusplus) -# define G_STRLOC __FILE__ ":" G_STRINGIFY (__LINE__) ":" __PRETTY_FUNCTION__ "()" +#define G_STRLOC __FILE__ ":" G_STRINGIFY (__LINE__) ":" __PRETTY_FUNCTION__ "()" #else -# define G_STRLOC __FILE__ ":" G_STRINGIFY (__LINE__) +#define G_STRLOC __FILE__ ":" G_STRINGIFY (__LINE__) #endif /* Provide a string identifying the current function, non-concatenatable */ #if defined (__GNUC__) && defined (__cplusplus) -# define G_STRFUNC ((const char*) (__PRETTY_FUNCTION__)) +#define G_STRFUNC ((const char*) (__PRETTY_FUNCTION__)) #elif defined (__STDC_VERSION__) && __STDC_VERSION__ >= 199901L -# define G_STRFUNC ((const char*) (__func__)) +#define G_STRFUNC ((const char*) (__func__)) #elif defined (__GNUC__) || (defined(_MSC_VER) && (_MSC_VER > 1300)) -# define G_STRFUNC ((const char*) (__FUNCTION__)) +#define G_STRFUNC ((const char*) (__FUNCTION__)) #else -# define G_STRFUNC ((const char*) ("???")) +#define G_STRFUNC ((const char*) ("???")) #endif /* Guard C code in headers, while including them from C++ */ #ifdef __cplusplus -# define G_BEGIN_DECLS extern "C" { -# define G_END_DECLS } +#define G_BEGIN_DECLS extern "C" { +#define G_END_DECLS } #else -# define G_BEGIN_DECLS -# define G_END_DECLS +#define G_BEGIN_DECLS +#define G_END_DECLS #endif /* Provide definitions for some commonly used macros. @@ -217,9 +213,9 @@ */ #ifndef NULL # ifdef __cplusplus -# define NULL (0L) +# define NULL (0L) # else /* !__cplusplus */ -# define NULL ((void*) 0) +# define NULL ((void*) 0) # endif /* !__cplusplus */ #endif @@ -259,10 +255,10 @@ */ #if defined(__GNUC__) && __GNUC__ >= 4 -# define G_STRUCT_OFFSET(struct_type, member) \ +#define G_STRUCT_OFFSET(struct_type, member) \ ((glong) offsetof (struct_type, member)) #else -# define G_STRUCT_OFFSET(struct_type, member) \ +#define G_STRUCT_OFFSET(struct_type, member) \ ((glong) ((guint8*) &((struct_type*) 0)->member)) #endif @@ -279,8 +275,8 @@ * avoid portability issue or side effects when compiled with different compilers. */ #if !(defined (G_STMT_START) && defined (G_STMT_END)) -# define G_STMT_START do -# define G_STMT_END while (0) +#define G_STMT_START do +#define G_STMT_END while (0) #endif /* Deprecated -- do not use. */ diff --git a/glib/gmem.c b/glib/gmem.c index ec1c1cc41..980cc09c9 100644 --- a/glib/gmem.c +++ b/glib/gmem.c @@ -66,18 +66,15 @@ static GMemVTable glib_mem_vtable = { * * These functions provide support for allocating and freeing memory. * - * * If any call to allocate memory fails, the application is terminated. * This also means that there is no need to check if the call succeeded. - * - * - * - * It's important to match g_malloc() with g_free(), plain malloc() with free(), - * and (if you're using C++) new with delete and new[] with delete[]. Otherwise - * bad things can happen, since these allocators may use different memory - * pools (and new/delete call constructors and destructors). See also - * g_mem_set_vtable(). - * + * + * It's important to match g_malloc() (and wrappers such as g_new()) with + * g_free(), g_slice_alloc() and wrappers such as g_slice_new()) with + * g_slice_free(), plain malloc() with free(), and (if you're using C++) + * new with delete and new[] with delete[]. Otherwise bad things can happen, + * since these allocators may use different memory pools (and new/delete call + * constructors and destructors). See also g_mem_set_vtable(). */ /* --- functions --- */ diff --git a/glib/gqueue.c b/glib/gqueue.c index a78c08c97..926539cea 100644 --- a/glib/gqueue.c +++ b/glib/gqueue.c @@ -75,11 +75,8 @@ g_queue_new (void) * if @queue was created with g_queue_new(). If queue elements contain * dynamically-allocated memory, they should be freed first. * - * - * If queue elements contain dynamically-allocated memory, - * you should either use g_queue_free_full() or free them manually - * first. - * + * If queue elements contain dynamically-allocated memory, you should + * either use g_queue_free_full() or free them manually first. **/ void g_queue_free (GQueue *queue) diff --git a/glib/gsequence.c b/glib/gsequence.c index a17953b17..9f65b5f4c 100644 --- a/glib/gsequence.c +++ b/glib/gsequence.c @@ -769,13 +769,11 @@ g_sequence_sort_changed (GSequenceIter *iter, * If you are simply searching for an existing element of the sequence, * consider using g_sequence_lookup(). * - * * This function will fail if the data contained in the sequence is * unsorted. Use g_sequence_insert_sorted() or * g_sequence_insert_sorted_iter() to add data to your sequence or, if * you want to add a large amount of data, call g_sequence_sort() after * doing unsorted insertions. - * * * Return value: an #GSequenceIter pointing to the position where @data * would have been inserted according to @cmp_func and @cmp_data. @@ -818,13 +816,11 @@ g_sequence_search (GSequence *seq, * the first item comes before the second, and a positive value if * the second item comes before the first. * - * * This function will fail if the data contained in the sequence is * unsorted. Use g_sequence_insert_sorted() or * g_sequence_insert_sorted_iter() to add data to your sequence or, if * you want to add a large amount of data, call g_sequence_sort() after * doing unsorted insertions. - * * * Return value: an #GSequenceIter pointing to the position of the * first item found equal to @data according to @cmp_func and @@ -1052,13 +1048,11 @@ g_sequence_insert_sorted_iter (GSequence *seq, * If you are simply searching for an existing element of the sequence, * consider using g_sequence_lookup_iter(). * - * * This function will fail if the data contained in the sequence is * unsorted. Use g_sequence_insert_sorted() or * g_sequence_insert_sorted_iter() to add data to your sequence or, if * you want to add a large amount of data, call g_sequence_sort() after * doing unsorted insertions. - * * * Return value: a #GSequenceIter pointing to the position in @seq * where @data would have been inserted according to @iter_cmp @@ -1112,13 +1106,11 @@ g_sequence_search_iter (GSequence *seq, * if the first iterator comes before the second, and a positive * value if the second iterator comes before the first. * - * * This function will fail if the data contained in the sequence is * unsorted. Use g_sequence_insert_sorted() or * g_sequence_insert_sorted_iter() to add data to your sequence or, if * you want to add a large amount of data, call g_sequence_sort() after * doing unsorted insertions. - * * * Return value: an #GSequenceIter pointing to the position of * the first item found equal to @data according to @cmp_func diff --git a/glib/gslist.c b/glib/gslist.c index 0143ded2d..1915f9137 100644 --- a/glib/gslist.c +++ b/glib/gslist.c @@ -128,11 +128,9 @@ g_slist_alloc (void) * Frees all of the memory used by a #GSList. * The freed elements are returned to the slice allocator. * - * * If list elements contain dynamically-allocated memory, * you should either use g_slist_free_full() or free them manually * first. - * */ void g_slist_free (GSList *list) @@ -185,17 +183,13 @@ g_slist_free_full (GSList *list, * * Adds a new element on to the end of the list. * - * * The return value is the new start of the list, which may * have changed, so make sure you store the new value. - * * - * * Note that g_slist_append() has to traverse the entire list * to find the end, which is inefficient when adding multiple * elements. A common idiom to avoid the inefficiency is to prepend * the elements and reverse the list when all elements have been added. - * * * |[ * /* Notice that these are initialized to the empty list. */ @@ -242,10 +236,8 @@ g_slist_append (GSList *list, * * Adds a new element on to the start of the list. * - * * The return value is the new start of the list, which * may have changed, so make sure you store the new value. - * * * |[ * /* Notice that it is initialized to the empty list. */ @@ -515,11 +507,11 @@ _g_slist_remove_link (GSList *list, * link is set to %NULL, so that it becomes a * self-contained list with one element. * - * Removing arbitrary nodes from a singly-linked list + * Removing arbitrary nodes from a singly-linked list * requires time that is proportional to the length of the list * (ie. O(n)). If you find yourself using g_slist_remove_link() - * frequently, you should consider a different data structure, such - * as the doubly-linked #GList. + * frequently, you should consider a different data structure, + * such as the doubly-linked #GList. * * Returns: the new start of the #GSList, without the element */ @@ -539,11 +531,11 @@ g_slist_remove_link (GSList *list, * Compare this to g_slist_remove_link() which removes the node * without freeing it. * - * Removing arbitrary nodes from a singly-linked list - * requires time that is proportional to the length of the list - * (ie. O(n)). If you find yourself using g_slist_delete_link() - * frequently, you should consider a different data structure, such - * as the doubly-linked #GList. + * Removing arbitrary nodes from a singly-linked list requires time + * that is proportional to the length of the list (ie. O(n)). If you + * find yourself using g_slist_delete_link() frequently, you should + * consider a different data structure, such as the doubly-linked + * #GList. * * Returns: the new head of @list */ @@ -563,12 +555,10 @@ g_slist_delete_link (GSList *list, * * Copies a #GSList. * - * * Note that this is a "shallow" copy. If the list elements * consist of pointers to data, the pointers are copied but * the actual data isn't. See g_slist_copy_deep() if you need * to copy the data as well. - * * * Returns: a copy of @list */ @@ -828,9 +818,7 @@ g_slist_index (GSList *list, * * Gets the last element in a #GSList. * - * * This function iterates over the whole list. - * * * Returns: the last element in the #GSList, * or %NULL if the #GSList has no elements @@ -853,10 +841,8 @@ g_slist_last (GSList *list) * * Gets the number of elements in a #GSList. * - * * This function iterates over the whole list to * count its elements. - * * * Returns: the number of elements in the #GSList */ diff --git a/glib/gspawn.c b/glib/gspawn.c index 0e6106ca1..86aa89c34 100644 --- a/glib/gspawn.c +++ b/glib/gspawn.c @@ -109,17 +109,14 @@ G_DEFINE_QUARK (g-spawn-exit-error-quark, g_spawn_exit_error) * You should call g_spawn_close_pid() on the returned child process * reference when you don't need it any more. * - * - * If you are writing a GTK+ application, and the program you - * are spawning is a graphical application, too, then you may - * want to use gdk_spawn_on_screen() instead to ensure that - * the spawned program opens its windows on the right screen. - * + * If you are writing a GTK+ application, and the program you are + * spawning is a graphical application, too, then you may want to + * use gdk_spawn_on_screen() instead to ensure that the spawned program + * opens its windows on the right screen. * - * Note that the returned @child_pid on Windows is a - * handle to the child process and not its identifier. Process handles - * and process identifiers are different concepts on Windows. - * + * Note that the returned @child_pid on Windows is a handle to the child + * process and not its identifier. Process handles and process identifiers + * are different concepts on Windows. * * Return value: %TRUE on success, %FALSE if error is set **/ @@ -237,8 +234,8 @@ read_data (GString *str, * function for full details on the other parameters and details on * how these functions work on Windows. * - * Return value: %TRUE on success, %FALSE if an error was set. - **/ + * Return value: %TRUE on success, %FALSE if an error was set + */ gboolean g_spawn_sync (const gchar *working_directory, gchar **argv, @@ -509,21 +506,19 @@ g_spawn_sync (const gchar *working_directory, * level wide character command line passed to the spawned program * using the GetCommandLineW() function. * - * On Windows the low-level child process creation API - * CreateProcess() doesn't use argument vectors, - * but a command line. The C runtime library's - * spawn*() family of functions (which - * g_spawn_async_with_pipes() eventually calls) paste the argument - * vector elements together into a command line, and the C runtime startup code - * does a corresponding reconstruction of an argument vector from the - * command line, to be passed to main(). Complications arise when you have - * argument vector elements that contain spaces of double quotes. The - * spawn*() functions don't do any quoting or - * escaping, but on the other hand the startup code does do unquoting - * and unescaping in order to enable receiving arguments with embedded - * spaces or double quotes. To work around this asymmetry, - * g_spawn_async_with_pipes() will do quoting and escaping on argument - * vector elements that need it before calling the C runtime + * On Windows the low-level child process creation API CreateProcess() + * doesn't use argument vectors, but a command line. The C runtime + * library's spawn*() family of functions (which g_spawn_async_with_pipes() + * eventually calls) paste the argument vector elements together into + * a command line, and the C runtime startup code does a corresponding + * reconstruction of an argument vector from the command line, to be + * passed to main(). Complications arise when you have argument vector + * elements that contain spaces of double quotes. The spawn*() functions + * don't do any quoting or escaping, but on the other hand the startup + * code does do unquoting and unescaping in order to enable receiving + * arguments with embedded spaces or double quotes. To work around this + * asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on + * argument vector elements that need it before calling the C runtime * spawn() function. * * The returned @child_pid on Windows is a handle to the child @@ -542,20 +537,19 @@ g_spawn_sync (const gchar *working_directory, * call g_spawn_close_pid() on the @child_pid, in order to free * resources which may be associated with the child process. (On Unix, * using a child watch is equivalent to calling waitpid() or handling - * the SIGCHLD signal manually. On Windows, calling g_spawn_close_pid() + * the %SIGCHLD signal manually. On Windows, calling g_spawn_close_pid() * is equivalent to calling CloseHandle() on the process handle returned - * in @child_pid). See g_child_watch_add(). + * in @child_pid). See g_child_watch_add(). * * %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that the parent's open file - * descriptors will be inherited by the child; otherwise all - * descriptors except stdin/stdout/stderr will be closed before - * calling exec() in the child. %G_SPAWN_SEARCH_PATH - * means that argv[0] need not be an absolute path, it - * will be looked for in the PATH environment variable. - * %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an absolute path, it - * will be looked for in the PATH variable from @envp. If - * both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP are used, - * the value from @envp takes precedence over the environment. + * descriptors will be inherited by the child; otherwise all descriptors + * except stdin/stdout/stderr will be closed before calling exec() in the + * child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an absolute + * path, it will be looked for in the PATH environment + * variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an absolute + * path, it will be looked for in the PATH variable from + * @envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP + * are used, the value from @envp takes precedence over the environment. * %G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output will * be discarded, instead of going to the same location as the parent's * standard output. If you use this flag, @standard_output must be %NULL. @@ -566,42 +560,40 @@ g_spawn_sync (const gchar *working_directory, * standard input (by default, the child's standard input is attached to * /dev/null). If you use this flag, @standard_input must be %NULL. * %G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is - * the file to execute, while the remaining elements are the - * actual argument vector to pass to the file. Normally - * g_spawn_async_with_pipes() uses @argv[0] as the file to execute, and - * passes all of @argv to the child. + * the file to execute, while the remaining elements are the actual + * argument vector to pass to the file. Normally g_spawn_async_with_pipes() + * uses @argv[0] as the file to execute, and passes all of @argv to the child. * * @child_setup and @user_data are a function and user data. On POSIX * platforms, the function is called in the child after GLib has * performed all the setup it plans to perform (including creating - * pipes, closing file descriptors, etc.) but before calling - * exec(). That is, @child_setup is called just - * before calling exec() in the child. Obviously - * actions taken in this function will only affect the child, not the - * parent. + * pipes, closing file descriptors, etc.) but before calling exec(). + * That is, @child_setup is called just before calling exec() in the + * child. Obviously actions taken in this function will only affect + * the child, not the parent. * - * On Windows, there is no separate fork() and exec() - * functionality. Child processes are created and run with a single - * API call, CreateProcess(). There is no sensible thing @child_setup + * On Windows, there is no separate fork() and exec() functionality. + * Child processes are created and run with a single API call, + * CreateProcess(). There is no sensible thing @child_setup * could be used for on Windows so it is ignored and not called. * * If non-%NULL, @child_pid will on Unix be filled with the child's - * process ID. You can use the process ID to send signals to the - * child, or to use g_child_watch_add() (or waitpid()) if you specified the + * process ID. You can use the process ID to send signals to the child, + * or to use g_child_watch_add() (or waitpid()) if you specified the * %G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be * filled with a handle to the child process only if you specified the * %G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child * process using the Win32 API, for example wait for its termination - * with the WaitFor*() functions, or examine its - * exit code with GetExitCodeProcess(). You should close the handle - * with CloseHandle() or g_spawn_close_pid() when you no longer need it. + * with the WaitFor*() functions, or examine its exit code with + * GetExitCodeProcess(). You should close the handle with CloseHandle() + * or g_spawn_close_pid() when you no longer need it. * * If non-%NULL, the @standard_input, @standard_output, @standard_error * locations will be filled with file descriptors for writing to the child's * standard input or reading from its standard output or standard error. * The caller of g_spawn_async_with_pipes() must close these file descriptors - * when they are no longer in use. If these parameters are %NULL, the corresponding - * pipe won't be created. + * when they are no longer in use. If these parameters are %NULL, the + * corresponding pipe won't be created. * * If @standard_input is NULL, the child's standard input is attached to * /dev/null unless %G_SPAWN_CHILD_INHERITS_STDIN is set. @@ -615,11 +607,11 @@ g_spawn_sync (const gchar *working_directory, * is set. * * @error can be %NULL to ignore errors, or non-%NULL to report errors. - * If an error is set, the function returns %FALSE. Errors - * are reported even if they occur in the child (for example if the - * executable in argv[0] is not found). Typically - * the message field of returned errors should be displayed - * to users. Possible errors are those from the #G_SPAWN_ERROR domain. + * If an error is set, the function returns %FALSE. Errors are reported + * even if they occur in the child (for example if the executable in + * @argv[0] is not found). Typically the message field + * of returned errors should be displayed to users. Possible errors are + * those from the #G_SPAWN_ERROR domain. * * If an error occurs, @child_pid, @standard_input, @standard_output, * and @standard_error will not be filled with valid values. @@ -627,15 +619,13 @@ g_spawn_sync (const gchar *working_directory, * If @child_pid is not %NULL and an error does not occur then the returned * process reference must be closed using g_spawn_close_pid(). * - * * If you are writing a GTK+ application, and the program you * are spawning is a graphical application, too, then you may * want to use gdk_spawn_on_screen_with_pipes() instead to ensure that * the spawned program opens its windows on the right screen. - * * * Return value: %TRUE on success, %FALSE if an error was set - **/ + */ gboolean g_spawn_async_with_pipes (const gchar *working_directory, gchar **argv, @@ -759,7 +749,7 @@ g_spawn_command_line_sync (const gchar *command_line, * * The same concerns on Windows apply as for g_spawn_command_line_sync(). * - * Return value: %TRUE on success, %FALSE if error is set. + * Return value: %TRUE on success, %FALSE if error is set **/ gboolean g_spawn_command_line_async (const gchar *command_line, @@ -798,25 +788,23 @@ g_spawn_command_line_async (const gchar *command_line, * * The g_spawn_sync() and g_child_watch_add() family of APIs return an * exit status for subprocesses encoded in a platform-specific way. - * On Unix, this is guaranteed to be in the same format - * waitpid(2) returns, and on Windows it is - * guaranteed to be the result of - * GetExitCodeProcess(). Prior to the introduction - * of this function in GLib 2.34, interpreting @exit_status required - * use of platform-specific APIs, which is problematic for software - * using GLib as a cross-platform layer. + * On Unix, this is guaranteed to be in the same format waitpid() returns, + * and on Windows it is guaranteed to be the result of GetExitCodeProcess(). + * + * Prior to the introduction of this function in GLib 2.34, interpreting + * @exit_status required use of platform-specific APIs, which is problematic + * for software using GLib as a cross-platform layer. * * Additionally, many programs simply want to determine whether or not * the child exited successfully, and either propagate a #GError or - * print a message to standard error. In that common case, this - * function can be used. Note that the error message in @error will - * contain human-readable information about the exit status. + * print a message to standard error. In that common case, this function + * can be used. Note that the error message in @error will contain + * human-readable information about the exit status. * - * The domain and code of @error - * have special semantics in the case where the process has an "exit - * code", as opposed to being killed by a signal. On Unix, this - * happens if WIFEXITED would be true of - * @exit_status. On Windows, it is always the case. + * The @domain and @code of @error have special semantics in the case + * where the process has an "exit code", as opposed to being killed by + * a signal. On Unix, this happens if WIFEXITED() would be true of + * @exit_status. On Windows, it is always the case. * * The special semantics are that the actual exit code will be the * code set in @error, and the domain will be %G_SPAWN_EXIT_ERROR. @@ -828,12 +816,13 @@ g_spawn_command_line_async (const gchar *command_line, * * This function just offers convenience; you can of course also check * the available platform via a macro such as %G_OS_UNIX, and use - * WIFEXITED() and WEXITSTATUS() - * on @exit_status directly. Do not attempt to scan or parse the - * error message string; it may be translated and/or change in future - * versions of GLib. + * WIFEXITED() and WEXITSTATUS() on @exit_status directly. Do not attempt + * to scan or parse the error message string; it may be translated and/or + * change in future versions of GLib. + * + * Returns: %TRUE if child exited successfully, %FALSE otherwise (and + * @error will be set) * - * Returns: %TRUE if child exited successfully, %FALSE otherwise (and @error will be set) * Since: 2.34 */ gboolean diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c index 019a34876..89d212db4 100644 --- a/glib/gstrfuncs.c +++ b/glib/gstrfuncs.c @@ -398,18 +398,16 @@ g_memdup (gconstpointer mem, * @n: the maximum number of bytes to copy from @str * * Duplicates the first @n bytes of a string, returning a newly-allocated - * buffer @n + 1 bytes long which will always be nul-terminated. - * If @str is less than @n bytes long the buffer is padded with nuls. - * If @str is %NULL it returns %NULL. - * The returned value should be freed when no longer needed. + * buffer @n + 1 bytes long which will always be nul-terminated. If @str + * is less than @n bytes long the buffer is padded with nuls. If @str is + * %NULL it returns %NULL. The returned value should be freed when no longer + * needed. * - * * To copy a number of characters from a UTF-8 encoded string, use * g_utf8_strncpy() instead. - * * * Returns: a newly-allocated buffer containing the first @n bytes - * of @str, nul-terminated + * of @str, nul-terminated */ gchar* g_strndup (const gchar *str, @@ -1343,9 +1341,9 @@ g_strlcat (gchar *dest, * it's often faster). It returns the size of the attempted result, * strlen (src), so if @retval >= @dest_size, truncation occurred. * - * Caveat: strlcpy() is supposedly more secure than - * strcpy() or strncpy(), but if you really want to avoid screwups, - * g_strdup() is an even better idea. + * Caveat: strlcpy() is supposedly more secure than strcpy() or strncpy(), + * but if you really want to avoid screwups, g_strdup() is an even better + * idea. * * Returns: length of @src */ @@ -1397,20 +1395,19 @@ g_strlcpy (gchar *dest, * guaranteeing nul-termination for @dest. The total size of @dest won't * exceed @dest_size. * - * At most dest_size - 1 characters will be copied. - * Unlike strncat, dest_size is the full size of dest, not the space left over. - * This function does NOT allocate memory. - * This always NUL terminates (unless siz == 0 or there were no NUL characters - * in the dest_size characters of dest to start with). + * At most @dest_size - 1 characters will be copied. Unlike strncat(), + * @dest_size is the full size of dest, not the space left over. This + * function does not allocate memory. It always nul-terminates (unless + * @dest_size == 0 or there were no nul characters in the @dest_size + * characters of dest to start with). * - * Caveat: this is supposedly a more secure alternative to - * strcat() or strncat(), but for real security g_strconcat() is harder - * to mess up. + * Caveat: this is supposedly a more secure alternative to strcat() or + * strncat(), but for real security g_strconcat() is harder to mess up. * * Returns: size of attempted result, which is MIN (dest_size, strlen - * (original dest)) + strlen (src), so if retval >= dest_size, - * truncation occurred. - **/ + * (original dest)) + strlen (src), so if retval >= dest_size, + * truncation occurred. + */ gsize g_strlcat (gchar *dest, const gchar *src, @@ -1450,17 +1447,16 @@ g_strlcat (gchar *dest, /** * g_ascii_strdown: - * @str: a string. - * @len: length of @str in bytes, or -1 if @str is nul-terminated. + * @str: a string + * @len: length of @str in bytes, or -1 if @str is nul-terminated * * Converts all upper case ASCII letters to lower case ASCII letters. * * Return value: a newly-allocated string, with all the upper case - * characters in @str converted to lower case, with - * semantics that exactly match g_ascii_tolower(). (Note - * that this is unlike the old g_strdown(), which modified - * the string in place.) - **/ + * characters in @str converted to lower case, with semantics that + * exactly match g_ascii_tolower(). (Note that this is unlike the + * old g_strdown(), which modified the string in place.) + */ gchar* g_ascii_strdown (const gchar *str, gssize len) @@ -1481,17 +1477,16 @@ g_ascii_strdown (const gchar *str, /** * g_ascii_strup: - * @str: a string. - * @len: length of @str in bytes, or -1 if @str is nul-terminated. + * @str: a string + * @len: length of @str in bytes, or -1 if @str is nul-terminated * * Converts all lower case ASCII letters to upper case ASCII letters. * * Return value: a newly allocated string, with all the lower case - * characters in @str converted to upper case, with - * semantics that exactly match g_ascii_toupper(). (Note - * that this is unlike the old g_strup(), which modified - * the string in place.) - **/ + * characters in @str converted to upper case, with semantics that + * exactly match g_ascii_toupper(). (Note that this is unlike the + * old g_strup(), which modified the string in place.) + */ gchar* g_ascii_strup (const gchar *str, gssize len) @@ -1512,7 +1507,7 @@ g_ascii_strup (const gchar *str, /** * g_str_is_ascii: - * @string: a string. + * @string: a string * * Determines if a string is pure ASCII. A string is pure ASCII if it * contains no bytes with the high bit set. @@ -1520,7 +1515,7 @@ g_ascii_strup (const gchar *str, * Returns: %TRUE if @string is ascii * * Since: 2.40 - **/ + */ gboolean g_str_is_ascii (const gchar *string) { @@ -1566,15 +1561,16 @@ g_strdown (gchar *string) /** * g_strup: - * @string: the string to convert. + * @string: the string to convert * * Converts a string to upper case. * * Return value: the string * - * Deprecated:2.2: This function is totally broken for the reasons discussed - * in the g_strncasecmp() docs - use g_ascii_strup() or g_utf8_strup() instead. - **/ + * Deprecated:2.2: This function is totally broken for the reasons + * discussed in the g_strncasecmp() docs - use g_ascii_strup() + * or g_utf8_strup() instead. + */ gchar* g_strup (gchar *string) { @@ -1637,7 +1633,7 @@ g_strreverse (gchar *string) /** * g_ascii_tolower: - * @c: any character. + * @c: any character * * Convert a character to ASCII lower case. * @@ -1646,13 +1642,12 @@ g_strreverse (gchar *string) * all non-ASCII characters unchanged, even if they are lower case * letters in a particular character set. Also unlike the standard * library function, this takes and returns a char, not an int, so - * don't call it on EOF but no need to worry about casting to #guchar + * don't call it on %EOF but no need to worry about casting to #guchar * before passing a possibly non-ASCII character in. * - * Return value: the result of converting @c to lower case. - * If @c is not an ASCII upper case letter, - * @c is returned unchanged. - **/ + * Return value: the result of converting @c to lower case. If @c is + * not an ASCII upper case letter, @c is returned unchanged. + */ gchar g_ascii_tolower (gchar c) { @@ -1661,7 +1656,7 @@ g_ascii_tolower (gchar c) /** * g_ascii_toupper: - * @c: any character. + * @c: any character * * Convert a character to ASCII upper case. * @@ -1670,13 +1665,12 @@ g_ascii_tolower (gchar c) * all non-ASCII characters unchanged, even if they are upper case * letters in a particular character set. Also unlike the standard * library function, this takes and returns a char, not an int, so - * don't call it on EOF but no need to worry about casting to #guchar + * don't call it on %EOF but no need to worry about casting to #guchar * before passing a possibly non-ASCII character in. * - * Return value: the result of converting @c to upper case. - * If @c is not an ASCII lower case letter, - * @c is returned unchanged. - **/ + * Return value: the result of converting @c to upper case. If @c is not + * an ASCII lower case letter, @c is returned unchanged. + */ gchar g_ascii_toupper (gchar c) { @@ -1685,16 +1679,15 @@ g_ascii_toupper (gchar c) /** * g_ascii_digit_value: - * @c: an ASCII character. + * @c: an ASCII character * - * Determines the numeric value of a character as a decimal - * digit. Differs from g_unichar_digit_value() because it takes - * a char, so there's no worry about sign extension if characters - * are signed. + * Determines the numeric value of a character as a decimal digit. + * Differs from g_unichar_digit_value() because it takes a char, so + * there's no worry about sign extension if characters are signed. * - * Return value: If @c is a decimal digit (according to - * g_ascii_isdigit()), its numeric value. Otherwise, -1. - **/ + * Return value: If @c is a decimal digit (according to g_ascii_isdigit()), + * its numeric value. Otherwise, -1. + */ int g_ascii_digit_value (gchar c) { @@ -1712,9 +1705,9 @@ g_ascii_digit_value (gchar c) * a char, so there's no worry about sign extension if characters * are signed. * - * Return value: If @c is a hex digit (according to - * g_ascii_isxdigit()), its numeric value. Otherwise, -1. - **/ + * Return value: If @c is a hex digit (according to g_ascii_isxdigit()), + * its numeric value. Otherwise, -1. + */ int g_ascii_xdigit_value (gchar c) { @@ -1727,8 +1720,8 @@ g_ascii_xdigit_value (gchar c) /** * g_ascii_strcasecmp: - * @s1: string to compare with @s2. - * @s2: string to compare with @s1. + * @s1: string to compare with @s2 + * @s2: string to compare with @s1 * * Compare two strings, ignoring the case of ASCII characters. * @@ -1747,8 +1740,8 @@ g_ascii_xdigit_value (gchar c) * Both @s1 and @s2 must be non-%NULL. * * Return value: 0 if the strings match, a negative value if @s1 < @s2, - * or a positive value if @s1 > @s2. - **/ + * or a positive value if @s1 > @s2. + */ gint g_ascii_strcasecmp (const gchar *s1, const gchar *s2) @@ -1772,9 +1765,9 @@ g_ascii_strcasecmp (const gchar *s1, /** * g_ascii_strncasecmp: - * @s1: string to compare with @s2. - * @s2: string to compare with @s1. - * @n: number of characters to compare. + * @s1: string to compare with @s2 + * @s2: string to compare with @s1 + * @n: number of characters to compare * * Compare @s1 and @s2, ignoring the case of ASCII characters and any * characters after the first @n in each string. @@ -1788,12 +1781,12 @@ g_ascii_strcasecmp (const gchar *s1, * corresponding to ASCII letters always represent themselves. * * Return value: 0 if the strings match, a negative value if @s1 < @s2, - * or a positive value if @s1 > @s2. - **/ + * or a positive value if @s1 > @s2. + */ gint g_ascii_strncasecmp (const gchar *s1, const gchar *s2, - gsize n) + gsize n) { gint c1, c2; @@ -1818,18 +1811,18 @@ g_ascii_strncasecmp (const gchar *s1, /** * g_strcasecmp: - * @s1: a string. - * @s2: a string to compare with @s1. + * @s1: a string + * @s2: a string to compare with @s1 * * A case-insensitive string comparison, corresponding to the standard * strcasecmp() function on platforms which support it. * * Return value: 0 if the strings match, a negative value if @s1 < @s2, - * or a positive value if @s1 > @s2. + * or a positive value if @s1 > @s2. * - * Deprecated:2.2: See g_strncasecmp() for a discussion of why this function - * is deprecated and how to replace it. - **/ + * Deprecated:2.2: See g_strncasecmp() for a discussion of why this + * function is deprecated and how to replace it. + */ gint g_strcasecmp (const gchar *s1, const gchar *s2) @@ -1863,33 +1856,33 @@ g_strcasecmp (const gchar *s1, /** * g_strncasecmp: - * @s1: a string. - * @s2: a string to compare with @s1. - * @n: the maximum number of characters to compare. + * @s1: a string + * @s2: a string to compare with @s1 + * @n: the maximum number of characters to compare * * A case-insensitive string comparison, corresponding to the standard - * strncasecmp() function on platforms which support it. - * It is similar to g_strcasecmp() except it only compares the first @n - * characters of the strings. + * strncasecmp() function on platforms which support it. It is similar + * to g_strcasecmp() except it only compares the first @n characters of + * the strings. * * Return value: 0 if the strings match, a negative value if @s1 < @s2, - * or a positive value if @s1 > @s2. - * - * Deprecated:2.2: The problem with g_strncasecmp() is that it does the - * comparison by calling toupper()/tolower(). These functions are - * locale-specific and operate on single bytes. However, it is impossible - * to handle things correctly from an I18N standpoint by operating on - * bytes, since characters may be multibyte. Thus g_strncasecmp() is - * broken if your string is guaranteed to be ASCII, since it's - * locale-sensitive, and it's broken if your string is localized, since - * it doesn't work on many encodings at all, including UTF-8, EUC-JP, - * etc. - * - * There are therefore two replacement techniques: g_ascii_strncasecmp(), - * which only works on ASCII and is not locale-sensitive, and - * g_utf8_casefold() followed by strcmp() on the resulting strings, which is - * good for case-insensitive sorting of UTF-8. - **/ + * or a positive value if @s1 > @s2. + * + * Deprecated:2.2: The problem with g_strncasecmp() is that it does + * the comparison by calling toupper()/tolower(). These functions + * are locale-specific and operate on single bytes. However, it is + * impossible to handle things correctly from an internationalization + * standpoint by operating on bytes, since characters may be multibyte. + * Thus g_strncasecmp() is broken if your string is guaranteed to be + * ASCII, since it is locale-sensitive, and it's broken if your string + * is localized, since it doesn't work on many encodings at all, + * including UTF-8, EUC-JP, etc. + * + * There are therefore two replacement techniques: g_ascii_strncasecmp(), + * which only works on ASCII and is not locale-sensitive, and + * g_utf8_casefold() followed by strcmp() on the resulting strings, + * which is good for case-insensitive sorting of UTF-8. + */ gint g_strncasecmp (const gchar *s1, const gchar *s2, @@ -1926,8 +1919,8 @@ g_strncasecmp (const gchar *s1, /** * g_strdelimit: * @string: the string to convert - * @delimiters: (allow-none): a string containing the current delimiters, or %NULL - * to use the standard delimiters defined in #G_STR_DELIMITERS + * @delimiters: (allow-none): a string containing the current delimiters, + * or %NULL to use the standard delimiters defined in #G_STR_DELIMITERS * @new_delimiter: the new delimiter character * * Converts any delimiter characters in @string to @new_delimiter. @@ -1968,10 +1961,10 @@ g_strdelimit (gchar *string, * @valid_chars: bytes permitted in @string * @substitutor: replacement character for disallowed bytes * - * For each character in @string, if the character is not in - * @valid_chars, replaces the character with @substitutor. - * Modifies @string in place, and return @string itself, not - * a copy. The return value is to allow nesting such as + * For each character in @string, if the character is not in @valid_chars, + * replaces the character with @substitutor. Modifies @string in place, + * and return @string itself, not a copy. The return value is to allow + * nesting such as * |[ * g_ascii_strup (g_strcanon (str, "abc", '?')) * ]| @@ -2424,7 +2417,7 @@ g_strsplit_set (const gchar *string, * Frees a %NULL-terminated array of strings, and the array itself. * If called on a %NULL value, g_strfreev() simply returns. - **/ + */ void g_strfreev (gchar **str_array) { @@ -2480,7 +2473,8 @@ g_strdupv (gchar **str_array) /** * g_strjoinv: - * @separator: (allow-none): a string to insert between each of the strings, or %NULL + * @separator: (allow-none): a string to insert between each of the + * strings, or %NULL * @str_array: a %NULL-terminated array of strings to join * * Joins a number of strings together to form one long string, with the @@ -2532,7 +2526,8 @@ g_strjoinv (const gchar *separator, /** * g_strjoin: - * @separator: (allow-none): a string to insert between each of the strings, or %NULL + * @separator: (allow-none): a string to insert between each of the + * strings, or %NULL * @...: a %NULL-terminated list of strings to join * * Joins a number of strings together to form one long string, with the diff --git a/glib/gthread-posix.c b/glib/gthread-posix.c index ae6d34b22..79afd3292 100644 --- a/glib/gthread-posix.c +++ b/glib/gthread-posix.c @@ -195,10 +195,10 @@ g_mutex_clear (GMutex *mutex) * current thread will block until @mutex is unlocked by the other * thread. * - * #GMutex is neither guaranteed to be recursive nor to be + * #GMutex is neither guaranteed to be recursive nor to be * non-recursive. As such, calling g_mutex_lock() on a #GMutex that has * already been locked by the same thread results in undefined behaviour - * (including but not limited to deadlocks). + * (including but not limited to deadlocks). */ void g_mutex_lock (GMutex *mutex) @@ -236,11 +236,10 @@ g_mutex_unlock (GMutex *mutex) * it immediately returns %FALSE. Otherwise it locks @mutex and returns * %TRUE. * - * #GMutex is neither guaranteed to be recursive nor to be + * #GMutex is neither guaranteed to be recursive nor to be * non-recursive. As such, calling g_mutex_lock() on a #GMutex that has * already been locked by the same thread results in undefined behaviour * (including but not limited to deadlocks or arbitrary return values). - * * Returns: %TRUE if @mutex could be locked */ diff --git a/glib/gthread.c b/glib/gthread.c index a7687e437..d410dbc87 100644 --- a/glib/gthread.c +++ b/glib/gthread.c @@ -907,12 +907,10 @@ g_thread_new_internal (const gchar *name, * Calling g_thread_exit (retval) is equivalent to * returning @retval from the function @func, as given to g_thread_new(). * - * - * You must only call g_thread_exit() from a thread that you created - * yourself with g_thread_new() or related APIs. You must not call - * this function from a thread created with another threading library - * or or from within a #GThreadPool. - * + * You must only call g_thread_exit() from a thread that you created + * yourself with g_thread_new() or related APIs. You must not call + * this function from a thread created with another threading library + * or or from within a #GThreadPool. */ void g_thread_exit (gpointer retval) diff --git a/glib/gutils.c b/glib/gutils.c index fccf9947c..071471d77 100644 --- a/glib/gutils.c +++ b/glib/gutils.c @@ -795,21 +795,19 @@ g_get_real_name (void) * If the path given in HOME is non-absolute, does not * exist, or is not a directory, the result is undefined. * - * - * Before version 2.36 this function would ignore the - * HOME environment variable, taking the value from the - * passwd database instead. This was changed to - * increase the compatibility of GLib with other programs (and the XDG - * basedir specification) and to increase testability of programs - * based on GLib (by making it easier to run them from test - * frameworks). - * - * If your program has a strong requirement for either the new or the - * old behaviour (and if you don't wish to increase your GLib - * dependency to ensure that the new behaviour is in effect) then you - * should either directly check the HOME environment - * variable yourself or unset it before calling any functions in GLib. - * + * Before version 2.36 this function would ignore the + * HOME environment variable, taking the value from the + * passwd database instead. This was changed to + * increase the compatibility of GLib with other programs (and the XDG + * basedir specification) and to increase testability of programs + * based on GLib (by making it easier to run them from test + * frameworks). + * + * If your program has a strong requirement for either the new or the + * old behaviour (and if you don't wish to increase your GLib + * dependency to ensure that the new behaviour is in effect) then you + * should either directly check the HOME environment + * variable yourself or unset it before calling any functions in GLib. * * Returns: the current user's home directory */ diff --git a/gobject/gbinding.c b/gobject/gbinding.c index c2342d9af..7a9f562c2 100644 --- a/gobject/gbinding.c +++ b/gobject/gbinding.c @@ -94,10 +94,10 @@ * either one of the #GObject instances it refers to are finalized, or when * the #GBinding instance loses its last reference. * - * Bindings for languages with garbage collection can use + * Bindings for languages with garbage collection can use * g_binding_unbind() to explicitly release a binding between the source * and target properties, instead of relying on the last reference on the - * binding, source, and target instances to drop. + * binding, source, and target instances to drop. * * #GBinding is available since GObject 2.26 */ @@ -704,7 +704,7 @@ g_binding_init (GBinding *binding) * g_binding_get_flags: * @binding: a #GBinding * - * Retrieves the flags passed when constructing the #GBinding + * Retrieves the flags passed when constructing the #GBinding. * * Return value: the #GBindingFlags used by the #GBinding * @@ -722,7 +722,7 @@ g_binding_get_flags (GBinding *binding) * g_binding_get_source: * @binding: a #GBinding * - * Retrieves the #GObject instance used as the source of the binding + * Retrieves the #GObject instance used as the source of the binding. * * Return value: (transfer none): the source #GObject * @@ -740,7 +740,7 @@ g_binding_get_source (GBinding *binding) * g_binding_get_target: * @binding: a #GBinding * - * Retrieves the #GObject instance used as the target of the binding + * Retrieves the #GObject instance used as the target of the binding. * * Return value: (transfer none): the target #GObject * @@ -759,7 +759,7 @@ g_binding_get_target (GBinding *binding) * @binding: a #GBinding * * Retrieves the name of the property of #GBinding:source used as the source - * of the binding + * of the binding. * * Return value: the name of the source property * @@ -778,7 +778,7 @@ g_binding_get_source_property (GBinding *binding) * @binding: a #GBinding * * Retrieves the name of the property of #GBinding:target used as the target - * of the binding + * of the binding. * * Return value: the name of the target property * @@ -799,10 +799,10 @@ g_binding_get_target_property (GBinding *binding) * Explicitly releases the binding between the source and the target * property expressed by @binding. * - * This function will release the reference that is being held on + * This function will release the reference that is being held on * the @binding instance; if you want to hold on to the #GBinding instance * after calling g_binding_unbind(), you will need to hold a reference - * to it. + * to it. * * Since: 2.38 */ @@ -822,13 +822,13 @@ g_binding_unbind (GBinding *binding) * @target_property: the property on @target to bind * @flags: flags to pass to #GBinding * @transform_to: (scope notified) (allow-none): the transformation function - * from the @source to the @target, or %NULL to use the default + * from the @source to the @target, or %NULL to use the default * @transform_from: (scope notified) (allow-none): the transformation function - * from the @target to the @source, or %NULL to use the default + * from the @target to the @source, or %NULL to use the default * @user_data: custom data to be passed to the transformation functions, - * or %NULL + * or %NULL * @notify: function to be called when disposing the binding, to free the - * resources used by the transformation functions + * resources used by the transformation functions * * Complete version of g_object_bind_property(). * @@ -848,15 +848,15 @@ g_binding_unbind (GBinding *binding) * * A #GObject can have multiple bindings. * - * The same @user_data parameter will be used for both @transform_to + * The same @user_data parameter will be used for both @transform_to * and @transform_from transformation functions; the @notify function will * be called once, when the binding is removed. If you need different data * for each transformation function, please use - * g_object_bind_property_with_closures() instead. + * g_object_bind_property_with_closures() instead. * * Return value: (transfer none): the #GBinding instance representing the - * binding between the two #GObject instances. The binding is released - * whenever the #GBinding reference count reaches zero. + * binding between the two #GObject instances. The binding is released + * whenever the #GBinding reference count reaches zero. * * Since: 2.26 */ @@ -1036,8 +1036,8 @@ g_object_bind_property_full (gpointer source, * A #GObject can have multiple bindings. * * Return value: (transfer none): the #GBinding instance representing the - * binding between the two #GObject instances. The binding is released - * whenever the #GBinding reference count reaches zero. + * binding between the two #GObject instances. The binding is released + * whenever the #GBinding reference count reaches zero. * * Since: 2.26 */ @@ -1172,23 +1172,23 @@ bind_with_closures_free_func (gpointer data) * @target_property: the property on @target to bind * @flags: flags to pass to #GBinding * @transform_to: a #GClosure wrapping the transformation function - * from the @source to the @target, or %NULL to use the default + * from the @source to the @target, or %NULL to use the default * @transform_from: a #GClosure wrapping the transformation function - * from the @target to the @source, or %NULL to use the default + * from the @target to the @source, or %NULL to use the default * * Creates a binding between @source_property on @source and @target_property * on @target, allowing you to set the transformation functions to be used by * the binding. * * This function is the language bindings friendly version of - * g_object_bind_property_full(), using #GClosures instead of + * g_object_bind_property_full(), using #GClosures instead of * function pointers. * * Rename to: g_object_bind_property_full * * Return value: (transfer none): the #GBinding instance representing the - * binding between the two #GObject instances. The binding is released - * whenever the #GBinding reference count reaches zero. + * binding between the two #GObject instances. The binding is released + * whenever the #GBinding reference count reaches zero. * * Since: 2.26 */ diff --git a/gobject/gobject.c b/gobject/gobject.c index 18c7aee35..a18fcfb12 100644 --- a/gobject/gobject.c +++ b/gobject/gobject.c @@ -815,7 +815,6 @@ g_object_interface_find_property (gpointer g_iface, * a property implementation in a parent class or to provide * the implementation of a property from an interface. * - * * Internally, overriding is implemented by creating a property of type * #GParamSpecOverride; generally operations that query the properties of * the object class, such as g_object_class_find_property() or @@ -826,7 +825,6 @@ g_object_interface_find_property (gpointer g_iface, * correct. For virtually all uses, this makes no difference. If you * need to get the overridden property, you can call * g_param_spec_get_redirect_target(). - * * * Since: 2.4 */ -- 2.34.1