[glib] Docs: Don't use the note tag
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glib] Docs: Don't use the note tag
- Date: Fri, 31 Jan 2014 23:20:26 +0000 (UTC)
commit c575d24dfb78d956e66a522524c7b1d82d0adde7
Author: Matthias Clasen <mclasen redhat com>
Date: Fri Jan 31 14:56:10 2014 -0500
Docs: Don't use the note tag
More markup avoidance.
gio/gioscheduler.c | 8 +-
gio/gsettingsbackend.c | 6 +-
gio/gsimpleasyncresult.c | 8 +-
gio/gthemedicon.c | 4 -
glib/docs.c | 271 +++++++++----------
glib/garray.c | 676 +++++++++++++++++++++++-----------------------
glib/ggettext.c | 24 +-
glib/gkeyfile.c | 7 +-
glib/glib-unix.c | 18 +-
glib/glist.c | 31 +--
glib/gmacros.h | 52 ++--
glib/gmem.c | 15 +-
glib/gqueue.c | 7 +-
glib/gsequence.c | 8 -
glib/gslist.c | 30 +--
glib/gspawn.c | 163 ++++++------
glib/gstrfuncs.c | 219 ++++++++--------
glib/gthread-posix.c | 7 +-
glib/gthread.c | 10 +-
glib/gutils.c | 28 +-
gobject/gbinding.c | 48 ++--
gobject/gobject.c | 2 -
22 files changed, 773 insertions(+), 869 deletions(-)
---
diff --git a/gio/gioscheduler.c b/gio/gioscheduler.c
index ab8afa1..97c4bd2 100644
--- a/gio/gioscheduler.c
+++ b/gio/gioscheduler.c
@@ -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;
diff --git a/gio/gsettingsbackend.c b/gio/gsettingsbackend.c
index 8c1d267..9c96401 100644
--- a/gio/gsettingsbackend.c
+++ b/gio/gsettingsbackend.c
@@ -75,13 +75,11 @@ static gboolean g_settings_has_backend;
* g_settings_backend_create_tree() is a convenience function to create
* suitable trees.
*
- * <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
diff --git a/gio/gsimpleasyncresult.c b/gio/gsimpleasyncresult.c
index 017e240..f5e4b2a 100644
--- a/gio/gsimpleasyncresult.c
+++ b/gio/gsimpleasyncresult.c
@@ -34,12 +34,10 @@
* SECTION:gsimpleasyncresult
* @short_description: Simple asynchronous results implementation
* @include: gio/gio.h
- * @see_also: #GAsyncResult
+ * @see_also: #GAsyncResult, #GTask
*
- * <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.
*
diff --git a/gio/gthemedicon.c b/gio/gthemedicon.c
index 1b171c9..4990766 100644
--- a/gio/gthemedicon.c
+++ b/gio/gthemedicon.c
@@ -390,10 +390,8 @@ g_themed_icon_get_names (GThemedIcon *icon)
*
* Append a name to the list of icons from within @icon.
*
- * <note><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
*/
diff --git a/glib/docs.c b/glib/docs.c
index ac57f12..2b14de1 100644
--- a/glib/docs.c
+++ b/glib/docs.c
@@ -409,11 +409,9 @@
* for scanning and printing values of type #gint64 or #guint64.
* It is a string literal.
*
- * <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: */
diff --git a/glib/garray.c b/glib/garray.c
index 9640e1e..7c2ad13 100644
--- a/glib/garray.c
+++ b/glib/garray.c
@@ -46,7 +46,7 @@
* SECTION:arrays
* @title: Arrays
* @short_description: arrays of arbitrary elements which grow
- * automatically as elements are added
+ * automatically as elements are added
*
* Arrays are similar to standard C arrays, except that they grow
* automatically as elements are added.
@@ -84,7 +84,7 @@
* g_array_free (garray, TRUE);
* </programlisting>
* </example>
- **/
+ */
#define MIN_ARRAY_SIZE 16
@@ -93,12 +93,12 @@ typedef struct _GRealArray GRealArray;
/**
* GArray:
* @data: a pointer to the element data. The data may be moved as
- * elements are added to the #GArray.
+ * elements are added to the #GArray.
* @len: the number of elements in the #GArray not including the
- * possible terminating zero element.
+ * possible terminating zero element.
*
- * Contains the public fields of an <link linkend="glib-Arrays">Array</link>.
- **/
+ * Contains the public fields of a #GArray.
+ */
struct _GRealArray
{
guint8 *data;
@@ -113,9 +113,9 @@ struct _GRealArray
/**
* g_array_index:
- * @a: a #GArray.
- * @t: the type of the elements.
- * @i: the index of the element to return.
+ * @a: a #GArray
+ * @t: the type of the elements
+ * @i: the index of the element to return
*
* Returns the element of a #GArray at the given index. The return
* value is cast to the given type.
@@ -130,38 +130,38 @@ struct _GRealArray
* </programlisting>
* </example>
*
- * Returns: the element of the #GArray at the index given by @i.
- **/
+ * Returns: the element of the #GArray at the index given by @i
+ */
#define g_array_elt_len(array,i) ((array)->elt_size * (i))
#define g_array_elt_pos(array,i) ((array)->data + g_array_elt_len((array),(i)))
-#define g_array_elt_zero(array, pos, len) \
+#define g_array_elt_zero(array, pos, len) \
(memset (g_array_elt_pos ((array), pos), 0, g_array_elt_len ((array), len)))
-#define g_array_zero_terminate(array) G_STMT_START{ \
- if ((array)->zero_terminated) \
- g_array_elt_zero ((array), (array)->len, 1); \
+#define g_array_zero_terminate(array) G_STMT_START{ \
+ if ((array)->zero_terminated) \
+ g_array_elt_zero ((array), (array)->len, 1); \
}G_STMT_END
static guint g_nearest_pow (gint num) G_GNUC_CONST;
static void g_array_maybe_expand (GRealArray *array,
- gint len);
+ gint len);
/**
* g_array_new:
* @zero_terminated: %TRUE if the array should have an extra element at
- * the end which is set to 0.
+ * the end which is set to 0
* @clear_: %TRUE if #GArray elements should be automatically cleared
- * to 0 when they are allocated.
- * @element_size: the size of each element in bytes.
+ * to 0 when they are allocated
+ * @element_size: the size of each element in bytes
*
* Creates a new #GArray with a reference count of 1.
*
- * Returns: the new #GArray.
- **/
+ * Returns: the new #GArray
+ */
GArray*
g_array_new (gboolean zero_terminated,
- gboolean clear,
- guint elt_size)
+ gboolean clear,
+ guint elt_size)
{
g_return_val_if_fail (elt_size > 0, NULL);
@@ -171,23 +171,24 @@ g_array_new (gboolean zero_terminated,
/**
* g_array_sized_new:
* @zero_terminated: %TRUE if the array should have an extra element at
- * the end with all bits cleared.
+ * the end with all bits cleared
* @clear_: %TRUE if all bits in the array should be cleared to 0 on
- * allocation.
- * @element_size: size of each element in the array.
- * @reserved_size: number of elements preallocated.
+ * allocation
+ * @element_size: size of each element in the array
+ * @reserved_size: number of elements preallocated
*
* Creates a new #GArray with @reserved_size elements preallocated and
* a reference count of 1. This avoids frequent reallocation, if you
* are going to add many elements to the array. Note however that the
* size of the array is still 0.
*
- * Returns: the new #GArray.
- **/
-GArray* g_array_sized_new (gboolean zero_terminated,
- gboolean clear,
- guint elt_size,
- guint reserved_size)
+ * Returns: the new #GArray
+ */
+GArray*
+g_array_sized_new (gboolean zero_terminated,
+ gboolean clear,
+ guint elt_size,
+ guint reserved_size)
{
GRealArray *array;
@@ -243,15 +244,15 @@ g_array_set_clear_func (GArray *array,
/**
* g_array_ref:
- * @array: A #GArray.
+ * @array: A #GArray
*
- * Atomically increments the reference count of @array by one. This
- * function is MT-safe and may be called from any thread.
+ * Atomically increments the reference count of @array by one.
+ * This function is MT-safe and may be called from any thread.
*
- * Returns: The passed in #GArray.
+ * Returns: The passed in #GArray
*
* Since: 2.22
- **/
+ */
GArray *
g_array_ref (GArray *array)
{
@@ -273,7 +274,7 @@ static gchar *array_free (GRealArray *, ArrayFreeFlags);
/**
* g_array_unref:
- * @array: A #GArray.
+ * @array: A #GArray
*
* Atomically decrements the reference count of @array by one. If the
* reference count drops to 0, all memory allocated by the array is
@@ -281,7 +282,7 @@ static gchar *array_free (GRealArray *, ArrayFreeFlags);
* thread.
*
* Since: 2.22
- **/
+ */
void
g_array_unref (GArray *array)
{
@@ -294,14 +295,14 @@ g_array_unref (GArray *array)
/**
* g_array_get_element_size:
- * @array: A #GArray.
+ * @array: A #GArray
*
* Gets the size of the elements in @array.
*
- * Returns: Size of each element, in bytes.
+ * Returns: Size of each element, in bytes
*
* Since: 2.22
- **/
+ */
guint
g_array_get_element_size (GArray *array)
{
@@ -314,8 +315,8 @@ g_array_get_element_size (GArray *array)
/**
* g_array_free:
- * @array: a #GArray.
- * @free_segment: if %TRUE the actual element data is freed as well.
+ * @array: a #GArray
+ * @free_segment: if %TRUE the actual element data is freed as well
*
* Frees the memory allocated for the #GArray. If @free_segment is
* %TRUE it frees the memory block holding the elements as well and
@@ -325,15 +326,15 @@ g_array_get_element_size (GArray *array)
* is greater than one, the #GArray wrapper is preserved but the size
* of @array will be set to zero.
*
- * <note><para>If array elements contain dynamically-allocated memory,
- * they should be freed separately.</para></note>
+ * If array elements contain dynamically-allocated memory, they should
+ * be freed separately.
*
* Returns: the element data if @free_segment is %FALSE, otherwise
- * %NULL. The element data should be freed using g_free().
- **/
+ * %NULL. The element data should be freed using g_free().
+ */
gchar*
g_array_free (GArray *farray,
- gboolean free_segment)
+ gboolean free_segment)
{
GRealArray *array = (GRealArray*) farray;
ArrayFreeFlags flags;
@@ -387,32 +388,32 @@ array_free (GRealArray *array,
/**
* g_array_append_vals:
- * @array: a #GArray.
- * @data: a pointer to the elements to append to the end of the array.
- * @len: the number of elements to append.
+ * @array: a #GArray
+ * @data: a pointer to the elements to append to the end of the array
+ * @len: the number of elements to append
*
* Adds @len elements onto the end of the array.
*
- * Returns: the #GArray.
- **/
+ * Returns: the #GArray
+ */
/**
* g_array_append_val:
- * @a: a #GArray.
- * @v: the value to append to the #GArray.
+ * @a: a #GArray
+ * @v: the value to append to the #GArray
*
* Adds the value on to the end of the array. The array will grow in
* size automatically if necessary.
*
- * <note><para>g_array_append_val() is a macro which uses a reference
- * to the value parameter @v. This means that you cannot use it with
- * literal values such as "27". You must use variables.</para></note>
+ * g_array_append_val() is a macro which uses a reference to the value
+ * parameter @v. This means that you cannot use it with literal values
+ * such as "27". You must use variables.
*
- * Returns: the #GArray.
- **/
+ * Returns: the #GArray
+ */
GArray*
g_array_append_vals (GArray *farray,
- gconstpointer data,
- guint len)
+ gconstpointer data,
+ guint len)
{
GRealArray *array = (GRealArray*) farray;
@@ -421,7 +422,7 @@ g_array_append_vals (GArray *farray,
g_array_maybe_expand (array, len);
memcpy (g_array_elt_pos (array, array->len), data,
- g_array_elt_len (array, len));
+ g_array_elt_len (array, len));
array->len += len;
@@ -432,10 +433,9 @@ g_array_append_vals (GArray *farray,
/**
* g_array_prepend_vals:
- * @array: a #GArray.
- * @data: a pointer to the elements to prepend to the start of the
- * array.
- * @len: the number of elements to prepend.
+ * @array: a #GArray
+ * @data: a pointer to the elements to prepend to the start of the array
+ * @len: the number of elements to prepend
*
* Adds @len elements onto the start of the array.
*
@@ -443,12 +443,12 @@ g_array_append_vals (GArray *farray,
* existing elements in the array have to be moved to make space for
* the new elements.
*
- * Returns: the #GArray.
- **/
+ * Returns: the #GArray
+ */
/**
* g_array_prepend_val:
- * @a: a #GArray.
- * @v: the value to prepend to the #GArray.
+ * @a: a #GArray
+ * @v: the value to prepend to the #GArray
*
* Adds the value on to the start of the array. The array will grow in
* size automatically if necessary.
@@ -457,16 +457,16 @@ g_array_append_vals (GArray *farray,
* existing elements in the array have to be moved to make space for
* the new element.
*
- * <note><para>g_array_prepend_val() is a macro which uses a reference
- * to the value parameter @v. This means that you cannot use it with
- * literal values such as "27". You must use variables.</para></note>
+ * g_array_prepend_val() is a macro which uses a reference to the value
+ * parameter @v. This means that you cannot use it with literal values
+ * such as "27". You must use variables.
*
- * Returns: the #GArray.
- **/
+ * Returns: the #GArray
+ */
GArray*
g_array_prepend_vals (GArray *farray,
- gconstpointer data,
- guint len)
+ gconstpointer data,
+ guint len)
{
GRealArray *array = (GRealArray*) farray;
@@ -488,34 +488,34 @@ g_array_prepend_vals (GArray *farray,
/**
* g_array_insert_vals:
- * @array: a #GArray.
- * @index_: the index to place the elements at.
- * @data: a pointer to the elements to insert.
- * @len: the number of elements to insert.
+ * @array: a #GArray
+ * @index_: the index to place the elements at
+ * @data: a pointer to the elements to insert
+ * @len: the number of elements to insert
*
* Inserts @len elements into a #GArray at the given index.
*
- * Returns: the #GArray.
- **/
+ * Returns: the #GArray
+ */
/**
* g_array_insert_val:
- * @a: a #GArray.
- * @i: the index to place the element at.
- * @v: the value to insert into the array.
+ * @a: a #GArray
+ * @i: the index to place the element at
+ * @v: the value to insert into the array
*
* Inserts an element into an array at the given index.
*
- * <note><para>g_array_insert_val() is a macro which uses a reference
- * to the value parameter @v. This means that you cannot use it with
- * literal values such as "27". You must use variables.</para></note>
+ * g_array_insert_val() is a macro which uses a reference to the value
+ * parameter @v. This means that you cannot use it with literal values
+ * such as "27". You must use variables.
*
- * Returns: the #GArray.
- **/
+ * Returns: the #GArray
+ */
GArray*
g_array_insert_vals (GArray *farray,
- guint index_,
- gconstpointer data,
- guint len)
+ guint index_,
+ gconstpointer data,
+ guint len)
{
GRealArray *array = (GRealArray*) farray;
@@ -538,17 +538,17 @@ g_array_insert_vals (GArray *farray,
/**
* g_array_set_size:
- * @array: a #GArray.
- * @length: the new size of the #GArray.
+ * @array: a #GArray
+ * @length: the new size of the #GArray
*
* Sets the size of the array, expanding it if necessary. If the array
* was created with @clear_ set to %TRUE, the new elements are set to 0.
*
- * Returns: the #GArray.
- **/
+ * Returns: the #GArray
+ */
GArray*
g_array_set_size (GArray *farray,
- guint length)
+ guint length)
{
GRealArray *array = (GRealArray*) farray;
@@ -559,7 +559,7 @@ g_array_set_size (GArray *farray,
g_array_maybe_expand (array, length - array->len);
if (array->clear)
- g_array_elt_zero (array, array->len, length - array->len);
+ g_array_elt_zero (array, array->len, length - array->len);
}
else if (length < array->len)
g_array_remove_range (farray, length, array->len - length);
@@ -573,17 +573,17 @@ g_array_set_size (GArray *farray,
/**
* g_array_remove_index:
- * @array: a #GArray.
- * @index_: the index of the element to remove.
+ * @array: a #GArray
+ * @index_: the index of the element to remove
*
* Removes the element at the given index from a #GArray. The following
* elements are moved down one place.
*
- * Returns: the #GArray.
- **/
+ * Returns: the #GArray
+ */
GArray*
g_array_remove_index (GArray *farray,
- guint index_)
+ guint index_)
{
GRealArray* array = (GRealArray*) farray;
@@ -611,19 +611,19 @@ g_array_remove_index (GArray *farray,
/**
* g_array_remove_index_fast:
- * @array: a @GArray.
- * @index_: the index of the element to remove.
+ * @array: a @GArray
+ * @index_: the index of the element to remove
*
* Removes the element at the given index from a #GArray. The last
* element in the array is used to fill in the space, so this function
* does not preserve the order of the #GArray. But it is faster than
* g_array_remove_index().
*
- * Returns: the #GArray.
- **/
+ * Returns: the #GArray
+ */
GArray*
g_array_remove_index_fast (GArray *farray,
- guint index_)
+ guint index_)
{
GRealArray* array = (GRealArray*) farray;
@@ -651,17 +651,17 @@ g_array_remove_index_fast (GArray *farray,
/**
* g_array_remove_range:
- * @array: a @GArray.
- * @index_: the index of the first element to remove.
- * @length: the number of elements to remove.
+ * @array: a @GArray
+ * @index_: the index of the first element to remove
+ * @length: the number of elements to remove
*
* Removes the given number of elements starting at the given index
* from a #GArray. The following elements are moved to close the gap.
*
- * Returns: the #GArray.
+ * Returns: the #GArray
*
* Since: 2.4
- **/
+ */
GArray*
g_array_remove_range (GArray *farray,
guint index_,
@@ -697,8 +697,8 @@ g_array_remove_range (GArray *farray,
/**
* g_array_sort:
- * @array: a #GArray.
- * @compare_func: comparison function.
+ * @array: a #GArray
+ * @compare_func: comparison function
*
* Sorts a #GArray using @compare_func which should be a qsort()-style
* comparison function (returns less than zero for first arg is less
@@ -706,10 +706,10 @@ g_array_remove_range (GArray *farray,
* greater than second arg).
*
* This is guaranteed to be a stable sort since version 2.32.
- **/
+ */
void
g_array_sort (GArray *farray,
- GCompareFunc compare_func)
+ GCompareFunc compare_func)
{
GRealArray *array = (GRealArray*) farray;
@@ -717,17 +717,17 @@ g_array_sort (GArray *farray,
/* Don't use qsort as we want a guaranteed stable sort */
g_qsort_with_data (array->data,
- array->len,
- array->elt_size,
- (GCompareDataFunc)compare_func,
- NULL);
+ array->len,
+ array->elt_size,
+ (GCompareDataFunc)compare_func,
+ NULL);
}
/**
* g_array_sort_with_data:
- * @array: a #GArray.
- * @compare_func: comparison function.
- * @user_data: data to pass to @compare_func.
+ * @array: a #GArray
+ * @compare_func: comparison function
+ * @user_data: data to pass to @compare_func
*
* Like g_array_sort(), but the comparison function receives an extra
* user data argument.
@@ -737,21 +737,21 @@ g_array_sort (GArray *farray,
* There used to be a comment here about making the sort stable by
* using the addresses of the elements in the comparison function.
* This did not actually work, so any such code should be removed.
- **/
+ */
void
g_array_sort_with_data (GArray *farray,
- GCompareDataFunc compare_func,
- gpointer user_data)
+ GCompareDataFunc compare_func,
+ gpointer user_data)
{
GRealArray *array = (GRealArray*) farray;
g_return_if_fail (array != NULL);
g_qsort_with_data (array->data,
- array->len,
- array->elt_size,
- compare_func,
- user_data);
+ array->len,
+ array->elt_size,
+ compare_func,
+ user_data);
}
/* Returns the smallest power of 2 greater than n, or n if
@@ -770,10 +770,10 @@ g_nearest_pow (gint num)
static void
g_array_maybe_expand (GRealArray *array,
- gint len)
+ gint len)
{
guint want_alloc = g_array_elt_len (array, array->len + len +
- array->zero_terminated);
+ array->zero_terminated);
if (want_alloc > array->alloc)
{
@@ -793,16 +793,16 @@ g_array_maybe_expand (GRealArray *array,
* SECTION:arrays_pointer
* @title: Pointer Arrays
* @short_description: arrays of pointers to any type of data, which
- * grow automatically as new elements are added
+ * grow automatically as new elements are added
*
* Pointer Arrays are similar to Arrays but are used only for storing
* pointers.
*
- * <note><para>If you remove elements from the array, elements at the
- * end of the array are moved into the space previously occupied by the
- * removed element. This means that you should not rely on the index of
- * particular elements remaining the same. You should also be careful
- * when deleting elements while iterating over the array.</para></note>
+ * If you remove elements from the array, elements at the end of the
+ * array are moved into the space previously occupied by the removed
+ * element. This means that you should not rely on the index of particular
+ * elements remaining the same. You should also be careful when deleting
+ * elements while iterating over the array.
*
* To create a pointer array, use g_ptr_array_new().
*
@@ -842,11 +842,11 @@ typedef struct _GRealPtrArray GRealPtrArray;
/**
* GPtrArray:
* @pdata: points to the array of pointers, which may be moved when the
- * array grows.
- * @len: number of pointers in the array.
+ * array grows
+ * @len: number of pointers in the array
*
* Contains the public fields of a pointer array.
- **/
+ */
struct _GRealPtrArray
{
gpointer *pdata;
@@ -858,28 +858,27 @@ struct _GRealPtrArray
/**
* g_ptr_array_index:
- * @array: a #GPtrArray.
- * @index_: the index of the pointer to return.
+ * @array: a #GPtrArray
+ * @index_: the index of the pointer to return
*
* Returns the pointer at the given index of the pointer array.
*
- * <note><para>
- * This does not perform bounds checking on the given @index_, so you are
- * responsible for checking it against the array length.</para></note>
+ * This does not perform bounds checking on the given @index_,
+ * so you are responsible for checking it against the array length.
*
- * Returns: the pointer at the given index.
- **/
+ * Returns: the pointer at the given index
+ */
static void g_ptr_array_maybe_expand (GRealPtrArray *array,
- gint len);
+ gint len);
/**
* g_ptr_array_new:
*
* Creates a new #GPtrArray with a reference count of 1.
*
- * Returns: the new #GPtrArray.
- **/
+ * Returns: the new #GPtrArray
+ */
GPtrArray*
g_ptr_array_new (void)
{
@@ -888,15 +887,15 @@ g_ptr_array_new (void)
/**
* g_ptr_array_sized_new:
- * @reserved_size: number of pointers preallocated.
+ * @reserved_size: number of pointers preallocated
*
* Creates a new #GPtrArray with @reserved_size pointers preallocated
* and a reference count of 1. This avoids frequent reallocation, if
* you are going to add many pointers to the array. Note however that
* the size of the array is still 0.
*
- * Returns: the new #GPtrArray.
- **/
+ * Returns: the new #GPtrArray
+ */
GPtrArray*
g_ptr_array_sized_new (guint reserved_size)
{
@@ -916,17 +915,18 @@ g_ptr_array_sized_new (guint reserved_size)
/**
* g_ptr_array_new_with_free_func:
- * @element_free_func: (allow-none): A function to free elements with destroy @array or %NULL.
+ * @element_free_func: (allow-none): A function to free elements with
+ * destroy @array or %NULL
*
- * Creates a new #GPtrArray with a reference count of 1 and use @element_free_func
- * for freeing each element when the array is destroyed either via
- * g_ptr_array_unref(), when g_ptr_array_free() is called with @free_segment
- * set to %TRUE or when removing elements.
+ * Creates a new #GPtrArray with a reference count of 1 and use
+ * @element_free_func for freeing each element when the array is destroyed
+ * either via g_ptr_array_unref(), when g_ptr_array_free() is called with
+ * @free_segment set to %TRUE or when removing elements.
*
- * Returns: A new #GPtrArray.
+ * Returns: A new #GPtrArray
*
* Since: 2.22
- **/
+ */
GPtrArray *
g_ptr_array_new_with_free_func (GDestroyNotify element_free_func)
{
@@ -939,21 +939,22 @@ g_ptr_array_new_with_free_func (GDestroyNotify element_free_func)
/**
* g_ptr_array_new_full:
- * @reserved_size: number of pointers preallocated.
- * @element_free_func: (allow-none): A function to free elements with destroy @array or %NULL.
+ * @reserved_size: number of pointers preallocated
+ * @element_free_func: (allow-none): A function to free elements with
+ * destroy @array or %NULL
*
* Creates a new #GPtrArray with @reserved_size pointers preallocated
* and a reference count of 1. This avoids frequent reallocation, if
* you are going to add many pointers to the array. Note however that
* the size of the array is still 0. It also set @element_free_func
* for freeing each element when the array is destroyed either via
- * g_ptr_array_unref(), when g_ptr_array_free() is called with @free_segment
- * set to %TRUE or when removing elements.
+ * g_ptr_array_unref(), when g_ptr_array_free() is called with
+ * @free_segment set to %TRUE or when removing elements.
*
- * Returns: A new #GPtrArray.
+ * Returns: A new #GPtrArray
*
* Since: 2.30
- **/
+ */
GPtrArray *
g_ptr_array_new_full (guint reserved_size,
GDestroyNotify element_free_func)
@@ -967,15 +968,16 @@ g_ptr_array_new_full (guint reserved_size,
/**
* g_ptr_array_set_free_func:
- * @array: A #GPtrArray.
- * @element_free_func: (allow-none): A function to free elements with destroy @array or %NULL.
+ * @array: A #GPtrArray
+ * @element_free_func: (allow-none): A function to free elements with
+ * destroy @array or %NULL
*
* Sets a function for freeing each element when @array is destroyed
* either via g_ptr_array_unref(), when g_ptr_array_free() is called
* with @free_segment set to %TRUE or when removing elements.
*
* Since: 2.22
- **/
+ */
void
g_ptr_array_set_free_func (GPtrArray *array,
GDestroyNotify element_free_func)
@@ -1014,7 +1016,7 @@ static gpointer *ptr_array_free (GPtrArray *, ArrayFreeFlags);
/**
* g_ptr_array_unref:
- * @array: A #GPtrArray.
+ * @array: A #GPtrArray
*
* Atomically decrements the reference count of @array by one. If the
* reference count drops to 0, the effect is the same as calling
@@ -1022,7 +1024,7 @@ static gpointer *ptr_array_free (GPtrArray *, ArrayFreeFlags);
* is MT-safe and may be called from any thread.
*
* Since: 2.22
- **/
+ */
void
g_ptr_array_unref (GPtrArray *array)
{
@@ -1035,8 +1037,8 @@ g_ptr_array_unref (GPtrArray *array)
/**
* g_ptr_array_free:
- * @array: a #GPtrArray.
- * @free_seg: if %TRUE the actual pointer array is freed as well.
+ * @array: a #GPtrArray
+ * @free_seg: if %TRUE the actual pointer array is freed as well
*
* Frees the memory allocated for the #GPtrArray. If @free_seg is %TRUE
* it frees the memory block holding the elements as well. Pass %FALSE
@@ -1045,16 +1047,16 @@ g_ptr_array_unref (GPtrArray *array)
* is greater than one, the #GPtrArray wrapper is preserved but the
* size of @array will be set to zero.
*
- * <note><para>If array contents point to dynamically-allocated
- * memory, they should be freed separately if @free_seg is %TRUE and no
- * #GDestroyNotify function has been set for @array.</para></note>
+ * If array contents point to dynamically-allocated memory, they should
+ * be freed separately if @free_seg is %TRUE and no #GDestroyNotify
+ * function has been set for @array.
*
* Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL.
- * The pointer array should be freed using g_free().
- **/
+ * The pointer array should be freed using g_free().
+ */
gpointer*
g_ptr_array_free (GPtrArray *farray,
- gboolean free_segment)
+ gboolean free_segment)
{
GRealPtrArray *array = (GRealPtrArray*) farray;
ArrayFreeFlags flags;
@@ -1063,7 +1065,9 @@ g_ptr_array_free (GPtrArray *farray,
flags = (free_segment ? FREE_SEGMENT : 0);
- /* if others are holding a reference, preserve the wrapper but do free/return the data */
+ /* if others are holding a reference, preserve the wrapper but
+ * do free/return the data
+ */
if (!g_atomic_int_dec_and_test (&array->ref_count))
flags |= PRESERVE_WRAPPER;
@@ -1103,7 +1107,7 @@ ptr_array_free (GPtrArray *farray,
static void
g_ptr_array_maybe_expand (GRealPtrArray *array,
- gint len)
+ gint len)
{
if ((array->len + len) > array->alloc)
{
@@ -1119,17 +1123,17 @@ g_ptr_array_maybe_expand (GRealPtrArray *array,
/**
* g_ptr_array_set_size:
- * @array: a #GPtrArray.
- * @length: the new length of the pointer array.
+ * @array: a #GPtrArray
+ * @length: the new length of the pointer array
*
* Sets the size of the array. When making the array larger,
* newly-added elements will be set to %NULL. When making it smaller,
* if @array has a non-%NULL #GDestroyNotify function then it will be
* called for the removed elements.
- **/
+ */
void
g_ptr_array_set_size (GPtrArray *farray,
- gint length)
+ gint length)
{
GRealPtrArray* array = (GRealPtrArray*) farray;
@@ -1146,7 +1150,7 @@ g_ptr_array_set_size (GPtrArray *farray,
* bitwise zero. It of course is silly not to use memset (..,0,..).
*/
for (i = array->len; i < length; i++)
- array->pdata[i] = NULL;
+ array->pdata[i] = NULL;
}
else if (length < array->len)
g_ptr_array_remove_range (farray, length, array->len - length);
@@ -1156,19 +1160,19 @@ g_ptr_array_set_size (GPtrArray *farray,
/**
* g_ptr_array_remove_index:
- * @array: a #GPtrArray.
- * @index_: the index of the pointer to remove.
+ * @array: a #GPtrArray
+ * @index_: the index of the pointer to remove
*
- * Removes the pointer at the given index from the pointer array. The
- * following elements are moved down one place. If @array has a
- * non-%NULL #GDestroyNotify function it is called for the removed
+ * Removes the pointer at the given index from the pointer array.
+ * The following elements are moved down one place. If @array has
+ * a non-%NULL #GDestroyNotify function it is called for the removed
* element.
*
- * Returns: the pointer which was removed.
- **/
+ * Returns: the pointer which was removed
+ */
gpointer
g_ptr_array_remove_index (GPtrArray *farray,
- guint index_)
+ guint index_)
{
GRealPtrArray* array = (GRealPtrArray*) farray;
gpointer result;
@@ -1196,20 +1200,20 @@ g_ptr_array_remove_index (GPtrArray *farray,
/**
* g_ptr_array_remove_index_fast:
- * @array: a #GPtrArray.
- * @index_: the index of the pointer to remove.
+ * @array: a #GPtrArray
+ * @index_: the index of the pointer to remove
*
- * Removes the pointer at the given index from the pointer array. The
- * last element in the array is used to fill in the space, so this
- * function does not preserve the order of the array. But it is faster
- * than g_ptr_array_remove_index(). If @array has a non-%NULL
+ * Removes the pointer at the given index from the pointer array.
+ * The last element in the array is used to fill in the space, so
+ * this function does not preserve the order of the array. But it
+ * is faster than g_ptr_array_remove_index(). If @array has a non-%NULL
* #GDestroyNotify function it is called for the removed element.
*
- * Returns: the pointer which was removed.
- **/
+ * Returns: the pointer which was removed
+ */
gpointer
g_ptr_array_remove_index_fast (GPtrArray *farray,
- guint index_)
+ guint index_)
{
GRealPtrArray* array = (GRealPtrArray*) farray;
gpointer result;
@@ -1248,7 +1252,7 @@ g_ptr_array_remove_index_fast (GPtrArray *farray,
* Returns: the @array
*
* Since: 2.4
- **/
+ */
GPtrArray *
g_ptr_array_remove_range (GPtrArray *farray,
guint index_,
@@ -1287,8 +1291,8 @@ g_ptr_array_remove_range (GPtrArray *farray,
/**
* g_ptr_array_remove:
- * @array: a #GPtrArray.
- * @data: the pointer to remove.
+ * @array: a #GPtrArray
+ * @data: the pointer to remove
*
* Removes the first occurrence of the given pointer from the pointer
* array. The following elements are moved down one place. If @array
@@ -1298,12 +1302,12 @@ g_ptr_array_remove_range (GPtrArray *farray,
* It returns %TRUE if the pointer was removed, or %FALSE if the
* pointer was not found.
*
- * Returns: %TRUE if the pointer is removed. %FALSE if the pointer is
- * not found in the array.
- **/
+ * Returns: %TRUE if the pointer is removed, %FALSE if the pointer
+ * is not found in the array
+ */
gboolean
g_ptr_array_remove (GPtrArray *farray,
- gpointer data)
+ gpointer data)
{
GRealPtrArray* array = (GRealPtrArray*) farray;
guint i;
@@ -1313,10 +1317,10 @@ g_ptr_array_remove (GPtrArray *farray,
for (i = 0; i < array->len; i += 1)
{
if (array->pdata[i] == data)
- {
- g_ptr_array_remove_index (farray, i);
- return TRUE;
- }
+ {
+ g_ptr_array_remove_index (farray, i);
+ return TRUE;
+ }
}
return FALSE;
@@ -1324,23 +1328,23 @@ g_ptr_array_remove (GPtrArray *farray,
/**
* g_ptr_array_remove_fast:
- * @array: a #GPtrArray.
- * @data: the pointer to remove.
+ * @array: a #GPtrArray
+ * @data: the pointer to remove
*
* Removes the first occurrence of the given pointer from the pointer
* array. The last element in the array is used to fill in the space,
- * so this function does not preserve the order of the array. But it is
- * faster than g_ptr_array_remove(). If @array has a non-%NULL
+ * so this function does not preserve the order of the array. But it
+ * is faster than g_ptr_array_remove(). If @array has a non-%NULL
* #GDestroyNotify function it is called for the removed element.
*
* It returns %TRUE if the pointer was removed, or %FALSE if the
* pointer was not found.
*
- * Returns: %TRUE if the pointer was found in the array.
- **/
+ * Returns: %TRUE if the pointer was found in the array
+ */
gboolean
g_ptr_array_remove_fast (GPtrArray *farray,
- gpointer data)
+ gpointer data)
{
GRealPtrArray* array = (GRealPtrArray*) farray;
guint i;
@@ -1350,10 +1354,10 @@ g_ptr_array_remove_fast (GPtrArray *farray,
for (i = 0; i < array->len; i += 1)
{
if (array->pdata[i] == data)
- {
- g_ptr_array_remove_index_fast (farray, i);
- return TRUE;
- }
+ {
+ g_ptr_array_remove_index_fast (farray, i);
+ return TRUE;
+ }
}
return FALSE;
@@ -1361,15 +1365,15 @@ g_ptr_array_remove_fast (GPtrArray *farray,
/**
* g_ptr_array_add:
- * @array: a #GPtrArray.
- * @data: the pointer to add.
+ * @array: a #GPtrArray
+ * @data: the pointer to add
*
* Adds a pointer to the end of the pointer array. The array will grow
* in size automatically if necessary.
- **/
+ */
void
g_ptr_array_add (GPtrArray *farray,
- gpointer data)
+ gpointer data)
{
GRealPtrArray* array = (GRealPtrArray*) farray;
@@ -1382,15 +1386,15 @@ g_ptr_array_add (GPtrArray *farray,
/**
* g_ptr_array_insert:
- * @array: a #GPtrArray.
- * @index_: the index to place the new element at, or -1 to append.
+ * @array: a #GPtrArray
+ * @index_: the index to place the new element at, or -1 to append
* @data: the pointer to add.
*
* Inserts an element into the pointer array at the given index. The
* array will grow in size automatically if necessary.
*
* Since: 2.40
- **/
+ */
void
g_ptr_array_insert (GPtrArray *farray,
gint index_,
@@ -1418,61 +1422,61 @@ g_ptr_array_insert (GPtrArray *farray,
/**
* g_ptr_array_sort:
- * @array: a #GPtrArray.
- * @compare_func: comparison function.
+ * @array: a #GPtrArray
+ * @compare_func: comparison function
*
* Sorts the array, using @compare_func which should be a qsort()-style
* comparison function (returns less than zero for first arg is less
* than second arg, zero for equal, greater than zero if irst arg is
* greater than second arg).
*
- * <note><para>The comparison function for g_ptr_array_sort() doesn't
+ * Note that the comparison function for g_ptr_array_sort() doesn't
* take the pointers from the array as arguments, it takes pointers to
- * the pointers in the array.</para></note>
+ * the pointers in the array.
*
* This is guaranteed to be a stable sort since version 2.32.
- **/
+ */
void
g_ptr_array_sort (GPtrArray *array,
- GCompareFunc compare_func)
+ GCompareFunc compare_func)
{
g_return_if_fail (array != NULL);
/* Don't use qsort as we want a guaranteed stable sort */
g_qsort_with_data (array->pdata,
- array->len,
- sizeof (gpointer),
- (GCompareDataFunc)compare_func,
- NULL);
+ array->len,
+ sizeof (gpointer),
+ (GCompareDataFunc)compare_func,
+ NULL);
}
/**
* g_ptr_array_sort_with_data:
- * @array: a #GPtrArray.
- * @compare_func: comparison function.
- * @user_data: data to pass to @compare_func.
+ * @array: a #GPtrArray
+ * @compare_func: comparison function
+ * @user_data: data to pass to @compare_func
*
* Like g_ptr_array_sort(), but the comparison function has an extra
* user data argument.
*
- * <note><para>The comparison function for g_ptr_array_sort_with_data()
+ * Note that the comparison function for g_ptr_array_sort_with_data()
* doesn't take the pointers from the array as arguments, it takes
- * pointers to the pointers in the array.</para></note>
+ * pointers to the pointers in the array.
*
* This is guaranteed to be a stable sort since version 2.32.
- **/
+ */
void
g_ptr_array_sort_with_data (GPtrArray *array,
- GCompareDataFunc compare_func,
- gpointer user_data)
+ GCompareDataFunc compare_func,
+ gpointer user_data)
{
g_return_if_fail (array != NULL);
g_qsort_with_data (array->pdata,
- array->len,
- sizeof (gpointer),
- compare_func,
- user_data);
+ array->len,
+ sizeof (gpointer),
+ compare_func,
+ user_data);
}
/**
@@ -1484,7 +1488,7 @@ g_ptr_array_sort_with_data (GPtrArray *array,
* Calls a function for each element of a #GPtrArray.
*
* Since: 2.4
- **/
+ */
void
g_ptr_array_foreach (GPtrArray *array,
GFunc func,
@@ -1537,13 +1541,13 @@ g_ptr_array_foreach (GPtrArray *array,
*
* See #GBytes if you are interested in an immutable object representing a
* sequence of bytes.
- **/
+ */
/**
* GByteArray:
* @data: a pointer to the element data. The data may be moved as
- * elements are added to the #GByteArray.
- * @len: the number of elements in the #GByteArray.
+ * elements are added to the #GByteArray
+ * @len: the number of elements in the #GByteArray
*
* The #GByteArray-struct allows access to the public fields of
* a #GByteArray.
@@ -1554,9 +1558,10 @@ g_ptr_array_foreach (GPtrArray *array,
*
* Creates a new #GByteArray with a reference count of 1.
*
- * Returns: (transfer full): the new #GByteArray.
- **/
-GByteArray* g_byte_array_new (void)
+ * Returns: (transfer full): the new #GByteArray
+ */
+GByteArray*
+g_byte_array_new (void)
{
return (GByteArray*) g_array_sized_new (FALSE, FALSE, 1, 0);
}
@@ -1593,24 +1598,25 @@ g_byte_array_new_take (guint8 *data,
/**
* g_byte_array_sized_new:
- * @reserved_size: number of bytes preallocated.
+ * @reserved_size: number of bytes preallocated
*
* Creates a new #GByteArray with @reserved_size bytes preallocated.
* This avoids frequent reallocation, if you are going to add many
* bytes to the array. Note however that the size of the array is still
* 0.
*
- * Returns: the new #GByteArray.
- **/
-GByteArray* g_byte_array_sized_new (guint reserved_size)
+ * Returns: the new #GByteArray
+ */
+GByteArray*
+g_byte_array_sized_new (guint reserved_size)
{
return (GByteArray*) g_array_sized_new (FALSE, FALSE, 1, reserved_size);
}
/**
* g_byte_array_free:
- * @array: a #GByteArray.
- * @free_segment: if %TRUE the actual byte data is freed as well.
+ * @array: a #GByteArray
+ * @free_segment: if %TRUE the actual byte data is freed as well
*
* Frees the memory allocated by the #GByteArray. If @free_segment is
* %TRUE it frees the actual byte data. If the reference count of
@@ -1619,9 +1625,10 @@ GByteArray* g_byte_array_sized_new (guint reserved_size)
*
* Returns: the element data if @free_segment is %FALSE, otherwise
* %NULL. The element data should be freed using g_free().
- **/
-guint8* g_byte_array_free (GByteArray *array,
- gboolean free_segment)
+ */
+guint8*
+g_byte_array_free (GByteArray *array,
+ gboolean free_segment)
{
return (guint8*) g_array_free ((GArray*) array, free_segment);
}
@@ -1641,8 +1648,8 @@ guint8* g_byte_array_free (GByteArray *array,
*
* Since: 2.32
*
- * Returns: (transfer full): a new immutable #GBytes representing same byte
- * data that was in the array
+ * Returns: (transfer full): a new immutable #GBytes representing same
+ * byte data that was in the array
*/
GBytes *
g_byte_array_free_to_bytes (GByteArray *array)
@@ -1657,15 +1664,15 @@ g_byte_array_free_to_bytes (GByteArray *array)
/**
* g_byte_array_ref:
- * @array: A #GByteArray.
+ * @array: A #GByteArray
*
* Atomically increments the reference count of @array by one. This
* function is MT-safe and may be called from any thread.
*
- * Returns: The passed in #GByteArray.
+ * Returns: The passed in #GByteArray
*
* Since: 2.22
- **/
+ */
GByteArray *
g_byte_array_ref (GByteArray *array)
{
@@ -1674,7 +1681,7 @@ g_byte_array_ref (GByteArray *array)
/**
* g_byte_array_unref:
- * @array: A #GByteArray.
+ * @array: A #GByteArray
*
* Atomically decrements the reference count of @array by one. If the
* reference count drops to 0, all memory allocated by the array is
@@ -1682,7 +1689,7 @@ g_byte_array_ref (GByteArray *array)
* thread.
*
* Since: 2.22
- **/
+ */
void
g_byte_array_unref (GByteArray *array)
{
@@ -1691,18 +1698,19 @@ g_byte_array_unref (GByteArray *array)
/**
* g_byte_array_append:
- * @array: a #GByteArray.
- * @data: the byte data to be added.
- * @len: the number of bytes to add.
+ * @array: a #GByteArray
+ * @data: the byte data to be added
+ * @len: the number of bytes to add
*
* Adds the given bytes to the end of the #GByteArray. The array will
* grow in size automatically if necessary.
*
- * Returns: the #GByteArray.
- **/
-GByteArray* g_byte_array_append (GByteArray *array,
- const guint8 *data,
- guint len)
+ * Returns: the #GByteArray
+ */
+GByteArray*
+g_byte_array_append (GByteArray *array,
+ const guint8 *data,
+ guint len)
{
g_array_append_vals ((GArray*) array, (guint8*)data, len);
@@ -1711,18 +1719,19 @@ GByteArray* g_byte_array_append (GByteArray *array,
/**
* g_byte_array_prepend:
- * @array: a #GByteArray.
- * @data: the byte data to be added.
- * @len: the number of bytes to add.
+ * @array: a #GByteArray
+ * @data: the byte data to be added
+ * @len: the number of bytes to add
*
* Adds the given data to the start of the #GByteArray. The array will
* grow in size automatically if necessary.
*
- * Returns: the #GByteArray.
- **/
-GByteArray* g_byte_array_prepend (GByteArray *array,
- const guint8 *data,
- guint len)
+ * Returns: the #GByteArray
+ */
+GByteArray*
+g_byte_array_prepend (GByteArray *array,
+ const guint8 *data,
+ guint len)
{
g_array_prepend_vals ((GArray*) array, (guint8*)data, len);
@@ -1731,15 +1740,16 @@ GByteArray* g_byte_array_prepend (GByteArray *array,
/**
* g_byte_array_set_size:
- * @array: a #GByteArray.
- * @length: the new size of the #GByteArray.
+ * @array: a #GByteArray
+ * @length: the new size of the #GByteArray
*
* Sets the size of the #GByteArray, expanding it if necessary.
*
- * Returns: the #GByteArray.
- **/
-GByteArray* g_byte_array_set_size (GByteArray *array,
- guint length)
+ * Returns: the #GByteArray
+ */
+GByteArray*
+g_byte_array_set_size (GByteArray *array,
+ guint length)
{
g_array_set_size ((GArray*) array, length);
@@ -1748,16 +1758,17 @@ GByteArray* g_byte_array_set_size (GByteArray *array,
/**
* g_byte_array_remove_index:
- * @array: a #GByteArray.
- * @index_: the index of the byte to remove.
+ * @array: a #GByteArray
+ * @index_: the index of the byte to remove
*
* Removes the byte at the given index from a #GByteArray. The
* following bytes are moved down one place.
*
- * Returns: the #GByteArray.
+ * Returns: the #GByteArray
**/
-GByteArray* g_byte_array_remove_index (GByteArray *array,
- guint index_)
+GByteArray*
+g_byte_array_remove_index (GByteArray *array,
+ guint index_)
{
g_array_remove_index ((GArray*) array, index_);
@@ -1766,18 +1777,19 @@ GByteArray* g_byte_array_remove_index (GByteArray *array,
/**
* g_byte_array_remove_index_fast:
- * @array: a #GByteArray.
- * @index_: the index of the byte to remove.
+ * @array: a #GByteArray
+ * @index_: the index of the byte to remove
*
* Removes the byte at the given index from a #GByteArray. The last
* element in the array is used to fill in the space, so this function
* does not preserve the order of the #GByteArray. But it is faster
* than g_byte_array_remove_index().
*
- * Returns: the #GByteArray.
- **/
-GByteArray* g_byte_array_remove_index_fast (GByteArray *array,
- guint index_)
+ * Returns: the #GByteArray
+ */
+GByteArray*
+g_byte_array_remove_index_fast (GByteArray *array,
+ guint index_)
{
g_array_remove_index_fast ((GArray*) array, index_);
@@ -1786,17 +1798,17 @@ GByteArray* g_byte_array_remove_index_fast (GByteArray *array,
/**
* g_byte_array_remove_range:
- * @array: a @GByteArray.
- * @index_: the index of the first byte to remove.
- * @length: the number of bytes to remove.
+ * @array: a @GByteArray
+ * @index_: the index of the first byte to remove
+ * @length: the number of bytes to remove
*
* Removes the given number of bytes starting at the given index from a
* #GByteArray. The following elements are moved to close the gap.
*
- * Returns: the #GByteArray.
+ * Returns: the #GByteArray
*
* Since: 2.4
- **/
+ */
GByteArray*
g_byte_array_remove_range (GByteArray *array,
guint index_,
@@ -1811,8 +1823,8 @@ g_byte_array_remove_range (GByteArray *array,
/**
* g_byte_array_sort:
- * @array: a #GByteArray.
- * @compare_func: comparison function.
+ * @array: a #GByteArray
+ * @compare_func: comparison function
*
* Sorts a byte array, using @compare_func which should be a
* qsort()-style comparison function (returns less than zero for first
@@ -1824,27 +1836,27 @@ g_byte_array_remove_range (GByteArray *array,
* you want a stable sort) you can write a comparison function that,
* if two elements would otherwise compare equal, compares them by
* their addresses.
- **/
+ */
void
g_byte_array_sort (GByteArray *array,
- GCompareFunc compare_func)
+ GCompareFunc compare_func)
{
g_array_sort ((GArray *) array, compare_func);
}
/**
* g_byte_array_sort_with_data:
- * @array: a #GByteArray.
- * @compare_func: comparison function.
- * @user_data: data to pass to @compare_func.
+ * @array: a #GByteArray
+ * @compare_func: comparison function
+ * @user_data: data to pass to @compare_func
*
* Like g_byte_array_sort(), but the comparison function takes an extra
* user data argument.
- **/
+ */
void
g_byte_array_sort_with_data (GByteArray *array,
- GCompareDataFunc compare_func,
- gpointer user_data)
+ GCompareDataFunc compare_func,
+ gpointer user_data)
{
g_array_sort_with_data ((GArray *) array, compare_func, user_data);
}
diff --git a/glib/ggettext.c b/glib/ggettext.c
index 61d20d1..bd5c9d4 100644
--- a/glib/ggettext.c
+++ b/glib/ggettext.c
@@ -520,11 +520,11 @@ g_dngettext (const gchar *domain,
* See the C_() macro for a different way to mark up translatable strings
* with context.
*
- * <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
*/
diff --git a/glib/gkeyfile.c b/glib/gkeyfile.c
index d7a6648..d8c01bb 100644
--- a/glib/gkeyfile.c
+++ b/glib/gkeyfile.c
@@ -3561,16 +3561,15 @@ g_key_file_has_key_full (GKeyFile *key_file,
* Looks whether the key file has the key @key in the group
* @group_name.
*
- * <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
**/
diff --git a/glib/glib-unix.c b/glib/glib-unix.c
index ec8cc5c..5fad19d 100644
--- a/glib/glib-unix.c
+++ b/glib/glib-unix.c
@@ -63,19 +63,17 @@ g_unix_set_error_from_errno (GError **error,
/**
* g_unix_open_pipe:
* @fds: Array of two integers
- * @flags: Bitfield of file descriptor flags, see "man 2 fcntl"
+ * @flags: Bitfield of file descriptor flags, as for fcntl()
* @error: a #GError
*
* Similar to the UNIX pipe() call, but on modern systems like Linux
* uses the pipe2() system call, which atomically creates a pipe with
- * the configured flags. The only supported flag currently is
- * <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
*
diff --git a/glib/glist.c b/glib/glist.c
index 30c0a5b..1096f86 100644
--- a/glib/glist.c
+++ b/glib/glist.c
@@ -174,13 +174,10 @@ g_list_alloc (void)
* @list: a #GList
*
* Frees all of the memory used by a #GList.
- * The freed elements are returned to the slice allocator
+ * The freed elements are returned to the slice allocator.
*
- * <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
*
diff --git a/glib/gmacros.h b/glib/gmacros.h
index a181c97..6403a99 100644
--- a/glib/gmacros.h
+++ b/glib/gmacros.h
@@ -42,18 +42,16 @@
* "long long" types even in the presence of '-ansi -pedantic'.
*/
#if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 8)
-# define G_GNUC_EXTENSION __extension__
+#define G_GNUC_EXTENSION __extension__
#else
-# define G_GNUC_EXTENSION
+#define G_GNUC_EXTENSION
#endif
/* Provide macros to feature the GCC function attribute.
*/
#if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 96)
-#define G_GNUC_PURE \
- __attribute__((__pure__))
-#define G_GNUC_MALLOC \
- __attribute__((__malloc__))
+#define G_GNUC_PURE __attribute__((__pure__))
+#define G_GNUC_MALLOC __attribute__((__malloc__))
#else
#define G_GNUC_PURE
#define G_GNUC_MALLOC
@@ -99,8 +97,7 @@
#endif /* !__GNUC__ */
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1)
-#define G_GNUC_DEPRECATED \
- __attribute__((__deprecated__))
+#define G_GNUC_DEPRECATED __attribute__((__deprecated__))
#else
#define G_GNUC_DEPRECATED
#endif /* __GNUC__ */
@@ -130,14 +127,13 @@
#endif
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3)
-# define G_GNUC_MAY_ALIAS __attribute__((may_alias))
+#define G_GNUC_MAY_ALIAS __attribute__((may_alias))
#else
-# define G_GNUC_MAY_ALIAS
+#define G_GNUC_MAY_ALIAS
#endif
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
-#define G_GNUC_WARN_UNUSED_RESULT \
- __attribute__((warn_unused_result))
+#define G_GNUC_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
#else
#define G_GNUC_WARN_UNUSED_RESULT
#endif /* __GNUC__ */
@@ -185,29 +181,29 @@
/* Provide a string identifying the current code position */
#if defined(__GNUC__) && (__GNUC__ < 3) && !defined(__cplusplus)
-# define G_STRLOC __FILE__ ":" G_STRINGIFY (__LINE__) ":" __PRETTY_FUNCTION__ "()"
+#define G_STRLOC __FILE__ ":" G_STRINGIFY (__LINE__) ":" __PRETTY_FUNCTION__ "()"
#else
-# define G_STRLOC __FILE__ ":" G_STRINGIFY (__LINE__)
+#define G_STRLOC __FILE__ ":" G_STRINGIFY (__LINE__)
#endif
/* Provide a string identifying the current function, non-concatenatable */
#if defined (__GNUC__) && defined (__cplusplus)
-# define G_STRFUNC ((const char*) (__PRETTY_FUNCTION__))
+#define G_STRFUNC ((const char*) (__PRETTY_FUNCTION__))
#elif defined (__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
-# define G_STRFUNC ((const char*) (__func__))
+#define G_STRFUNC ((const char*) (__func__))
#elif defined (__GNUC__) || (defined(_MSC_VER) && (_MSC_VER > 1300))
-# define G_STRFUNC ((const char*) (__FUNCTION__))
+#define G_STRFUNC ((const char*) (__FUNCTION__))
#else
-# define G_STRFUNC ((const char*) ("???"))
+#define G_STRFUNC ((const char*) ("???"))
#endif
/* Guard C code in headers, while including them from C++ */
#ifdef __cplusplus
-# define G_BEGIN_DECLS extern "C" {
-# define G_END_DECLS }
+#define G_BEGIN_DECLS extern "C" {
+#define G_END_DECLS }
#else
-# define G_BEGIN_DECLS
-# define G_END_DECLS
+#define G_BEGIN_DECLS
+#define G_END_DECLS
#endif
/* Provide definitions for some commonly used macros.
@@ -217,9 +213,9 @@
*/
#ifndef NULL
# ifdef __cplusplus
-# define NULL (0L)
+# define NULL (0L)
# else /* !__cplusplus */
-# define NULL ((void*) 0)
+# define NULL ((void*) 0)
# endif /* !__cplusplus */
#endif
@@ -259,10 +255,10 @@
*/
#if defined(__GNUC__) && __GNUC__ >= 4
-# define G_STRUCT_OFFSET(struct_type, member) \
+#define G_STRUCT_OFFSET(struct_type, member) \
((glong) offsetof (struct_type, member))
#else
-# define G_STRUCT_OFFSET(struct_type, member) \
+#define G_STRUCT_OFFSET(struct_type, member) \
((glong) ((guint8*) &((struct_type*) 0)->member))
#endif
@@ -279,8 +275,8 @@
* avoid portability issue or side effects when compiled with different compilers.
*/
#if !(defined (G_STMT_START) && defined (G_STMT_END))
-# define G_STMT_START do
-# define G_STMT_END while (0)
+#define G_STMT_START do
+#define G_STMT_END while (0)
#endif
/* Deprecated -- do not use. */
diff --git a/glib/gmem.c b/glib/gmem.c
index ec1c1cc..980cc09 100644
--- a/glib/gmem.c
+++ b/glib/gmem.c
@@ -66,18 +66,15 @@ static GMemVTable glib_mem_vtable = {
*
* These functions provide support for allocating and freeing memory.
*
- * <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 --- */
diff --git a/glib/gqueue.c b/glib/gqueue.c
index a78c08c..926539c 100644
--- a/glib/gqueue.c
+++ b/glib/gqueue.c
@@ -75,11 +75,8 @@ g_queue_new (void)
* if @queue was created with g_queue_new(). If queue elements contain
* dynamically-allocated memory, they should be freed first.
*
- * <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)
diff --git a/glib/gsequence.c b/glib/gsequence.c
index a17953b..9f65b5f 100644
--- a/glib/gsequence.c
+++ b/glib/gsequence.c
@@ -769,13 +769,11 @@ g_sequence_sort_changed (GSequenceIter *iter,
* If you are simply searching for an existing element of the sequence,
* consider using g_sequence_lookup().
*
- * <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
diff --git a/glib/gslist.c b/glib/gslist.c
index 0143ded..1915f91 100644
--- a/glib/gslist.c
+++ b/glib/gslist.c
@@ -128,11 +128,9 @@ g_slist_alloc (void)
* Frees all of the memory used by a #GSList.
* The freed elements are returned to the slice allocator.
*
- * <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>
*
* |[
* /* Notice that these are initialized to the empty list. */
@@ -242,10 +236,8 @@ g_slist_append (GSList *list,
*
* Adds a new element on to the start of the list.
*
- * <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>
*
* |[
* /* Notice that it is initialized to the empty list. */
@@ -515,11 +507,11 @@ _g_slist_remove_link (GSList *list,
* link is set to %NULL, so that it becomes a
* self-contained list with one element.
*
- * <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
*/
diff --git a/glib/gspawn.c b/glib/gspawn.c
index 0e6106c..86aa89c 100644
--- a/glib/gspawn.c
+++ b/glib/gspawn.c
@@ -109,17 +109,14 @@ G_DEFINE_QUARK (g-spawn-exit-error-quark, g_spawn_exit_error)
* You should call g_spawn_close_pid() on the returned child process
* reference when you don't need it any more.
*
- * <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
diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c
index 019a348..89d212d 100644
--- a/glib/gstrfuncs.c
+++ b/glib/gstrfuncs.c
@@ -398,18 +398,16 @@ g_memdup (gconstpointer mem,
* @n: the maximum number of bytes to copy from @str
*
* Duplicates the first @n bytes of a string, returning a newly-allocated
- * buffer @n + 1 bytes long which will always be nul-terminated.
- * If @str is less than @n bytes long the buffer is padded with nuls.
- * If @str is %NULL it returns %NULL.
- * The returned value should be freed when no longer needed.
+ * buffer @n + 1 bytes long which will always be nul-terminated. If @str
+ * is less than @n bytes long the buffer is padded with nuls. If @str is
+ * %NULL it returns %NULL. The returned value should be freed when no longer
+ * needed.
*
- * <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 < @s2,
- * or a positive value if @s1 > @s2.
- **/
+ * or a positive value if @s1 > @s2.
+ */
gint
g_ascii_strcasecmp (const gchar *s1,
const gchar *s2)
@@ -1772,9 +1765,9 @@ g_ascii_strcasecmp (const gchar *s1,
/**
* g_ascii_strncasecmp:
- * @s1: string to compare with @s2.
- * @s2: string to compare with @s1.
- * @n: number of characters to compare.
+ * @s1: string to compare with @s2
+ * @s2: string to compare with @s1
+ * @n: number of characters to compare
*
* Compare @s1 and @s2, ignoring the case of ASCII characters and any
* characters after the first @n in each string.
@@ -1788,12 +1781,12 @@ g_ascii_strcasecmp (const gchar *s1,
* corresponding to ASCII letters always represent themselves.
*
* Return value: 0 if the strings match, a negative value if @s1 < @s2,
- * or a positive value if @s1 > @s2.
- **/
+ * or a positive value if @s1 > @s2.
+ */
gint
g_ascii_strncasecmp (const gchar *s1,
const gchar *s2,
- gsize n)
+ gsize n)
{
gint c1, c2;
@@ -1818,18 +1811,18 @@ g_ascii_strncasecmp (const gchar *s1,
/**
* g_strcasecmp:
- * @s1: a string.
- * @s2: a string to compare with @s1.
+ * @s1: a string
+ * @s2: a string to compare with @s1
*
* A case-insensitive string comparison, corresponding to the standard
* strcasecmp() function on platforms which support it.
*
* Return value: 0 if the strings match, a negative value if @s1 < @s2,
- * or a positive value if @s1 > @s2.
+ * or a positive value if @s1 > @s2.
*
- * Deprecated:2.2: See g_strncasecmp() for a discussion of why this function
- * is deprecated and how to replace it.
- **/
+ * Deprecated:2.2: See g_strncasecmp() for a discussion of why this
+ * function is deprecated and how to replace it.
+ */
gint
g_strcasecmp (const gchar *s1,
const gchar *s2)
@@ -1863,33 +1856,33 @@ g_strcasecmp (const gchar *s1,
/**
* g_strncasecmp:
- * @s1: a string.
- * @s2: a string to compare with @s1.
- * @n: the maximum number of characters to compare.
+ * @s1: a string
+ * @s2: a string to compare with @s1
+ * @n: the maximum number of characters to compare
*
* A case-insensitive string comparison, corresponding to the standard
- * strncasecmp() function on platforms which support it.
- * It is similar to g_strcasecmp() except it only compares the first @n
- * characters of the strings.
+ * strncasecmp() function on platforms which support it. It is similar
+ * to g_strcasecmp() except it only compares the first @n characters of
+ * the strings.
*
* Return value: 0 if the strings match, a negative value if @s1 < @s2,
- * or a positive value if @s1 > @s2.
- *
- * Deprecated:2.2: The problem with g_strncasecmp() is that it does the
- * comparison by calling toupper()/tolower(). These functions are
- * locale-specific and operate on single bytes. However, it is impossible
- * to handle things correctly from an I18N standpoint by operating on
- * bytes, since characters may be multibyte. Thus g_strncasecmp() is
- * broken if your string is guaranteed to be ASCII, since it's
- * locale-sensitive, and it's broken if your string is localized, since
- * it doesn't work on many encodings at all, including UTF-8, EUC-JP,
- * etc.
- *
- * There are therefore two replacement techniques: g_ascii_strncasecmp(),
- * which only works on ASCII and is not locale-sensitive, and
- * g_utf8_casefold() followed by strcmp() on the resulting strings, which is
- * good for case-insensitive sorting of UTF-8.
- **/
+ * or a positive value if @s1 > @s2.
+ *
+ * Deprecated:2.2: The problem with g_strncasecmp() is that it does
+ * the comparison by calling toupper()/tolower(). These functions
+ * are locale-specific and operate on single bytes. However, it is
+ * impossible to handle things correctly from an internationalization
+ * standpoint by operating on bytes, since characters may be multibyte.
+ * Thus g_strncasecmp() is broken if your string is guaranteed to be
+ * ASCII, since it is locale-sensitive, and it's broken if your string
+ * is localized, since it doesn't work on many encodings at all,
+ * including UTF-8, EUC-JP, etc.
+ *
+ * There are therefore two replacement techniques: g_ascii_strncasecmp(),
+ * which only works on ASCII and is not locale-sensitive, and
+ * g_utf8_casefold() followed by strcmp() on the resulting strings,
+ * which is good for case-insensitive sorting of UTF-8.
+ */
gint
g_strncasecmp (const gchar *s1,
const gchar *s2,
@@ -1926,8 +1919,8 @@ g_strncasecmp (const gchar *s1,
/**
* g_strdelimit:
* @string: the string to convert
- * @delimiters: (allow-none): a string containing the current delimiters, or %NULL
- * to use the standard delimiters defined in #G_STR_DELIMITERS
+ * @delimiters: (allow-none): a string containing the current delimiters,
+ * or %NULL to use the standard delimiters defined in #G_STR_DELIMITERS
* @new_delimiter: the new delimiter character
*
* Converts any delimiter characters in @string to @new_delimiter.
@@ -1968,10 +1961,10 @@ g_strdelimit (gchar *string,
* @valid_chars: bytes permitted in @string
* @substitutor: replacement character for disallowed bytes
*
- * For each character in @string, if the character is not in
- * @valid_chars, replaces the character with @substitutor.
- * Modifies @string in place, and return @string itself, not
- * a copy. The return value is to allow nesting such as
+ * For each character in @string, if the character is not in @valid_chars,
+ * replaces the character with @substitutor. Modifies @string in place,
+ * and return @string itself, not a copy. The return value is to allow
+ * nesting such as
* |[
* g_ascii_strup (g_strcanon (str, "abc", '?'))
* ]|
@@ -2424,7 +2417,7 @@ g_strsplit_set (const gchar *string,
* Frees a %NULL-terminated array of strings, and the array itself.
* If called on a %NULL value, g_strfreev() simply returns.
- **/
+ */
void
g_strfreev (gchar **str_array)
{
@@ -2480,7 +2473,8 @@ g_strdupv (gchar **str_array)
/**
* g_strjoinv:
- * @separator: (allow-none): a string to insert between each of the strings, or %NULL
+ * @separator: (allow-none): a string to insert between each of the
+ * strings, or %NULL
* @str_array: a %NULL-terminated array of strings to join
*
* Joins a number of strings together to form one long string, with the
@@ -2532,7 +2526,8 @@ g_strjoinv (const gchar *separator,
/**
* g_strjoin:
- * @separator: (allow-none): a string to insert between each of the strings, or %NULL
+ * @separator: (allow-none): a string to insert between each of the
+ * strings, or %NULL
* @...: a %NULL-terminated list of strings to join
*
* Joins a number of strings together to form one long string, with the
diff --git a/glib/gthread-posix.c b/glib/gthread-posix.c
index ae6d34b..79afd32 100644
--- a/glib/gthread-posix.c
+++ b/glib/gthread-posix.c
@@ -195,10 +195,10 @@ g_mutex_clear (GMutex *mutex)
* current thread will block until @mutex is unlocked by the other
* thread.
*
- * <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
*/
diff --git a/glib/gthread.c b/glib/gthread.c
index a7687e4..d410dbc 100644
--- a/glib/gthread.c
+++ b/glib/gthread.c
@@ -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)
diff --git a/glib/gutils.c b/glib/gutils.c
index fccf994..071471d 100644
--- a/glib/gutils.c
+++ b/glib/gutils.c
@@ -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
*/
diff --git a/gobject/gbinding.c b/gobject/gbinding.c
index c2342d9..7a9f562 100644
--- a/gobject/gbinding.c
+++ b/gobject/gbinding.c
@@ -94,10 +94,10 @@
* either one of the #GObject instances it refers to are finalized, or when
* the #GBinding instance loses its last reference.
*
- * <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
*/
diff --git a/gobject/gobject.c b/gobject/gobject.c
index 18c7aee..a18fcfb 100644
--- a/gobject/gobject.c
+++ b/gobject/gobject.c
@@ -815,7 +815,6 @@ g_object_interface_find_property (gpointer g_iface,
* a property implementation in a parent class or to provide
* the implementation of a property from an interface.
*
- * <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
*/
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
