luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-09 19:06:15 +01:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Don't use the note tag

Browse Source 
More markup avoidance.
This commit is contained in:
Matthias Clasen 2014-01-31 14:56:10 -05:00
parent 4cbee6a35b
commit c575d24dfb
22 changed files with 770 additions and 866 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
gio/gioscheduler.c
View File

@ -29,14 +29,12 @@
* @short_description: I/O Scheduler
* @include: gio/gio.h
*
* <note><para>
* As of GLib 2.36, the <literal>g_io_scheduler</literal> methods
* are deprecated in favor of #GThreadPool and #GTask.
* </para></note>
* 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;

6
gio/gsettingsbackend.c
View File

@ -75,13 +75,11 @@ static gboolean g_settings_has_backend;
* g_settings_backend_create_tree() is a convenience function to create
* suitable trees.
*
* <note><para>
* 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
* <filename>gio/gsettingsbackend.h</filename>
* </para></note>
**/
static gboolean

8
gio/gsimpleasyncresult.c
View File

@ -34,12 +34,10 @@
* SECTION:gsimpleasyncresult
* @short_description: Simple asynchronous results implementation
* @include: gio/gio.h
* @see_also: #GAsyncResult
* @see_also: #GAsyncResult, #GTask
*
* <note><para>
* As of GLib 2.36, #GSimpleAsyncResult is deprecated in favor of
* #GTask, which provides a simpler API.
* </para></note>
* As of GLib 2.36, #GSimpleAsyncResult is deprecated in favor of
* #GTask, which provides a simpler API.
*
* #GSimpleAsyncResult implements #GAsyncResult.
*

4
gio/gthemedicon.c
View File

@ -390,10 +390,8 @@ g_themed_icon_get_names (GThemedIcon *icon)
*
* Append a name to the list of icons from within @icon.
*
* <note><para>
* Note that doing so invalidates the hash computed by prior calls
* to g_icon_hash().
* </para></note>
*/
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><para>
* Note that doing so invalidates the hash computed by prior calls
* to g_icon_hash().
* </para></note>
*
* Since: 2.18
*/

271
glib/docs.c
View File

