X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=glib%2Fdocs.c;h=5a20cf2f6c88d9e82580e6a5d04dd740c84ba43d;hb=30ed5f53e205e6bfc35126a9d3c62dac8a9c5dad;hp=049bc73232007f0f13b49e782af2dcf04443de9a;hpb=4780ee5d4a6057312abee9a8fcaad45a9897fe0e;p=platform%2Fupstream%2Fglib.git diff --git a/glib/docs.c b/glib/docs.c index 049bc73..5a20cf2 100644 --- a/glib/docs.c +++ b/glib/docs.c @@ -12,9 +12,7 @@ * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public - * License along with this library; if not, write to the - * Free Software Foundation, Inc., 59 Temple Place - Suite 330, - * Boston, MA 02111-1307, USA. + * License along with this library; if not, see . * * Author: Matthias Clasen */ @@ -64,8 +62,7 @@ * gpointer: * * An untyped pointer. - * #gpointer looks better and is easier to use - * than void*. + * #gpointer looks better and is easier to use than void*. */ /** @@ -81,19 +78,19 @@ /** * gchar: * - * Corresponds to the standard C char type. + * Corresponds to the standard C char type. */ /** * guchar: * - * Corresponds to the standard C unsigned char type. + * Corresponds to the standard C unsigned char type. */ /** * gint: * - * Corresponds to the standard C int type. + * Corresponds to the standard C int type. * Values of this type can range from #G_MININT to #G_MAXINT. */ @@ -112,7 +109,7 @@ /** * guint: * - * Corresponds to the standard C unsigned int type. + * Corresponds to the standard C unsigned int type. * Values of this type can range from 0 to #G_MAXUINT. */ @@ -125,7 +122,7 @@ /** * gshort: * - * Corresponds to the standard C short type. + * Corresponds to the standard C short type. * Values of this type can range from #G_MINSHORT to #G_MAXSHORT. */ @@ -144,7 +141,7 @@ /** * gushort: * - * Corresponds to the standard C unsigned short type. + * Corresponds to the standard C unsigned short type. * Values of this type can range from 0 to #G_MAXUSHORT. */ @@ -157,7 +154,7 @@ /** * glong: * - * Corresponds to the standard C long type. + * Corresponds to the standard C long type. * Values of this type can range from #G_MINLONG to #G_MAXLONG. */ @@ -176,7 +173,7 @@ /** * gulong: * - * Corresponds to the standard C unsigned long type. + * Corresponds to the standard C unsigned long type. * Values of this type can range from 0 to #G_MAXULONG. */ @@ -262,7 +259,7 @@ * and conversion specifier and append a conversion specifier. * * The following example prints "0x7b"; - * |[ + * |[ * gint16 value = 123; * g_print ("%#" G_GINT16_MODIFIER "x", value); * ]| @@ -278,10 +275,10 @@ * include the percent-sign, such that you can add precision and length * modifiers between percent-sign and conversion specifier. * - * |[ + * |[ * gint16 in; * gint32 out; - * sscanf ("42", "%" G_GINT16_FORMAT, &in) + * sscanf ("42", "%" G_GINT16_FORMAT, &in) * out = in * 1000; * g_print ("%" G_GINT32_FORMAT, out); * ]| @@ -412,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 */ @@ -427,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). * @@ -460,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. - * */ /** @@ -491,7 +482,7 @@ /** * gfloat: * - * Corresponds to the standard C float type. + * Corresponds to the standard C float type. * Values of this type can range from -#G_MAXFLOAT to #G_MAXFLOAT. */ @@ -501,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. */ /** @@ -513,7 +504,7 @@ /** * gdouble: * - * Corresponds to the standard C double type. + * Corresponds to the standard C double type. * Values of this type can range from -#G_MAXDOUBLE to #G_MAXDOUBLE. */ @@ -523,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. */ /** @@ -536,10 +527,10 @@ * gsize: * * An unsigned integer type of the result of the sizeof operator, - * corresponding to the size_t type defined in C99. + * 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 @@ -577,7 +568,7 @@ * gssize: * * A signed variant of #gsize, corresponding to the - * ssize_t defined on most platforms. + * ssize_t defined on most platforms. * Values of this type can range from #G_MINSSIZE * to #G_MAXSSIZE. * @@ -614,7 +605,7 @@ * goffset: * * A signed integer type that is used for file offsets, - * corresponding to the C99 type off64_t. + * corresponding to the C99 type off64_t. * Values of this type can range from #G_MINOFFSET to * #G_MAXOFFSET. * @@ -670,7 +661,7 @@ /** * gintptr: * - * Corresponds to the C99 type intptr_t, + * Corresponds to the C99 type intptr_t, * a signed integer type that can hold any pointer. * * To print or scan values of this type, use @@ -701,7 +692,7 @@ /** * guintptr: * - * Corresponds to the C99 type uintptr_t, + * Corresponds to the C99 type uintptr_t, * an unsigned integer type that can hold any pointer. * * To print or scan values of this type, use @@ -730,7 +721,7 @@ * data" to a callback, in the form of a void pointer. From time to time * you want to pass an integer instead of a pointer. You could allocate * an integer, with something like: - * |[ + * |[ * int *ip = g_new (int, 1); * *ip = 42; * ]| @@ -740,15 +731,15 @@ * Pointers are always at least 32 bits in size (on all platforms GLib * intends to support). Thus you can store at least 32-bit integer values * in a pointer value. Naively, you might try this, but it's incorrect: - * |[ + * |[ * gpointer p; * int i; * p = (void*) 42; * i = (int) p; * ]| - * Again, that example was not correct, don't copy it. + * Again, that example was not correct, don't copy it. * The problem is that on some systems you need to do this: - * |[ + * |[ * gpointer p; * int i; * p = (void*) (long) 42; @@ -757,11 +748,10 @@ * The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care * to do the right thing on the every platform. * - * You may not store pointers in integers. This is not - * portable in any way, shape or form. These macros only - * allow storing integers in pointers, and only preserve 32 bits of the - * integer; values outside the range of a 32-bit integer will be mangled. - * + * Warning: You may not store pointers in integers. This is not + * portable in any way, shape or form. These macros only allow storing + * integers in pointers, and only preserve 32 bits of the integer; values + * outside the range of a 32-bit integer will be mangled. */ /** @@ -771,9 +761,9 @@ * Stuffs an integer into a pointer type. * * Remember, you may not store pointers in integers. This is not portable - * in any way, shape or form. These macros only allow - * storing integers in pointers, and only preserve 32 bits of the - * integer; values outside the range of a 32-bit integer will be mangled. + * in any way, shape or form. These macros only allow storing integers in + * pointers, and only preserve 32 bits of the integer; values outside the + * range of a 32-bit integer will be mangled. */ /** @@ -784,9 +774,9 @@ * been stored in the pointer with GINT_TO_POINTER(). * * Remember, you may not store pointers in integers. This is not portable - * in any way, shape or form. These macros only allow - * storing integers in pointers, and only preserve 32 bits of the - * integer; values outside the range of a 32-bit integer will be mangled. + * in any way, shape or form. These macros only allow storing integers in + * pointers, and only preserve 32 bits of the integer; values outside the + * range of a 32-bit integer will be mangled. */ /** @@ -818,7 +808,7 @@ * Extracts a #gsize from a pointer. The #gsize must have * been stored in the pointer with GSIZE_TO_POINTER(). */ - + /* Byte order {{{1 */ /** @@ -1422,7 +1412,7 @@ * * Returns: @val converted to the opposite byte order */ - + /* Numerical Definitions {{{1 */ /** @@ -1438,7 +1428,7 @@ * sign, mantissa and exponent of IEEE floats and doubles. These unions are * defined as appropriate for a given platform. IEEE floats and doubles are * supported (used for storage) by at least Intel, PPC and Sparc. See - * IEEE 754-2008 + * [IEEE 754-2008](http://en.wikipedia.org/wiki/IEEE_float) * for more information about IEEE number formats. */ @@ -1521,7 +1511,7 @@ * * Multiplying the base 2 exponent by this number yields the base 10 exponent. */ - + /* Macros {{{1 */ /** @@ -1536,21 +1526,14 @@ * G_OS_WIN32: * * This macro is defined only on Windows. So you can bracket - * Windows-specific code in "#ifdef G_OS_WIN32". - */ - -/** - * G_OS_BEOS: - * - * This macro is defined only on BeOS. So you can bracket - * BeOS-specific code in "#ifdef G_OS_BEOS". + * Windows-specific code in "\#ifdef G_OS_WIN32". */ /** * G_OS_UNIX: * * This macro is defined only on UNIX. So you can bracket - * UNIX-specific code in "#ifdef G_OS_UNIX". + * UNIX-specific code in "\#ifdef G_OS_UNIX". */ /** @@ -1685,8 +1668,8 @@ /** * G_STRUCT_OFFSET: - * @struct_type: a structure type, e.g. GtkWidget - * @member: a field in the structure, e.g. window + * @struct_type: a structure type, e.g. #GtkWidget + * @member: a field in the structure, e.g. @window * * Returns the offset, in bytes, of a member of a struct. * @@ -1696,19 +1679,17 @@ /** * G_CONST_RETURN: * - * If G_DISABLE_CONST_RETURNS is defined, this macro expands - * to nothing. By default, the macro expands to const. - * The macro should be used in place of const for - * functions that return a value that should not be modified. The - * purpose of this macro is to allow us to turn on const - * for returned constant strings by default, while allowing programmers - * who find that annoying to turn it off. This macro should only be used - * for return values and for out parameters, it doesn't - * make sense for in parameters. + * If %G_DISABLE_CONST_RETURNS is defined, this macro expands + * to nothing. By default, the macro expands to const. The macro + * can be used in place of const for functions that return a value + * that should not be modified. The purpose of this macro is to allow + * us to turn on const for returned constant strings by default, while + * allowing programmers who find that annoying to turn it off. This macro + * should only be used for return values and for "out" parameters, it + * doesn't make sense for "in" parameters. * * Deprecated: 2.30: API providers should replace all existing uses with - * const and API consumers should adjust their code - * accordingly + * const and API consumers should adjust their code accordingly */ /** @@ -1720,7 +1701,7 @@ * macro will not work on an array allocated on the heap, only static * arrays or arrays on the stack. */ - + /* Miscellaneous Macros {{{1 */ /** @@ -1737,7 +1718,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. @@ -1765,7 +1746,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. */ @@ -1773,21 +1754,20 @@ * 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. */ /** * G_VA_COPY: - * @ap1: the va_list variable to place a copy of @ap2 in - * @ap2: a va_list + * @ap1: the va_list variable to place a copy of @ap2 in + * @ap2: a va_list * - * Portable way to copy va_list variables. + * Portable way to copy va_list variables. * - * In order to use this function, you must include - * string.h yourself, because this macro may - * use memmove() and GLib does not include string.h - * for you. + * In order to use this function, you must include string.h yourself, + * because this macro may use memmove() and GLib does not include + * string.h for you. */ /** @@ -1797,14 +1777,14 @@ * Accepts a macro or a string and converts it into a string after * preprocessor argument expansion. For example, the following code: * - * |[ + * |[ * #define AGE 27 * const gchar *greeting = G_STRINGIFY (AGE) " today!"; * ]| * * is transformed by the preprocessor into (code equivalent to): * - * |[ + * |[ * const gchar *greeting = "27 today!"; * ]| */ @@ -1815,10 +1795,10 @@ * @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: - * |[ + * |[ * #define GET(traveller,method) G_PASTE(traveller_get_, method) (traveller) * const gchar *name = GET (traveller, name); * const gchar *quest = GET (traveller, quest); @@ -1826,7 +1806,7 @@ * ]| * * is transformed by the preprocessor into: - * |[ + * |[ * const gchar *name = traveller_get_name (traveller); * const gchar *quest = traveller_get_quest (traveller); * GdkColor *favourite = traveller_get_favourite_colour (traveller); @@ -1839,18 +1819,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. * @@ -1861,17 +1837,16 @@ * 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) \ * (G_STATIC_ASSERT_EXPR(sizeof (x) == sizeof (int)), ((x) + 1)) * ]| @@ -1882,49 +1857,55 @@ /** * 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 `-pedantic` 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. See the GNU C documentation for details. + * 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. See the GNU C documentation - * for details. + * 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. + * + * See the GNU C documentation for more details. */ /** * 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). See the GNU C documentation for details. + * 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. + * + * See the GNU C documentation for more details. * * Since: 2.6 */ @@ -1933,11 +1914,15 @@ * 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. - * See the GNU C documentation for details. + * 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. + * + * See the GNU C documentation for more details. * * Since: 2.18 */ @@ -1947,11 +1932,15 @@ * @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. - * See the GNU C documentation for details. + * 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. + * + * See the GNU C documentation for more details. * * Since: 2.18 */ @@ -1959,12 +1948,14 @@ /** * 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. - * See the GNU C documentation for details. + * 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 `-Wdeprecated-declarations` option, + * gcc will generate warnings when deprecated interfaces are used. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. * * Since: 2.2 */ @@ -1975,9 +1966,12 @@ * 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. - * See the GNU C documentation for details. + * 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. + * + * See the GNU C documentation for more details. * * Note that if @f is a macro, it will be expanded in the warning message. * You can enclose it in quotes to prevent this. (The quotes will show up @@ -1989,16 +1983,15 @@ /** * 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 - * then neither macro has any effect.) + * are not compiling with `-Wdeprecated-declarations` then neither macro + * has any effect.) * * This macro can be used either inside or outside of a function body, * but must appear on a line by itself. @@ -2010,8 +2003,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. @@ -2035,8 +2028,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 @@ -2065,20 +2058,32 @@ /** * 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. See the GNU C documentation for - * details. + * 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. + * + * See the GNU C documentation for more details. */ /** * G_GNUC_UNUSED: * - * Expands to the GNU C unused function attribute if - * the compiler is gcc. It is used for declaring - * functions which may never be used. It avoids possible compiler warnings. - * See the GNU C documentation for details. + * 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 + * argument declaration. + * + * |[ + * void my_unused_function (G_GNUC_UNUSED gint unused_argument, + * gint other_argument) G_GNUC_UNUSED; + * ]| + * + * See the GNU C documentation for more details. */ /** @@ -2087,13 +2092,17 @@ * 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. 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 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. + * + * See the GNU C documentation for more details. + * + * |[ * gint g_snprintf (gchar *string, * gulong n, * gchar const *format, @@ -2107,27 +2116,32 @@ * 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). See the GNU C documentation for details. + * 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. + * + * See the GNU C documentation for more details. + * + * |[ * gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2); * ]| */ @@ -2135,11 +2149,14 @@ /** * 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. See the GNU C documentation for details. + * explicit %NULL. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. * * Since: 2.8 */ @@ -2147,10 +2164,13 @@ /** * 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. See the GNU C documentation for details. + * 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. + * + * See the GNU C documentation for more details. * * Since: 2.10 */ @@ -2158,31 +2178,32 @@ /** * 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. - * See the GNU C documentation for details. + * 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 + * `-finstrument-functions` option. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. */ /** @@ -2195,14 +2216,14 @@ * 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, * Sun Studio does not. * - * |[ + * |[ * G_GNUC_INTERNAL * void _g_log_fallback_handler (const gchar *log_domain, * GLogLevelFlags log_level, @@ -2216,10 +2237,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 @@ -2232,7 +2253,7 @@ * Hints the compiler that the expression is likely to evaluate to * a true value. The compiler may use this information for optimizations. * - * |[ + * |[ * if (G_LIKELY (random () != 1)) * g_print ("not one"); * ]| @@ -2249,7 +2270,7 @@ * Hints the compiler that the expression is unlikely to evaluate to * a true value. The compiler may use this information for optimizations. * - * |[ + * |[ * if (G_UNLIKELY (random () == 1)) * g_print ("a random one"); * ]| @@ -2273,6 +2294,12 @@ * Since: 2.4 */ +/** + * G_HAVE_GNUC_VISIBILITY: + * + * Defined to 1 if gcc-style visibility handling is supported. + */ + /* Windows Compatibility Functions {{{1 */ /** @@ -2298,8 +2325,8 @@ * @static: empty or "static" * @dll_name: the name of the (pointer to the) char array where * the DLL name will be stored. If this is used, you must also - * include windows.h. If you need a more - * complex DLL entry point function, you cannot use this + * include `windows.h`. If you need a more complex DLL entry + * point function, you cannot use this * * On Windows, this macro defines a DllMain() function that stores * the actual DLL name that the code being compiled will be included in. @@ -2332,6 +2359,6 @@ * * Since: 2.6 */ - -/* Epilogue {{{1 */ + + /* Epilogue {{{1 */ /* vim: set foldmethod=marker: */