X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=glib%2Fdocs.c;h=5a20cf2f6c88d9e82580e6a5d04dd740c84ba43d;hb=49a5d0f6f2aed99cd78f25655f137f4448e47d92;hp=f680ae07178af5711b291968bc974affc3d4136f;hpb=ca05902a5883020add334e542a63d7f9381a3117;p=platform%2Fupstream%2Fglib.git
diff --git a/glib/docs.c b/glib/docs.c
index f680ae0..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.
@@ -2020,22 +2013,77 @@
*/
/**
+ * G_DEPRECATED:
+ *
+ * This macro is similar to %G_GNUC_DEPRECATED, and can be used to mark
+ * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED, it is
+ * meant to be portable across different compilers and must be placed
+ * before the function declaration.
+ *
+ * Since: 2.32
+ */
+
+/**
+ * G_DEPRECATED_FOR:
+ * @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
+ * before the function declaration.
+ *
+ * Since: 2.32
+ */
+
+/**
+ * G_UNAVAILABLE:
+ * @maj: the major version that introduced the symbol
+ * @min: the minor version that introduced the symbol
+ *
+ * This macro can be used to mark a function declaration as unavailable.
+ * It must be placed before the function declaration. Use of a function
+ * that has been annotated with this macros will produce a compiler warning.
+ *
+ * Since: 2.32
+ */
+
+/**
+ * GLIB_DISABLE_DEPRECATION_WARNINGS:
+ *
+ * A macro that should be defined before including the glib.h header.
+ * If it is defined, no compiler warnings will be produced for uses
+ * of deprecated GLib APIs.
+ */
+
+/**
* 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.
*/
/**
@@ -2044,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,
@@ -2064,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);
* ]|
*/
@@ -2092,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
*/
@@ -2104,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
*/
@@ -2115,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.
*/
/**
@@ -2152,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,
@@ -2173,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
@@ -2189,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");
* ]|
@@ -2206,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");
* ]|
@@ -2230,6 +2294,12 @@
* Since: 2.4
*/
+/**
+ * G_HAVE_GNUC_VISIBILITY:
+ *
+ * Defined to 1 if gcc-style visibility handling is supported.
+ */
+
/* Windows Compatibility Functions {{{1 */
/**
@@ -2255,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.
@@ -2289,6 +2359,6 @@
*
* Since: 2.6
*/
-
-/* Epilogue {{{1 */
+
+ /* Epilogue {{{1 */
/* vim: set foldmethod=marker: */