@ -409,11 +409,9 @@
* for scanning and printing values of type #gint64 or #guint64.
* It is a string literal.
*
* <note><para>
* 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.
* </para></note>
*
* 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.
*
* <note><para>
* 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.
* </para></note>
*/
/**
* 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.
*
* <note><para>
* 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.
* </para></note>
*/
/**
@ -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 <literal>G_IMPLEMENTS_INLINES</literal>
* 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 <literal>extern "C"</literal>
* 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 <literal>extern "C"</literal>
* 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
* <code>identifier1identifier2</code> 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 <literal>typedef</literal> is valid.
* any place where a typedef is valid.
*
* <note><para>
* A <literal>typedef</literal> is generally allowed in
* exactly the same places that a variable declaration is
* allowed. For this reason, you should not use
* <literal>G_STATIC_ASSERT</literal> in the middle of
* blocks of code.
* </para></note>
* 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 <literal>G_STATIC_ASSERT</literal>, 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 <literal>__extension__</literal> when <command>gcc</command>
* is used as the compiler. This simply tells <command>gcc</command> not
* to warn about the following non-standard code when compiling with the
* <option>-pedantic</option> 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>-pedantic</option> option.
*/
/**
* G_GNUC_CONST:
*
* Expands to the GNU C <literal>const</literal> function attribute if
* the compiler is <command>gcc</command>. 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.
*
* <note><para>
* A function that has pointer arguments and examines the data pointed to
* must <emphasis>not</emphasis> 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.
* </para></note>
* 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 <literal>pure</literal> function attribute if the
* compiler is <command>gcc</command>. 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 <literal>malloc</literal> function attribute if the
* compiler is <command>gcc</command>. 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 <literal>alloc_size</literal> function attribute
* if the compiler is a new enough <command>gcc</command>. This attribute
* tells the compiler that the function returns a pointer to memory of a
* size that is specified by the @x<!-- -->th 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 <literal>alloc_size</literal> function attribute
* if the compiler is a new enough <command>gcc</command>. 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 <literal>deprecated</literal> attribute if the
* compiler is <command>gcc</command>. It can be used to mark typedefs,
* variables and functions as deprecated. When called with the
* <option>-Wdeprecated-declarations</option> 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>-Wdeprecated-declarations</option> 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 <command>gcc</command> 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 <command>gcc</command> (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 <literal>-Wdeprecated-declarations</literal>
@ -2024,8 +2006,8 @@
* G_GNUC_END_IGNORE_DEPRECATIONS:
*
* Undoes the effect of %G_GNUC_BEGIN_IGNORE_DEPRECATIONS, telling
* <command>gcc</command> 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 <literal>noreturn</literal> function attribute
* if the compiler is <command>gcc</command>. 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 <literal>unused</literal> function attribute if
* the compiler is <command>gcc</command>. 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 <literal>format</literal> function attribute
* if the compiler is <command>gcc</command>. 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 <literal>format</literal> function attribute
* if the compiler is <command>gcc</command>. 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 <literal>format_arg</literal> function attribute
* if the compiler is <command>gcc</command>. 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 <literal>sentinel</literal> function attribute
* if the compiler is <command>gcc</command>, 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 <literal>warn_unused_result</literal> function
* attribute if the compiler is <command>gcc</command>, 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
* <literal>__FUNCTION__</literal> on <command>gcc</command> 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
* <literal>__PRETTY_FUNCTION__</literal> on <command>gcc</command>
* 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 <literal>no_instrument_function</literal> function
* attribute if the compiler is <command>gcc</command>. Functions with this
* attribute will not be instrumented for profiling, when the compiler is
* called with the <option>-finstrument-functions</option> 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>-finstrument-functions</option> 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 <literal>__attribute__((visibility("hidden")))</literal>.
* When using the Sun Studio compiler, it expands to <literal>__hidden</literal>.
* 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 <literal>may_alias</literal> type attribute
* if the compiler is <command>gcc</command>. 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: */

676
glib/garray.c
View File

File diff suppressed because it is too large Load Diff

24
glib/ggettext.c
View File

@ -520,11 +520,11 @@ g_dngettext (const gchar *domain,
* See the C_() macro for a different way to mark up translatable strings
* with context.
*
* <note><para>If you are using the Q_() macro, you need to make sure
* that you pass <option>--keyword=Q_</option> 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
* <option>--keyword=Q_</option> to xgettext when extracting messages.
* If you are using GNU gettext >= 0.15, you can also use
* <option>--keyword=Q_:1g</option> to let xgettext split the context
* string off into a msgctxt line in the po file.</para></note>
* 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");
* ]|
*
* <note><para>If you are using the C_() macro, you need to make sure
* that you pass <option>--keyword=C_:1c,2</option> to xgettext when
* extracting messages. Note that this only works with GNU
* gettext >= 0.15.</para></note>
* If you are using the C_() macro, you need to make sure that you pass
* <option>--keyword=C_:1c,2</option> 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,
* }
* ]|
*
* <note><para>If you are using the NC_() macro, you need to make sure
* that you pass <option>--keyword=NC_:1c,2</option> 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.
* </para></note>
* If you are using the NC_() macro, you need to make sure that you pass
* <option>--keyword=NC_:1c,2</option> 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
*/

7
glib/gkeyfile.c
View File

@ -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.
*
* <note>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.</note>
* 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
**/

18
glib/glib-unix.c
View File

@ -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
* <literal>FD_CLOEXEC</literal>. If for example you want to configure
* <literal>O_NONBLOCK</literal>, 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().
*
* <note>This function does *not* take <literal>O_CLOEXEC</literal>, it takes
* <literal>FD_CLOEXEC</literal> as if for fcntl(); these are
* different on Linux/glibc.</note>
* 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 <literal>O_NONBLOCK</literal>, but
* on some older ones may use <literal>O_NDELAY</literal>.
* according to @nonblock. On most systems this uses %O_NONBLOCK, but
* on some older ones may use %O_NDELAY.
*
* Returns: %TRUE if successful
*

31
glib/glist.c
View File

@ -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.
*
* <note><para>
* If list elements contain dynamically-allocated memory,
* you should either use g_list_free_full() or free them manually
* first.
* </para></note>
* 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");
* ]|
*
* <note><para>
* 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.
* </para></note>
* 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><para>
* 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.
* </para></note>
*
* 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.
*
* <note><para>
* This function iterates over the whole list to count its elements.
* Use a <link linkend="glib-Double-ended-Queues">GQueue</link> instead
* of a GList if you regularly need the number of items.
* </para></note>
* 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.
*
* <note><para>
* 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()
* </para></note>
* 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.
*
* <note><para>
* 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()
* </para></note>
* with g_list_sort().
*
* Returns: the (possibly changed) start of the #GList
*

52
glib/gmacros.h
View File

@ -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. */

15
glib/gmem.c
View File

@ -66,18 +66,15 @@ static GMemVTable glib_mem_vtable = {
*
* These functions provide support for allocating and freeing memory.
*
* <note>
* 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.
* </note>
*
* <note>
* 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().
* </note>
* 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 --- */

7
glib/gqueue.c
View File

@ -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.
*
* <note><para>
* If queue elements contain dynamically-allocated memory,
* you should either use g_queue_free_full() or free them manually
* first.
* </para></note>
* 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)

8
glib/gsequence.c
View File

@ -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().
*
* <note><para>
* 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.
* </para></note>
*
* 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.
*
* <note><para>
* 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.
* </para></note>
*
* 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().
*
* <note><para>
* 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.
* </para></note>
*
* 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.
*
* <note><para>
* 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.
* </para></note>
*
* Return value: an #GSequenceIter pointing to the position of
* the first item found equal to @data according to @cmp_func

30
glib/gslist.c
View File

@ -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.
*
* <note><para>
* If list elements contain dynamically-allocated memory,
* you should either use g_slist_free_full() or free them manually
* first.
* </para></note>
*/
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.
*
* <note><para>
* The return value is the new start of the list, which may
* have changed, so make sure you store the new value.
* </para></note>
*
* <note><para>
* 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.
* </para></note>
*
* |[
* /&ast; Notice that these are initialized to the empty list. &ast;/
@ -242,10 +236,8 @@ g_slist_append (GSList *list,
*
* Adds a new element on to the start of the list.
*
* <note><para>
* The return value is the new start of the list, which
* may have changed, so make sure you store the new value.
* </para></note>
*
* |[
* /&ast; Notice that it is initialized to the empty list. &ast;/
@ -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.
*
* <note>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.</note>
* 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.
*
* <note>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.</note>
* 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><para>
* 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.
* </para></note>
*
* Returns: a copy of @list
*/
@ -828,9 +818,7 @@ g_slist_index (GSList *list,
*
* Gets the last element in a #GSList.
*
* <note><para>
* This function iterates over the whole list.
* </para></note>
*
* 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.
*
* <note><para>
* This function iterates over the whole list to
* count its elements.
* </para></note>
*
* Returns: the number of elements in the #GSList
*/

161
glib/gspawn.c
View File

@ -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.
*
* <note><para>
* 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.
* </para></note>
* 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><para> 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.
* </para></note>
* 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
* <function>CreateProcess()</function> doesn't use argument vectors,
* but a command line. The C runtime library's
* <function>spawn*()</function> 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
* <function>spawn*()</function> 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 <literal>SIGCHLD</literal> 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 <literal>argv[0]</literal> need not be an absolute path, it
* will be looked for in the <envar>PATH</envar> environment variable.
* %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an absolute path, it
* will be looked for in the <envar>PATH</envar> 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 <envar>PATH</envar> environment
* variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an absolute
* path, it will be looked for in the <envar>PATH</envar> 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 <function>WaitFor*()</function> 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 <literal>argv[0]</literal> is not found). Typically
* the <literal>message</literal> 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 <literal>message</literal> 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().
*
* <note><para>
* 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.
* </para></note>
*
* 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
* <literal>waitpid(2)</literal> returns, and on Windows it is
* guaranteed to be the result of
* <literal>GetExitCodeProcess()</literal>. 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 <literal>domain</literal> and <literal>code</literal> 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 <literal>WIFEXITED</literal> 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
* <literal>WIFEXITED()</literal> and <literal>WEXITSTATUS()</literal>
* 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

215
glib/gstrfuncs.c
View File

@ -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.
*
* <note><para>
* To copy a number of characters from a UTF-8 encoded string, use
* g_utf8_strncpy() instead.
* </para></note>
*
* 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.
*
* <note><para>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.</para></note>
* 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).
*
* <note><para>Caveat: this is supposedly a more secure alternative to
* strcat() or strncat(), but for real security g_strconcat() is harder
* to mess up.</para></note>
* 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 <literal>EOF</literal> 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 <literal>EOF</literal> 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 &lt; @s2,
* or a positive value if @s1 &gt; @s2.
**/
* or a positive value if @s1 &gt; @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 &lt; @s2,
* or a positive value if @s1 &gt; @s2.
**/
* or a positive value if @s1 &gt; @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 &lt; @s2,
* or a positive value if @s1 &gt; @s2.
* or a positive value if @s1 &gt; @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 &lt; @s2,
* or a positive value if @s1 &gt; @s2.
* or a positive value if @s1 &gt; @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.
* 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.
**/
* 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

7
glib/gthread-posix.c
View File

@ -195,10 +195,10 @@ g_mutex_clear (GMutex *mutex)
* current thread will block until @mutex is unlocked by the other
* thread.
*
* <note>#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).</note>
* (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.
*
* <note>#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).
* </note>
* Returns: %TRUE if @mutex could be locked
*/

10
glib/gthread.c
View File

@ -907,12 +907,10 @@ g_thread_new_internal (const gchar *name,
* Calling <literal>g_thread_exit (retval)</literal> is equivalent to
* returning @retval from the function @func, as given to g_thread_new().
*
* <note><para>
* 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.
* </para></note>
* 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)

28
glib/gutils.c
View File

@ -795,21 +795,19 @@ g_get_real_name (void)
* If the path given in <envar>HOME</envar> is non-absolute, does not
* exist, or is not a directory, the result is undefined.
*
* <note><para>
* Before version 2.36 this function would ignore the
* <envar>HOME</envar> environment variable, taking the value from the
* <filename>passwd</filename> 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).
* </para><para>
* 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 <envar>HOME</envar> environment
* variable yourself or unset it before calling any functions in GLib.
* </para></note>
* Before version 2.36 this function would ignore the
* <envar>HOME</envar> environment variable, taking the value from the
* <filename>passwd</filename> 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 <envar>HOME</envar> environment
* variable yourself or unset it before calling any functions in GLib.
*
* Returns: the current user's home directory
*/

48
gobject/gbinding.c
View File

@ -94,10 +94,10 @@
* either one of the #GObject instances it refers to are finalized, or when
* the #GBinding instance loses its last reference.
*
* <note><para>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.</para></note>
* 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.
*
* <note>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.</note>
* 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.
*
* <note>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.</note>
* 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 #GClosure<!-- -->s 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
*/

2
gobject/gobject.c
View File

@ -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.
*
* <note>
* 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().
* </note>
*
* Since: 2.4
*/