diff options
Diffstat (limited to 'gir/glib-2.0.c')
| -rw-r--r-- | gir/glib-2.0.c | 6059 |
1 files changed, 2896 insertions, 3163 deletions
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index bb403b15..a68339e5 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -44,15 +44,14 @@ * used as a context. This is mainly useful for short strings which * may need different translations, depending on the context in which * they are used. - * |[ + * |[<!-- language="C" --> * label1 = C_("Navigation", "Back"); * 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 + * `--keyword=C_:1c,2` to xgettext when extracting messages. + * Note that this only works with GNU gettext >= 0.15. * * Returns: the translated message * Since: 2.16 @@ -69,11 +68,11 @@ /** * 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. */ @@ -82,18 +81,17 @@ * * The GAsyncQueue struct is an opaque data structure which represents * an asynchronous queue. It should only be accessed through the - * <function>g_async_queue_*</function> functions. + * g_async_queue_* functions. */ /** * 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 <structname>GByteArray</structname> struct allows access to the - * public fields of a <structname>GByteArray</structname>. + * Contains the public fields of a GByteArray. */ @@ -174,11 +172,9 @@ * another thread publishes the data, it can signal one of the waiting * threads to wake up to collect the data. * - * <example> - * <title> - * Using GCond to block a thread until a condition is satisfied - * </title> - * <programlisting> + * Here is an example for using GCond to block a thread until a condition + * is satisfied: + * |[<!-- language="C" --> * gpointer current_data = NULL; * GMutex data_mutex; * GCond data_cond; @@ -206,21 +202,19 @@ * * return data; * } - * </programlisting> - * </example> - * + * ]| * Whenever a thread calls pop_data() now, it will wait until * current_data is non-%NULL, i.e. until some other thread * has called push_data(). * * The example shows that use of a condition variable must always be * paired with a mutex. Without the use of a mutex, there would be a - * race between the check of <varname>current_data</varname> by the - * while loop in <function>pop_data</function> and waiting. - * Specifically, another thread could set <varname>pop_data</varname> - * after the check, and signal the cond (with nobody waiting on it) - * before the first thread goes to sleep. #GCond is specifically useful - * for its ability to release the mutex and go to sleep atomically. + * race between the check of @current_data by the while loop in + * pop_data() and waiting. Specifically, another thread could set + * @current_data after the check, and signal the cond (with nobody + * waiting on it) before the first thread goes to sleep. #GCond is + * specifically useful for its ability to release the mutex and go + * to sleep atomically. * * It is also important to use the g_cond_wait() and g_cond_wait_until() * functions only inside a loop which checks for the condition to be @@ -228,11 +222,10 @@ * not be true even after it returns. * * If a #GCond is allocated in static storage then it can be used - * without initialisation. Otherwise, you should call g_cond_init() on - * it and g_cond_clear() when done. + * without initialisation. Otherwise, you should call g_cond_init() + * on it and g_cond_clear() when done. * - * A #GCond should only be accessed via the <function>g_cond_</function> - * functions. + * A #GCond should only be accessed via the g_cond_ functions. */ @@ -269,14 +262,16 @@ * @year: the day of the day-month-year representation of the date * * Represents a day between January 1, Year 1 and a few thousand years in - * the future. None of its members should be accessed directly. If the - * <structname>GDate</structname> is obtained from g_date_new(), it will - * be safe to mutate but invalid and thus not safe for calendrical - * computations. If it's declared on the stack, it will contain garbage - * so must be initialized with g_date_clear(). g_date_clear() makes the - * date invalid but sane. An invalid date doesn't represent a day, it's - * "empty." A date becomes valid after you set it to a Julian day or you - * set a day, month, and year. + * the future. None of its members should be accessed directly. + * + * If the #GDate-struct is obtained from g_date_new(), it will be safe + * to mutate but invalid and thus not safe for calendrical computations. + * + * If it's declared on the stack, it will contain garbage so must be + * initialized with g_date_clear(). g_date_clear() makes the date invalid + * but sane. An invalid date doesn't represent a day, it's "empty." A date + * becomes valid after you set it to a Julian day or you set a day, month, + * and year. */ @@ -294,8 +289,8 @@ /** * GDateDay: * - * Integer representing a day of the month; between 1 and - * 31. #G_DATE_BAD_DAY represents an invalid day of the month. + * Integer representing a day of the month; between 1 and 31. + * #G_DATE_BAD_DAY represents an invalid day of the month. */ @@ -593,7 +588,7 @@ * and #gchar* respectively. * * g_direct_hash() is also the appropriate hash function for keys - * of the form <literal>GINT_TO_POINTER (n)</literal> (or similar macros). + * of the form `GINT_TO_POINTER (n)` (or similar macros). * * <!-- FIXME: Need more here. --> A good hash functions should produce * hash values that are evenly distributed over a fairly large range. @@ -607,7 +602,8 @@ * a more secure hash function when using a GHashTable with keys * that originate in untrusted data (such as HTTP requests). * Using g_str_hash() in that situation might make your application - * vulerable to <ulink url="https://lwn.net/Articles/474912/">Algorithmic Complexity Attacks</ulink>. + * vulerable to + * [Algorithmic Complexity Attacks](https://lwn.net/Articles/474912/). * * The key to choosing a good hash is unpredictability. Even * cryptographic hashes are very easy to find collisions for when the @@ -651,8 +647,7 @@ * @destroy: the default @finalize_hook function of a #GHookList calls * this member of the hook that is being finalized * - * The <structname>GHook</structname> struct represents a single hook - * function in a #GHookList. + * The #GHook struct represents a single hook function in a #GHookList. */ @@ -742,8 +737,7 @@ * The default behaviour is to call the hooks @destroy function * @dummy: unused * - * The <structname>GHookList</structname> struct represents a - * list of hook functions. + * The #GHookList struct represents a list of hook functions. */ @@ -923,9 +917,9 @@ * Stuffs an integer into a pointer type. * * Remember, you may not store pointers in integers. This is not portable - * in any way, shape or form. These macros <emphasis>only</emphasis> allow - * storing integers in pointers, and only preserve 32 bits of the - * integer; values outside the range of a 32-bit integer will be mangled. + * in any way, shape or form. These macros only allow storing integers in + * pointers, and only preserve 32 bits of the integer; values outside the + * range of a 32-bit integer will be mangled. */ @@ -983,24 +977,26 @@ /** * GIOFlags: - * @G_IO_FLAG_APPEND: turns on append mode, corresponds to <literal>O_APPEND</literal> - * (see the documentation of the UNIX open() - * syscall). + * @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND + * (see the documentation of the UNIX open() syscall) * @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to - * <literal>O_NONBLOCK</literal>/<literal>O_NDELAY</literal> - * (see the documentation of the UNIX open() syscall). + * %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open() + * syscall) * @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable. - * This flag cannot be changed. + * This flag cannot be changed. * @G_IO_FLAG_IS_WRITABLE: indicates that the io channel is writable. - * This flag cannot be changed. + * This flag cannot be changed. + * G_IO_FLAG_IS_WRITEABLE: a misspelled version of @G_IO_FLAG_IS_WRITABLE + * that existed before the spelling was fixed in GLib 2.30. It is kept + * here for compatibility reasons. Deprecated since 2.30 * @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable, - * i.e. that g_io_channel_seek_position() can - * be used on it. This flag cannot be changed. + * i.e. that g_io_channel_seek_position() can be used on it. + * This flag cannot be changed. * @G_IO_FLAG_MASK: the mask that specifies all the valid flags. * @G_IO_FLAG_GET_MASK: the mask of the flags that are returned from - * g_io_channel_get_flags(). + * g_io_channel_get_flags() * @G_IO_FLAG_SET_MASK: the mask of the flags that the user can modify - * with g_io_channel_set_flags(). + * with g_io_channel_set_flags() * * Specifies properties of a #GIOChannel. Some of the flags can only be * read with g_io_channel_get_flags(), but not changed with @@ -1115,17 +1111,7 @@ * @micro: the micro version to check for * * Checks the version of the GLib library that is being compiled - * against. - * - * <example> - * <title>Checking the version of the GLib library</title> - * <programlisting> - * if (!GLIB_CHECK_VERSION (1, 2, 0)) - * g_error ("GLib version 1.2.0 or above is needed"); - * </programlisting> - * </example> - * - * See glib_check_version() for a runtime check. + * against. See glib_check_version() for a runtime check. * * Returns: %TRUE if the version of the GLib header files * is the same as or newer than the passed-in version. @@ -1314,33 +1300,27 @@ * * The #GMutex struct is an opaque data structure to represent a mutex * (mutual exclusion). It can be used to protect data against shared - * access. Take for example the following function: + * access. * - * <example> - * <title>A function which will not work in a threaded environment</title> - * <programlisting> + * Take for example the following function: + * |[<!-- language="C" --> * int * give_me_next_number (void) * { * static int current_number = 0; * - * /<!-- -->* now do a very complicated calculation to calculate the new - * * number, this might for example be a random number generator - * *<!-- -->/ + * /* now do a very complicated calculation to calculate the new + * * number, this might for example be a random number generator + * */ * current_number = calc_next_number (current_number); * * return current_number; * } - * </programlisting> - * </example> - * + * ]| * It is easy to see that this won't work in a multi-threaded * application. There current_number must be protected against shared * access. A #GMutex can be used as a solution to this problem: - * - * <example> - * <title>Using GMutex to protected a shared variable</title> - * <programlisting> + * |[<!-- language="C" --> * int * give_me_next_number (void) * { @@ -1348,15 +1328,13 @@ * static int current_number = 0; * int ret_val; * - * g_mutex_lock (&mutex); + * g_mutex_lock (&mutex); * ret_val = current_number = calc_next_number (current_number); - * g_mutex_unlock (&mutex); + * g_mutex_unlock (&mutex); * * return ret_val; * } - * </programlisting> - * </example> - * + * ]| * Notice that the #GMutex is not initialised to any particular value. * Its placement in static storage ensures that it will be initialised * to all-zeros, which is appropriate. @@ -1364,8 +1342,7 @@ * If a #GMutex is placed in other contexts (eg: embedded in a struct) * then it must be explicitly initialised using g_mutex_init(). * - * A #GMutex should only be accessed via <function>g_mutex_</function> - * functions. + * A #GMutex should only be accessed via g_mutex_ functions. */ @@ -1446,9 +1423,9 @@ * been stored in the pointer with GINT_TO_POINTER(). * * Remember, you may not store pointers in integers. This is not portable - * in any way, shape or form. These macros <emphasis>only</emphasis> allow - * storing integers in pointers, and only preserve 32 bits of the - * integer; values outside the range of a 32-bit integer will be mangled. + * in any way, shape or form. These macros only allow storing integers in + * pointers, and only preserve 32 bits of the integer; values outside the + * range of a 32-bit integer will be mangled. */ @@ -1473,9 +1450,8 @@ /** * GPatternSpec: * - * A <structname>GPatternSpec</structname> is the 'compiled' form of a - * pattern. This structure is opaque and its fields cannot be accessed - * directly. + * A GPatternSpec struct is the 'compiled' form of a pattern. This + * structure is opaque and its fields cannot be accessed directly. */ @@ -1498,15 +1474,15 @@ * See G_PRIVATE_INIT() for a couple of examples. * * The #GPrivate structure should be considered opaque. It should only - * be accessed via the <function>g_private_</function> functions. + * be accessed via the g_private_ functions. */ /** * 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. */ @@ -1534,9 +1510,8 @@ * simultaneous read-only access (by holding the 'reader' lock via * g_rw_lock_reader_lock()). * - * <example> - * <title>An array with access functions</title> - * <programlisting> + * Here is an example for an array with access functions: + * |[<!-- language="C" --> * GRWLock lock; * GPtrArray *array; * @@ -1548,10 +1523,10 @@ * if (!array) * return NULL; * - * g_rw_lock_reader_lock (&lock); - * if (index < array->len) + * g_rw_lock_reader_lock (&lock); + * if (index < array->len) * retval = g_ptr_array_index (array, index); - * g_rw_lock_reader_unlock (&lock); + * g_rw_lock_reader_unlock (&lock); * * return retval; * } @@ -1559,35 +1534,30 @@ * void * my_array_set (guint index, gpointer data) * { - * g_rw_lock_writer_lock (&lock); + * g_rw_lock_writer_lock (&lock); * * if (!array) - * array = g_ptr_array_new (<!-- -->); + * array = g_ptr_array_new (); * * if (index >= array->len) * g_ptr_array_set_size (array, index+1); * g_ptr_array_index (array, index) = data; * - * g_rw_lock_writer_unlock (&lock); + * g_rw_lock_writer_unlock (&lock); * } - * </programlisting> - * <para> - * This example shows an array which can be accessed by many readers - * (the <function>my_array_get()</function> function) simultaneously, - * whereas the writers (the <function>my_array_set()</function> - * function) will only be allowed once at a time and only if no readers - * currently access the array. This is because of the potentially - * dangerous resizing of the array. Using these functions is fully - * multi-thread safe now. - * </para> - * </example> + * ]| + * This example shows an array which can be accessed by many readers + * (the my_array_get() function) simultaneously, whereas the writers + * (the my_array_set() function) will only be allowed one at a time + * and only if no readers currently access the array. This is because + * of the potentially dangerous resizing of the array. Using these + * functions is fully multi-thread safe now. * * If a #GRWLock is allocated in static storage then it can be used * without initialisation. Otherwise, you should call * g_rw_lock_init() on it and g_rw_lock_clear() when done. * - * A GRWLock should only be accessed with the - * <function>g_rw_lock_</function> functions. + * A GRWLock should only be accessed with the g_rw_lock_ functions. * * Since: 2.32 */ @@ -1596,8 +1566,8 @@ /** * GRand: * - * The #GRand struct is an opaque data structure. It should only be - * accessed through the <function>g_rand_*</function> functions. + * The GRand struct is an opaque data structure. It should only be + * accessed through the g_rand_* functions. */ @@ -1615,7 +1585,7 @@ * g_rec_mutex_init() on it and g_rec_mutex_clear() when done. * * A GRecMutex should only be accessed with the - * <function>g_rec_mutex_</function> functions. + * g_rec_mutex_ functions. * * Since: 2.32 */ @@ -1809,11 +1779,9 @@ * @identifier_2_string: specifies if identifiers are reported as strings * (the default is %FALSE). * @char_2_token: specifies if characters are reported by setting - * <literal>token = ch</literal> or as %G_TOKEN_CHAR (the default - * is %TRUE). + * `token = ch` or as %G_TOKEN_CHAR (the default is %TRUE). * @symbol_2_token: specifies if symbols are reported by setting - * <literal>token = v_symbol</literal> or as %G_TOKEN_SYMBOL (the - * default is %FALSE). + * `token = v_symbol` or as %G_TOKEN_SYMBOL (the default is %FALSE). * @scope_0_fallback: specifies if a symbol is searched for in the * default scope in addition to the current scope (the default is %FALSE). * @store_int64: use value.v_int64 rather than v_int @@ -1873,8 +1841,7 @@ * if @a comes before @b, and a positive value if @b comes before @a. * * Returns: zero if the iterators are equal, a negative value if @a - * comes before @b, and a positive value if @b comes before - * @a. + * comes before @b, and a positive value if @b comes before @a. */ @@ -1891,7 +1858,7 @@ /** * GStatBuf: * - * A type corresponding to the appropriate struct type for the stat + * A type corresponding to the appropriate struct type for the stat() * system call, depending on the platform and/or compiler being used. * * See g_stat() for more information. @@ -1950,9 +1917,9 @@ * 'built' terminology that automake uses and are explicitly used to * distinguish between the 'srcdir' and 'builddir' being separate. All * files in your project should either be dist (in the - * <literal>DIST_EXTRA</literal> or <literal>dist_schema_DATA</literal> + * `DIST_EXTRA` or `dist_schema_DATA` * sense, in which case they will always be in the srcdir) or built (in - * the <literal>BUILT_SOURCES</literal> sense, in which case they will + * the `BUILT_SOURCES` sense, in which case they will * always be in the builddir). * * Note: as a general rule of automake, files that are generated only as @@ -1997,7 +1964,7 @@ * GTestSubprocessFlags: * @G_TEST_SUBPROCESS_INHERIT_STDIN: If this flag is given, the child * process will inherit the parent's stdin. Otherwise, the child's - * stdin is redirected to <filename>/dev/null</filename>. + * stdin is redirected to `/dev/null`. * @G_TEST_SUBPROCESS_INHERIT_STDOUT: If this flag is given, the child * process will inherit the parent's stdout. Otherwise, the child's * stdout will not be visible, but it will be captured to allow @@ -2024,16 +1991,16 @@ /** * GTestTrapFlags: * @G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to - * <filename>/dev/null</filename> so it cannot be observed on the - * console during test runs. The actual output is still captured - * though to allow later tests with g_test_trap_assert_stdout(). + * `/dev/null` so it cannot be observed on the console during test + * runs. The actual output is still captured though to allow later + * tests with g_test_trap_assert_stdout(). * @G_TEST_TRAP_SILENCE_STDERR: Redirect stderr of the test child to - * <filename>/dev/null</filename> so it cannot be observed on the - * console during test runs. The actual output is still captured - * though to allow later tests with g_test_trap_assert_stderr(). + * `/dev/null` so it cannot be observed on the console during test + * runs. The actual output is still captured though to allow later + * tests with g_test_trap_assert_stderr(). * @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the * child process is shared with stdin of its parent process. - * It is redirected to <filename>/dev/null</filename> otherwise. + * It is redirected to `/dev/null` otherwise. * * Test traps are guards around forked tests. * These flags determine what traps to set. @@ -2049,7 +2016,7 @@ * * The #GThread struct represents a running thread. This struct * is returned by g_thread_new() or g_thread_try_new(). You can - * obtain the #GThread struct representing the current thead by + * obtain the #GThread struct representing the current thread by * calling g_thread_self(). * * GThread is refcounted, see g_thread_ref() and g_thread_unref(). @@ -2098,21 +2065,22 @@ /** * GTime: * - * Simply a replacement for <type>time_t</type>. It has been deprecated - * since it is <emphasis>not</emphasis> equivalent to <type>time_t</type> - * on 64-bit platforms with a 64-bit <type>time_t</type>. - * Unrelated to #GTimer. + * Simply a replacement for time_t. It has been deprecated + * since it is not equivalent to time_t on 64-bit platforms + * with a 64-bit time_t. Unrelated to #GTimer. * - * Note that <type>GTime</type> is defined to always be a 32bit integer, - * unlike <type>time_t</type> which may be 64bit on some systems. - * Therefore, <type>GTime</type> will overflow in the year 2038, and - * you cannot use the address of a <type>GTime</type> variable as argument - * to the UNIX time() function. Instead, do the following: - * |[ + * Note that #GTime is defined to always be a 32-bit integer, + * unlike time_t which may be 64-bit on some systems. Therefore, + * #GTime will overflow in the year 2038, and you cannot use the + * address of a #GTime variable as argument to the UNIX time() + * function. + * + * Instead, do the following: + * |[<!-- language="C" --> * time_t ttime; * GTime gtime; * - * time (&ttime); + * time (&ttime); * gtime = (GTime)ttime; * ]| */ @@ -2124,8 +2092,8 @@ * @tv_usec: microseconds * * Represents a precise time, with seconds and microseconds. - * Similar to the <structname>struct timeval</structname> returned by - * the gettimeofday() UNIX system call. + * Similar to the struct timeval returned by the gettimeofday() + * UNIX system call. * * GLib is attempting to unify around the use of 64bit integers to * represent microsecond-precision time. As such, this type will be @@ -2203,11 +2171,11 @@ /** * GTrashStack: * @next: pointer to the previous element of the stack, - * gets stored in the first <literal>sizeof (gpointer)</literal> + * gets stored in the first `sizeof (gpointer)` * bytes of the element * * Each piece of memory that is pushed onto the stack - * is cast to a <structname>GTrashStack*</structname>. + * is cast to a GTrashStack*. */ @@ -2300,10 +2268,9 @@ /** * GTree: * - * The <structname>GTree</structname> struct is an opaque data - * structure representing a <link - * linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>. It - * should be accessed only by using the following functions. + * The GTree struct is an opaque data structure representing a <link + * linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>. + * It should be accessed only by using the following functions. */ @@ -2645,6 +2612,105 @@ /** + * GVariantDict: (skip) + * + * #GVariantDict is a mutable interface to #GVariant dictionaries. + * + * It can be used for doing a sequence of dictionary lookups in an + * efficient way on an existing #GVariant dictionary or it can be used + * to construct new dictionaries with a hashtable-like interface. It + * can also be used for taking existing dictionaries and modifying them + * in order to create new ones. + * + * #GVariantDict can only be used with %G_VARIANT_TYPE_VARDICT + * dictionaries. + * + * It is possible to use #GVariantDict allocated on the stack or on the + * heap. When using a stack-allocated #GVariantDict, you begin with a + * call to g_variant_dict_init() and free the resources with a call to + * g_variant_dict_clear(). + * + * Heap-allocated #GVariantDict follows normal refcounting rules: you + * allocate it with g_variant_dict_new() and use g_variant_dict_ref() + * and g_variant_dict_unref(). + * + * g_variant_dict_end() is used to convert the #GVariantDict back into a + * dictionary-type #GVariant. When used with stack-allocated instances, + * this also implicitly frees all associated memory, but for + * heap-allocated instances, you must still call g_variant_dict_unref() + * afterwards. + * + * You will typically want to use a heap-allocated #GVariantDict when + * you expose it as part of an API. For most other uses, the + * stack-allocated form will be more convenient. + * + * Consider the following two examples that do the same thing in each + * style: take an existing dictionary and look up the "count" uint32 + * key, adding 1 to it if it is found, or returning an error if the + * key is not found. Each returns the new dictionary as a floating + * #GVariant. + * + * <example> + * <title>Using stack-allocated #GVariantDict</title> + * <programlisting> + * GVariant * + * add_to_count (GVariant *orig, + * GError **error) + * { + * GVariantDict dict; + * guint32 count; + * + * g_variant_dict_init (&dict, orig); + * if (!g_variant_dict_lookup (&dict, "count", "u", &count)) + * { + * g_set_error (...); + * g_variant_dict_clear (&dict); + * return NULL; + * } + * + * g_variant_dict_insert (&dict, "count", "u", count + 1); + * + * return g_variant_dict_end (&dict); + * } + * </programlisting> + * </example> + * + * <example> + * <title>Using heap-allocated #GVariantDict</title> + * <programlisting> + * GVariant * + * add_to_count (GVariant *orig, + * GError **error) + * { + * GVariantDict *dict; + * GVariant *result; + * guint32 count; + * + * dict = g_variant_dict_new (orig); + * + * if (g_variant_dict_lookup (dict, "count", "u", &count)) + * { + * g_variant_dict_insert (dict, "count", "u", count + 1); + * result = g_variant_dict_end (dict); + * } + * else + * { + * g_set_error (...); + * result = NULL; + * } + * + * g_variant_dict_unref (dict); + * + * return result; + * } + * </programlisting> + * </example> + * + * Since: 2.40 + */ + + +/** * GVariantIter: (skip) * * #GVariantIter is an opaque data structure and can only be accessed @@ -2685,10 +2751,10 @@ * on systems with 64bit IEEE-compatible doubles. * * The typical usage would be something like: - * |[ + * |[<!-- language="C" --> * char buf[G_ASCII_DTOSTR_BUF_SIZE]; * - * fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value)); + * fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value)); * ]| */ @@ -2711,7 +2777,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. */ @@ -2736,19 +2802,17 @@ /** * G_CONST_RETURN: * - * If <literal>G_DISABLE_CONST_RETURNS</literal> is defined, this macro expands - * to nothing. By default, the macro expands to <literal>const</literal>. - * The macro should be used in place of <literal>const</literal> for - * functions that return a value that should not be modified. The - * purpose of this macro is to allow us to turn on <literal>const</literal> - * for returned constant strings by default, while allowing programmers - * who find that annoying to turn it off. This macro should only be used - * for return values and for <emphasis>out</emphasis> parameters, it doesn't - * make sense for <emphasis>in</emphasis> parameters. + * If %G_DISABLE_CONST_RETURNS is defined, this macro expands + * to nothing. By default, the macro expands to const. The macro + * can be used in place of const for functions that return a value + * that should not be modified. The purpose of this macro is to allow + * us to turn on const for returned constant strings by default, while + * allowing programmers who find that annoying to turn it off. This macro + * should only be used for return values and for "out" parameters, it + * doesn't make sense for "in" parameters. * * Deprecated: 2.30: API providers should replace all existing uses with - * <literal>const</literal> and API consumers should adjust their code - * accordingly + * const and API consumers should adjust their code accordingly */ @@ -2818,9 +2882,10 @@ * * A convenience macro which defines a function returning the * #GQuark for the name @QN. The function will be named - * @q_n<!-- -->_quark(). - * Note that the quark name will be stringified automatically in the - * macro, so you shouldn't use double quotes. + * @q_n_quark(). + * + * Note that the quark name will be stringified automatically + * in the macro, so you shouldn't use double quotes. * * Since: 2.34 */ @@ -2843,8 +2908,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 @@ -2878,7 +2943,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. */ @@ -2900,10 +2965,10 @@ * include the percent-sign, such that you can add precision and length * modifiers between percent-sign and conversion specifier. * - * |[ + * |[<!-- language="C" --> * gint16 in; * gint32 out; - * sscanf ("42", "%" G_GINT16_FORMAT, &in) + * sscanf ("42", "%" G_GINT16_FORMAT, &in) * out = in * 1000; * g_print ("%" G_GINT32_FORMAT, out); * ]| @@ -2920,7 +2985,7 @@ * and conversion specifier and append a conversion specifier. * * The following example prints "0x7b"; - * |[ + * |[<!-- language="C" --> * gint16 value = 123; * g_print ("%#" G_GINT16_MODIFIER "x", value); * ]| @@ -2963,14 +3028,12 @@ * 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> */ @@ -2981,11 +3044,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 */ @@ -3016,10 +3077,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. @@ -3035,10 +3096,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. @@ -3052,16 +3113,15 @@ /** * 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> - * then neither macro has any effect.) + * are not compiling with `-Wdeprecated-declarations` then neither macro + * has any effect.) * * This macro can be used either inside or outside of a function body, * but must appear on a line by itself. @@ -3073,33 +3133,29 @@ /** * 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_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 `-Wdeprecated-declarations` option, + * gcc will generate warnings when deprecated interfaces are used. * * Place the attribute after the declaration, just before the semicolon. * @@ -3115,8 +3171,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. * @@ -3134,8 +3190,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. @@ -3147,10 +3203,9 @@ /** * 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 `-pedantic` option. */ @@ -3158,21 +3213,20 @@ * 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. * * See the GNU C documentation for more details. * - * |[ + * |[<!-- language="C" --> * gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2); * ]| */ @@ -3181,11 +3235,10 @@ /** * 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 */ @@ -3199,14 +3252,14 @@ * 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, * Sun Studio does not. * - * |[ + * |[<!-- language="C" --> * G_GNUC_INTERNAL * void _g_log_fallback_handler (const gchar *log_domain, * GLogLevelFlags log_level, @@ -3221,12 +3274,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. * @@ -3239,10 +3291,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 @@ -3252,10 +3304,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. * @@ -3266,10 +3317,10 @@ /** * 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 + * `-finstrument-functions` option. * * Place the attribute after the declaration, just before the semicolon. * @@ -3280,9 +3331,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. * @@ -3297,11 +3347,10 @@ /** * 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 */ @@ -3311,18 +3360,17 @@ * format string (The arguments are numbered from 1) * @arg_idx: the index of the first of the format arguments * - * Expands to the GNU C <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. * * See the GNU C documentation for more details. * - * |[ + * |[<!-- language="C" --> * gint g_snprintf (gchar *string, * gulong n, * gchar const *format, @@ -3334,11 +3382,11 @@ /** * 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. * @@ -3352,27 +3400,27 @@ * 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_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 * argument declaration. * - * |[ + * |[<!-- language="C" --> * void my_unused_function (G_GNUC_UNUSED gint unused_argument, * gint other_argument) G_GNUC_UNUSED; * ]| @@ -3384,10 +3432,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. * @@ -3495,14 +3542,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> */ @@ -3520,7 +3565,7 @@ * G_HOOK: * @hook: a pointer * - * Casts a pointer to a <literal>GHook*</literal>. + * Casts a pointer to a `GHook*`. */ @@ -3548,7 +3593,7 @@ * * The position of the first bit which is not reserved for internal * use be the #GHook implementation, i.e. - * <literal>1 << G_HOOK_FLAG_USER_SHIFT</literal> is the first + * `1 << G_HOOK_FLAG_USER_SHIFT` is the first * bit which can be used for application-defined flags. */ @@ -3603,7 +3648,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. @@ -3624,17 +3669,6 @@ /** - * G_IO_FLAG_IS_WRITEABLE: - * - * This is a misspelled version of G_IO_FLAG_IS_WRITABLE that existed - * before the spelling was fixed in GLib 2.30. It is kept here for - * compatibility reasons. - * - * Deprecated: 2.30: Use G_IO_FLAG_IS_WRITABLE instead. - */ - - -/** * G_IS_DIR_SEPARATOR: * @c: a character * @@ -3650,8 +3684,8 @@ * G_KEY_FILE_DESKTOP_GROUP: * * The name of the main group of a desktop entry file, as defined in the - * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop - * Entry Specification</ulink>. Consult the specification for more + * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec). + * Consult the specification for more * details about the meanings of the keys below. * * Since: 2.14 @@ -3684,7 +3718,7 @@ * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * giving the command line to execute. It is only valid for desktop - * entries with the <literal>Application</literal> type. + * entries with the `Application` type. * * Since: 2.14 */ @@ -3778,7 +3812,7 @@ * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * containing the working directory to run the program in. It is only - * valid for desktop entries with the <literal>Application</literal> type. + * valid for desktop entries with the `Application` type. * * Since: 2.14 */ @@ -3788,9 +3822,8 @@ * G_KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean - * stating whether the application supports the <ulink - * url="http://www.freedesktop.org/Standards/startup-notification-spec">Startup - * Notification Protocol Specification</ulink>. + * stating whether the application supports the + * [Startup Notification Protocol Specification](http://www.freedesktop.org/Standards/startup-notification-spec). * * Since: 2.14 */ @@ -3814,7 +3847,7 @@ * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean * stating whether the program should be run in a terminal window. * It is only valid for desktop entries with the - * <literal>Application</literal> type. + * `Application` type. * * Since: 2.14 */ @@ -3826,7 +3859,7 @@ * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * giving the file name of a binary on disk used to determine if the * program is actually installed. It is only valid for desktop entries - * with the <literal>Application</literal> type. + * with the `Application` type. * * Since: 2.14 */ @@ -3850,7 +3883,7 @@ * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * giving the URL to access. It is only valid for desktop entries - * with the <literal>Link</literal> type. + * with the `Link` type. * * Since: 2.14 */ @@ -3914,7 +3947,7 @@ * Hints the compiler that the expression is likely to evaluate to * a true value. The compiler may use this information for optimizations. * - * |[ + * |[<!-- language="C" --> * if (G_LIKELY (random () != 1)) * g_print ("not one"); * ]| @@ -3959,19 +3992,17 @@ * G_LOCK_DEFINE: * @name: the name of the lock * - * The <literal>G_LOCK_*</literal> macros provide a convenient interface to #GMutex. + * The #G_LOCK_ macros provide a convenient interface to #GMutex. * #G_LOCK_DEFINE defines a lock. It can appear in any place where * variable definitions may appear in programs, i.e. in the first block * of a function or outside of functions. The @name parameter will be * mangled to get the name of the #GMutex. This means that you * can use names of existing variables as the parameter - e.g. the name * of the variable you intend to protect with the lock. Look at our - * <function>give_me_next_number()</function> example using the - * <literal>G_LOCK_*</literal> macros: + * give_me_next_number() example using the #G_LOCK macros: * - * <example> - * <title>Using the <literal>G_LOCK_*</literal> convenience macros</title> - * <programlisting> + * Here is an example for using the #G_LOCK convenience macros: + * |[<!-- language="C" --> * G_LOCK_DEFINE (current_number); * * int @@ -3986,8 +4017,7 @@ * * return ret_val; * } - * </programlisting> - * </example> + * ]| */ @@ -4195,7 +4225,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. */ @@ -4205,7 +4235,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. */ @@ -4296,7 +4326,7 @@ * * A #GOnce must be initialized with this macro before it can be used. * - * |[ + * |[<!-- language="C" --> * GOnce my_once = G_ONCE_INIT; * ]| * @@ -4326,10 +4356,10 @@ * @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: - * |[ + * |[<!-- language="C" --> * #define GET(traveller,method) G_PASTE(traveller_get_, method) (traveller) * const gchar *name = GET (traveller, name); * const gchar *quest = GET (traveller, quest); @@ -4337,7 +4367,7 @@ * ]| * * is transformed by the preprocessor into: - * |[ + * |[<!-- language="C" --> * const gchar *name = traveller_get_name (traveller); * const gchar *quest = traveller_get_quest (traveller); * GdkColor *favourite = traveller_get_favourite_colour (traveller); @@ -4395,10 +4425,10 @@ * be properly initialised by default (ie: to all zeros). See the * examples below. * - * |[ + * |[<!-- language="C" --> * static GPrivate name_key = G_PRIVATE_INIT (g_free); * - * // return value should not be freed + * /* return value should not be freed */ * const gchar * * get_local_name (void) * { @@ -4412,7 +4442,7 @@ * } * * - * static GPrivate count_key; // no free function + * static GPrivate count_key; /* no free function */ * * gint * get_local_count (void) @@ -4467,18 +4497,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. * @@ -4490,17 +4516,16 @@ * G_STATIC_ASSERT_EXPR: * @expr: a constant expression * - * The G_STATIC_ASSERT_EXPR macro lets the programmer check + * The G_STATIC_ASSERT_EXPR() macro lets the programmer check * a condition at compile time. The condition needs to be * compile time computable. * - * Unlike <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. * - * |[ + * |[<!-- language="C" --> * #define ADD_ONE_TO_INT(x) \ * (G_STATIC_ASSERT_EXPR(sizeof (x) == sizeof (int)), ((x) + 1)) * ]| @@ -4541,14 +4566,14 @@ * Accepts a macro or a string and converts it into a string after * preprocessor argument expansion. For example, the following code: * - * |[ + * |[<!-- language="C" --> * #define AGE 27 * const gchar *greeting = G_STRINGIFY (AGE) " today!"; * ]| * * is transformed by the preprocessor into (code equivalent to): * - * |[ + * |[<!-- language="C" --> * const gchar *greeting = "27 today!"; * ]| */ @@ -4587,8 +4612,8 @@ /** * G_STRUCT_OFFSET: - * @struct_type: a structure type, e.g. <structname>GtkWidget</structname> - * @member: a field in the structure, e.g. <structfield>window</structfield> + * @struct_type: a structure type, e.g. #GtkWidget + * @member: a field in the structure, e.g. @window * * Returns the offset, in bytes, of a member of a struct. * @@ -4641,7 +4666,7 @@ * Hints the compiler that the expression is unlikely to evaluate to * a true value. The compiler may use this information for optimizations. * - * |[ + * |[<!-- language="C" --> * if (G_UNLIKELY (random () == 1)) * g_print ("a random one"); * ]| @@ -4679,15 +4704,14 @@ /** * G_VA_COPY: - * @ap1: the <type>va_list</type> variable to place a copy of @ap2 in - * @ap2: a <type>va_list</type> + * @ap1: the va_list variable to place a copy of @ap2 in + * @ap2: a va_list * - * Portable way to copy <type>va_list</type> variables. + * Portable way to copy va_list variables. * - * In order to use this function, you must include - * <filename>string.h</filename> yourself, because this macro may - * use memmove() and GLib does not include <filename>string.h</filename> - * for you. + * In order to use this function, you must include string.h yourself, + * because this macro may use memmove() and GLib does not include + * string.h for you. */ @@ -4696,8 +4720,8 @@ * @static: empty or "static" * @dll_name: the name of the (pointer to the) char array where * the DLL name will be stored. If this is used, you must also - * include <filename>windows.h</filename>. If you need a more - * complex DLL entry point function, you cannot use this + * include `windows.h`. If you need a more complex DLL entry + * point function, you cannot use this * * On Windows, this macro defines a DllMain() function that stores * the actual DLL name that the code being compiled will be included in. @@ -4774,7 +4798,7 @@ * be directly used, e.g. in string array initializers. To get the * translated string, you should call g_dpgettext2() at runtime. * - * |[ + * |[<!-- language="C" --> * { * static const char *messages[] = { * NC_("some context", "some very meaningful message"), @@ -4783,19 +4807,18 @@ * const char *string; * ... * string - * = index > 1 ? g_dpgettext2 (NULL, "some context", "a default message") - * : g_dpgettext2 (NULL, "some context", messages[index]); + * = index > 1 ? g_dpgettext2 (NULL, "some context", "a default message") + * : g_dpgettext2 (NULL, "some context", messages[index]); * * fputs (string); * ... * } * ]| * - * <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 + * `--keyword=NC_:1c,2` 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 */ @@ -4816,7 +4839,7 @@ * where the translated strings can't be directly used, e.g. in string * array initializers. To get the translated string, call gettext() * at runtime. - * |[ + * |[<!-- language="C" --> * { * static const char *messages[] = { * N_("some very meaningful message"), @@ -4855,11 +4878,11 @@ * 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 - * <option>--keyword=Q_:1g</option> to let xgettext split the context - * string off into a msgctxt line in the po file.</para></note> + * If you are using the Q_() macro, you need to make sure that you pass + * `--keyword=Q_` to xgettext when extracting messages. + * If you are using GNU gettext >= 0.15, you can also use + * `--keyword=Q_:1g` to let xgettext split the context + * string off into a msgctxt line in the po file. * * Returns: the translated message * Since: 2.4 @@ -4870,7 +4893,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. @@ -4891,23 +4914,22 @@ * * To free an array, use g_array_free(). * - * <example> - * <title>Using a #GArray to store #gint values</title> - * <programlisting> + * Here is an example that stores integers in a #GArray: + * |[<!-- language="C" --> * GArray *garray; * gint i; - * /<!-- -->* We create a new array to store gint values. - * We don't want it zero-terminated or cleared to 0's. *<!-- -->/ + * /* We create a new array to store gint values. + * * We don't want it zero-terminated or cleared to 0's. + * */ * garray = g_array_new (FALSE, FALSE, sizeof (gint)); - * for (i = 0; i < 10000; i++) + * for (i = 0; i < 10000; i++) * g_array_append_val (garray, i); - * for (i = 0; i < 10000; i++) + * for (i = 0; i < 10000; i++) * if (g_array_index (garray, gint, i) != i) - * g_print ("ERROR: got %d instead of %d\n", + * g_print ("ERROR: got %d instead of %d\n", * g_array_index (garray, gint, i), i); * g_array_free (garray, TRUE); - * </programlisting> - * </example> + * ]| */ @@ -4926,17 +4948,16 @@ * * To free a #GByteArray, use g_byte_array_free(). * - * <example> - * <title>Using a #GByteArray</title> - * <programlisting> + * An example for using a #GByteArray: + * |[<!-- language="C" --> * GByteArray *gbarray; * gint i; * - * gbarray = g_byte_array_new (<!-- -->); - * for (i = 0; i < 10000; i++) + * gbarray = g_byte_array_new (); + * for (i = 0; i < 10000; i++) * g_byte_array_append (gbarray, (guint8*) "abcd", 4); * - * for (i = 0; i < 10000; i++) + * for (i = 0; i < 10000; i++) * { * g_assert (gbarray->data[4*i] == 'a'); * g_assert (gbarray->data[4*i+1] == 'b'); @@ -4945,8 +4966,7 @@ * } * * g_byte_array_free (gbarray, TRUE); - * </programlisting> - * </example> + * ]| * * See #GBytes if you are interested in an immutable object representing a * sequence of bytes. @@ -4957,16 +4977,16 @@ * 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(). * @@ -4981,24 +5001,22 @@ * * To free a pointer array, use g_ptr_array_free(). * - * <example> - * <title>Using a #GPtrArray</title> - * <programlisting> - * GPtrArray *gparray; + * An example using a #GPtrArray: + * |[<!-- language="C" --> + * GPtrArray *array; * gchar *string1 = "one", *string2 = "two", *string3 = "three"; * - * gparray = g_ptr_array_new (<!-- -->); - * g_ptr_array_add (gparray, (gpointer) string1); - * g_ptr_array_add (gparray, (gpointer) string2); - * g_ptr_array_add (gparray, (gpointer) string3); + * gparray = g_ptr_array_new (); + * g_ptr_array_add (array, (gpointer) string1); + * g_ptr_array_add (array, (gpointer) string2); + * g_ptr_array_add (array, (gpointer) string3); * - * if (g_ptr_array_index (gparray, 0) != (gpointer) string1) - * g_print ("ERROR: got %p instead of %p\n", - * g_ptr_array_index (gparray, 0), string1); + * if (g_ptr_array_index (array, 0) != (gpointer) string1) + * g_print ("ERROR: got %p instead of %p\n", + * g_ptr_array_index (array, 0), string1); * - * g_ptr_array_free (gparray, TRUE); - * </programlisting> - * </example> + * g_ptr_array_free (array, TRUE); + * ]| */ @@ -5089,8 +5107,7 @@ * fall outside of simple reference counting patterns are prone to * subtle bugs and occasionally undefined behaviour. It is also worth * noting that since all of these operations require global - * synchronisation of the entire machine, they can be quite slow. In - * the case of performing multiple atomic operations it can often be + * synchronisation of the entire machine, they can be quite slow. In * the case of performing multiple atomic operations it can often be * faster to simply acquire a mutex lock around the critical area, * perform the operations normally and then release the lock. */ @@ -5103,9 +5120,11 @@ * * Base64 is an encoding that allows a sequence of arbitrary bytes to be * encoded as a sequence of printable ASCII characters. For the definition - * of Base64, see <ulink url="http://www.ietf.org/rfc/rfc1421.txt">RFC - * 1421</ulink> or <ulink url="http://www.ietf.org/rfc/rfc2045.txt">RFC - * 2045</ulink>. Base64 is most commonly used as a MIME transfer encoding + * of Base64, see + * [RFC 1421](http://www.ietf.org/rfc/rfc1421.txt) + * or + * [RFC 2045](http://www.ietf.org/rfc/rfc2045.txt). + * Base64 is most commonly used as a MIME transfer encoding * for email. * * GLib supports incremental encoding using g_base64_encode_step() and @@ -5128,26 +5147,27 @@ * like its MIME type, the application that is registering the bookmark and * the icon that should be used to represent the bookmark. The data is stored * using the - * <ulink url="http://www.gnome.org/~ebassi/bookmark-spec">Desktop Bookmark - * Specification</ulink>. + * [Desktop Bookmark Specification](http://www.gnome.org/~ebassi/bookmark-spec). * - * The syntax of the bookmark files is described in detail inside the Desktop - * Bookmark Specification, here is a quick summary: bookmark files use a - * sub-class of the <ulink url="">XML Bookmark Exchange Language</ulink> + * The syntax of the bookmark files is described in detail inside the + * Desktop Bookmark Specification, here is a quick summary: bookmark + * files use a sub-class of the XML Bookmark Exchange Language * specification, consisting of valid UTF-8 encoded XML, under the - * <literal>xbel</literal> root element; each bookmark is stored inside a - * <literal>bookmark</literal> element, using its URI: no relative paths can - * be used inside a bookmark file. The bookmark may have a user defined title - * and description, to be used instead of the URI. Under the - * <literal>metadata</literal> element, with its <literal>owner</literal> - * attribute set to <literal>http://freedesktop.org</literal>, is stored the - * meta-data about a resource pointed by its URI. The meta-data consists of - * the resource's MIME type; the applications that have registered a bookmark; - * the groups to which a bookmark belongs to; a visibility flag, used to set - * the bookmark as "private" to the applications and groups that has it - * registered; the URI and MIME type of an icon, to be used when displaying - * the bookmark inside a GUI. - * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../glib/tests/bookmarks.xbel"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]| + * <xbel> root element; each bookmark is stored inside a + * <bookmark> element, using its URI: no relative paths can + * be used inside a bookmark file. The bookmark may have a user defined + * title and description, to be used instead of the URI. Under the + * <metadata> element, with its owner attribute set to + * `http://freedesktop.org`, is stored the meta-data about a resource + * pointed by its URI. The meta-data consists of the resource's MIME + * type; the applications that have registered a bookmark; the groups + * to which a bookmark belongs to; a visibility flag, used to set the + * bookmark as "private" to the applications and groups that has it + * registered; the URI and MIME type of an icon, to be used when + * displaying the bookmark inside a GUI. + * + * Here is an example of a bookmark file: + * [bookmarks.xbel](https://git.gnome.org/browse/glib/tree/glib/tests/bookmarks.xbel) * * A bookmark file might contain more than one bookmark; each bookmark * is accessed through its URI. @@ -5227,120 +5247,100 @@ * @title: Character Set Conversion * @short_description: convert strings between different character sets * - * The g_convert() family of function wraps the functionality of iconv(). In - * addition to pure character set conversions, GLib has functions to deal - * with the extra complications of encodings for file names. - * - * <refsect2 id="file-name-encodings"> - * <title>File Name Encodings</title> - * <para> - * Historically, Unix has not had a defined encoding for file - * names: a file name is valid as long as it does not have path - * separators in it ("/"). However, displaying file names may - * require conversion: from the character set in which they were - * created, to the character set in which the application - * operates. Consider the Spanish file name - * "<filename>Presentación.sxi</filename>". If the - * application which created it uses ISO-8859-1 for its encoding, - * </para> - * <programlisting id="filename-iso8859-1"> + * The g_convert() family of function wraps the functionality of iconv(). + * In addition to pure character set conversions, GLib has functions to + * deal with the extra complications of encodings for file names. + * + * ## File Name Encodings + * + * Historically, UNIX has not had a defined encoding for file names: + * a file name is valid as long as it does not have path separators + * in it ("/"). However, displaying file names may require conversion: + * from the character set in which they were created, to the character + * set in which the application operates. Consider the Spanish file name + * "Presentación.sxi". If the application which created it uses + * ISO-8859-1 for its encoding, + * <programlisting> * Character: P r e s e n t a c i ó n . s x i * Hex code: 50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69 * </programlisting> - * <para> * However, if the application use UTF-8, the actual file name on * disk would look like this: - * </para> * <programlisting id="filename-utf-8"> * Character: P r e s e n t a c i ó n . s x i * Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69 * </programlisting> - * <para> - * Glib uses UTF-8 for its strings, and GUI toolkits like GTK+ - * that use Glib do the same thing. If you get a file name from - * the file system, for example, from readdir(3) or from g_dir_read_name(), - * and you wish to display the file name to the user, you - * <emphasis>will</emphasis> need to convert it into UTF-8. The - * opposite case is when the user types the name of a file he - * wishes to save: the toolkit will give you that string in - * UTF-8 encoding, and you will need to convert it to the - * character set used for file names before you can create the - * file with open(2) or fopen(3). - * </para> - * <para> + * Glib uses UTF-8 for its strings, and GUI toolkits like GTK+ that use + * Glib do the same thing. If you get a file name from the file system, + * for example, from readdir() or from g_dir_read_name(), and you wish + * to display the file name to the user, you will need to convert it + * into UTF-8. The opposite case is when the user types the name of a + * file he wishes to save: the toolkit will give you that string in + * UTF-8 encoding, and you will need to convert it to the character + * set used for file names before you can create the file with open() + * or fopen(). + * * By default, Glib assumes that file names on disk are in UTF-8 - * encoding. This is a valid assumption for file systems which - * were created relatively recently: most applications use UTF-8 + * encoding. This is a valid assumption for file systems which + * were created relatively recently: most applications use UTF-8 * encoding for their strings, and that is also what they use for - * the file names they create. However, older file systems may + * the file names they create. However, older file systems may * still contain file names created in "older" encodings, such as * ISO-8859-1. In this case, for compatibility reasons, you may * want to instruct Glib to use that particular encoding for file - * names rather than UTF-8. You can do this by specifying the + * names rather than UTF-8. You can do this by specifying the * encoding for file names in the <link - * linkend="G_FILENAME_ENCODING"><envar>G_FILENAME_ENCODING</envar></link> - * environment variable. For example, if your installation uses - * ISO-8859-1 for file names, you can put this in your - * <filename>~/.profile</filename>: - * </para> + * linkend="G_FILENAME_ENCODING">`G_FILENAME_ENCODING`</link> + * environment variable. For example, if your installation uses + * ISO-8859-1 for file names, you can put this in your `~/.profile` * <programlisting> * export G_FILENAME_ENCODING=ISO-8859-1 * </programlisting> - * <para> * Glib provides the functions g_filename_to_utf8() and - * g_filename_from_utf8() to perform the necessary conversions. These - * functions convert file names from the encoding specified in - * <envar>G_FILENAME_ENCODING</envar> to UTF-8 and vice-versa. + * g_filename_from_utf8() to perform the necessary conversions. + * These functions convert file names from the encoding specified + * in `G_FILENAME_ENCODING` to UTF-8 and vice-versa. * <xref linkend="file-name-encodings-diagram"/> illustrates how * these functions are used to convert between UTF-8 and the * encoding for file names in the file system. - * </para> - * <figure id="file-name-encodings-diagram"> - * <title>Conversion between File Name Encodings</title> - * <graphic fileref="file-name-encodings.png" format="PNG"/> - * </figure> - * <refsect3 id="file-name-encodings-checklist"> - * <title>Checklist for Application Writers</title> - * <para> + * + * ## Conversion between file name encodings # {#file-name-encodings-diagram) + * + *  + * + * ## Checklist for Application Writers + * * This section is a practical summary of the detailed - * description above. You can use this as a checklist of + * * things to do to make sure your applications process file * name encodings correctly. - * </para> - * <orderedlist> - * <listitem><para> - * If you get a file name from the file system from a function - * such as readdir(3) or gtk_file_chooser_get_filename(), - * you do not need to do any conversion to pass that - * file name to functions like open(2), rename(2), or - * fopen(3) — those are "raw" file names which the file - * system understands. - * </para></listitem> - * <listitem><para> - * If you need to display a file name, convert it to UTF-8 first by - * using g_filename_to_utf8(). If conversion fails, display a string like - * "<literal>Unknown file name</literal>". <emphasis>Do not</emphasis> - * convert this string back into the encoding used for file names if you - * wish to pass it to the file system; use the original file name instead. - * For example, the document window of a word processor could display - * "Unknown file name" in its title bar but still let the user save the - * file, as it would keep the raw file name internally. This can happen - * if the user has not set the <envar>G_FILENAME_ENCODING</envar> - * environment variable even though he has files whose names are not - * encoded in UTF-8. - * </para></listitem> - * <listitem><para> - * If your user interface lets the user type a file name for saving or - * renaming, convert it to the encoding used for file names in the file - * system by using g_filename_from_utf8(). Pass the converted file name - * to functions like fopen(3). If conversion fails, ask the user to enter - * a different file name. This can happen if the user types Japanese - * characters when <envar>G_FILENAME_ENCODING</envar> is set to - * <literal>ISO-8859-1</literal>, for example. - * </para></listitem> - * </orderedlist> - * </refsect3> - * </refsect2> + * + * 1. If you get a file name from the file system from a function + * such as readdir() or gtk_file_chooser_get_filename(), you do + * not need to do any conversion to pass that file name to + * functions like open(), rename(), or fopen() -- those are "raw" + * file names which the file system understands. + * + * 2. If you need to display a file name, convert it to UTF-8 first + * by using g_filename_to_utf8(). If conversion fails, display a + * string like "Unknown file name". Do not convert this string back + * into the encoding used for file names if you wish to pass it to + * the file system; use the original file name instead. + * + * For example, the document window of a word processor could display + * "Unknown file name" in its title bar but still let the user save + * the file, as it would keep the raw file name internally. This + * can happen if the user has not set the `G_FILENAME_ENCODING` + * environment variable even though he has files whose names are + * not encoded in UTF-8. + * + * 3. If your user interface lets the user type a file name for saving + * or renaming, convert it to the encoding used for file names in + * the file system by using g_filename_from_utf8(). Pass the converted + * file name to functions like fopen(). If conversion fails, ask the + * user to enter a different file name. This can happen if the user + * types Japanese characters when `G_FILENAME_ENCODING` is set to + * `ISO-8859-1`, for example. */ @@ -5432,7 +5432,7 @@ * or ISO timestamps or the like. It extrapolates the current Gregorian * calendar forward and backward in time; there is no attempt to change * the calendar to match time periods or locations. #GDate does not store - * time information; it represents a <emphasis>day</emphasis>. + * time information; it represents a day. * * The #GDate implementation has several nice features; it is only a * 64-bit struct, so storing large numbers of dates is very efficient. It @@ -5450,16 +5450,16 @@ * calling g_date_clear(). A cleared date is sane; it's safe to call * g_date_set_dmy() and the other mutator functions to initialize the * value of a cleared date. However, a cleared date is initially - * <emphasis>invalid</emphasis>, meaning that it doesn't represent a day - * that exists. It is undefined to call any of the date calculation - * routines on an invalid date. If you obtain a date from a user or other + * invalid, meaning that it doesn't represent a day that exists. + * It is undefined to call any of the date calculation routines on an + * invalid date. If you obtain a date from a user or other * unpredictable source, you should check its validity with the * g_date_valid() predicate. g_date_valid() is also used to check for * errors with g_date_set_parse() and other functions that can * fail. Dates can be invalidated by calling g_date_clear() again. * - * <emphasis>It is very important to use the API to access the #GDate - * struct.</emphasis> Often only the day-month-year or only the Julian + * It is very important to use the API to access the #GDate + * struct. Often only the day-month-year or only the Julian * representation is valid. Sometimes neither is valid. Use the API. * * GLib also features #GDateTime which represents a precise time. @@ -5508,18 +5508,18 @@ * GLib provides a standard method of reporting errors from a called * function to the calling code. (This is the same problem solved by * exceptions in other languages.) It's important to understand that - * this method is both a <emphasis>data type</emphasis> (the #GError - * object) and a <emphasis>set of rules.</emphasis> If you use #GError - * incorrectly, then your code will not properly interoperate with other - * code that uses #GError, and users of your API will probably get confused. - * - * First and foremost: <emphasis>#GError should only be used to report - * recoverable runtime errors, never to report programming - * errors.</emphasis> If the programmer has screwed up, then you should - * use g_warning(), g_return_if_fail(), g_assert(), g_error(), or some - * similar facility. (Incidentally, remember that the g_error() function - * should <emphasis>only</emphasis> be used for programming errors, it - * should not be used to print any error reportable via #GError.) + * this method is both a data type (the #GError struct) and a set of + * rules. If you use #GError incorrectly, then your code will not + * properly interoperate with other code that uses #GError, and users + * of your API will probably get confused. + * + * First and foremost: #GError should only be used to report recoverable + * runtime errors, never to report programming errors. If the programmer + * has screwed up, then you should use g_warning(), g_return_if_fail(), + * g_assert(), g_error(), or some similar facility. (Incidentally, + * remember that the g_error() function should only be used for + * programming errors, it should not be used to print any error + * reportable via #GError.) * * Examples of recoverable runtime errors are "file not found" or * "failed to parse input." Examples of programming errors are "NULL @@ -5531,25 +5531,25 @@ * * Functions that can fail take a return location for a #GError as their * last argument. For example: - * |[ + * |[<!-- language="C" --> * gboolean g_file_get_contents (const gchar *filename, * gchar **contents, * gsize *length, * GError **error); * ]| - * If you pass a non-%NULL value for the <literal>error</literal> - * argument, it should point to a location where an error can be placed. - * For example: - * |[ + * If you pass a non-%NULL value for the `error` argument, it should + * point to a location where an error can be placed. For example: + * |[<!-- language="C" --> * gchar *contents; * GError *err = NULL; - * g_file_get_contents ("foo.txt", &contents, NULL, &err); - * g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL)); + * + * g_file_get_contents ("foo.txt", &contents, NULL, &err); + * g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL)); * if (err != NULL) * { * /* Report error to user, and free error */ * g_assert (contents == NULL); - * fprintf (stderr, "Unable to read file: %s\n", err->message); + * fprintf (stderr, "Unable to read file: %s\n", err->message); * g_error_free (err); * } * else @@ -5558,44 +5558,41 @@ * g_assert (contents != NULL); * } * ]| - * Note that <literal>err != NULL</literal> in this example is a - * <emphasis>reliable</emphasis> indicator of whether - * g_file_get_contents() failed. Additionally, g_file_get_contents() - * returns a boolean which indicates whether it was successful. + * Note that `err != NULL` in this example is a reliable indicator + * of whether g_file_get_contents() failed. Additionally, + * g_file_get_contents() returns a boolean which + * indicates whether it was successful. * * Because g_file_get_contents() returns %FALSE on failure, if you * are only interested in whether it failed and don't need to display - * an error message, you can pass %NULL for the <literal>error</literal> - * argument: - * |[ - * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) /* ignore errors */ + * an error message, you can pass %NULL for the @error argument: + * |[<!-- language="C" --> + * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) /* ignore errors */ * /* no error occurred */ ; * else * /* error */ ; * ]| * - * The #GError object contains three fields: <literal>domain</literal> - * indicates the module the error-reporting function is located in, - * <literal>code</literal> indicates the specific error that occurred, - * and <literal>message</literal> is a user-readable error message with + * The #GError object contains three fields: @domain indicates the module + * the error-reporting function is located in, @code indicates the specific + * error that occurred, and @message is a user-readable error message with * as many details as possible. Several functions are provided to deal * with an error received from a called function: g_error_matches() * returns %TRUE if the error matches a given domain and code, * g_propagate_error() copies an error into an error location (so the * calling function will receive it), and g_clear_error() clears an * error location by freeing the error and resetting the location to - * %NULL. To display an error to the user, simply display - * <literal>error->message</literal>, perhaps along with additional - * context known only to the calling function (the file being opened, - * or whatever -- though in the g_file_get_contents() case, - * <literal>error->message</literal> already contains a filename). + * %NULL. To display an error to the user, simply display the @message, + * perhaps along with additional context known only to the calling + * function (the file being opened, or whatever - though in the + * g_file_get_contents() case, the @message already contains a filename). * * When implementing a function that can report errors, the basic * tool is g_set_error(). Typically, if a fatal error occurs you * want to g_set_error(), then return immediately. g_set_error() * does nothing if the error location passed to it is %NULL. * Here's an example: - * |[ + * |[<!-- language="C" --> * gint * foo_open_file (GError **error) * { @@ -5603,12 +5600,12 @@ * * fd = open ("file.txt", O_RDONLY); * - * if (fd < 0) + * if (fd < 0) * { * g_set_error (error, * FOO_ERROR, /* error domain */ * FOO_ERROR_BLAH, /* error code */ - * "Failed to open file: %s", /* error message format string */ + * "Failed to open file: %s", /* error message format string */ * g_strerror (errno)); * return -1; * } @@ -5621,7 +5618,7 @@ * function that can report a #GError. If the sub-function indicates * fatal errors in some way other than reporting a #GError, such as * by returning %TRUE on success, you can simply do the following: - * |[ + * |[<!-- language="C" --> * gboolean * my_function_that_can_fail (GError **err) * { @@ -5643,7 +5640,7 @@ * reporting a #GError, you need to create a temporary #GError * since the passed-in one may be %NULL. g_propagate_error() is * intended for use in this case. - * |[ + * |[<!-- language="C" --> * gboolean * my_function_that_can_fail (GError **err) * { @@ -5652,7 +5649,7 @@ * g_return_val_if_fail (err == NULL || *err == NULL, FALSE); * * tmp_error = NULL; - * sub_function_that_can_fail (&tmp_error); + * sub_function_that_can_fail (&tmp_error); * * if (tmp_error != NULL) * { @@ -5668,7 +5665,7 @@ * ]| * * Error pileups are always a bug. For example, this code is incorrect: - * |[ + * |[<!-- language="C" --> * gboolean * my_function_that_can_fail (GError **err) * { @@ -5677,8 +5674,8 @@ * g_return_val_if_fail (err == NULL || *err == NULL, FALSE); * * tmp_error = NULL; - * sub_function_that_can_fail (&tmp_error); - * other_function_that_can_fail (&tmp_error); + * sub_function_that_can_fail (&tmp_error); + * other_function_that_can_fail (&tmp_error); * * if (tmp_error != NULL) * { @@ -5687,15 +5684,15 @@ * } * } * ]| - * <literal>tmp_error</literal> should be checked immediately after - * sub_function_that_can_fail(), and either cleared or propagated - * upward. The rule is: <emphasis>after each error, you must either - * handle the error, or return it to the calling function</emphasis>. + * @tmp_error should be checked immediately after sub_function_that_can_fail(), + * and either cleared or propagated upward. The rule is: after each error, + * you must either handle the error, or return it to the calling function. + * * Note that passing %NULL for the error location is the equivalent * of handling an error by always doing nothing about it. So the * following code is fine, assuming errors in sub_function_that_can_fail() * are not fatal to my_function_that_can_fail(): - * |[ + * |[<!-- language="C" --> * gboolean * my_function_that_can_fail (GError **err) * { @@ -5706,7 +5703,7 @@ * sub_function_that_can_fail (NULL); /* ignore errors */ * * tmp_error = NULL; - * other_function_that_can_fail (&tmp_error); + * other_function_that_can_fail (&tmp_error); * * if (tmp_error != NULL) * { @@ -5716,116 +5713,93 @@ * } * ]| * - * Note that passing %NULL for the error location - * <emphasis>ignores</emphasis> errors; it's equivalent to - * <literal>try { sub_function_that_can_fail (); } catch (...) {}</literal> - * in C++. It does <emphasis>not</emphasis> mean to leave errors - * unhandled; it means to handle them by doing nothing. + * Note that passing %NULL for the error location ignores errors; + * it's equivalent to + * `try { sub_function_that_can_fail (); } catch (...) {}` + * in C++. It does not mean to leave errors unhandled; it means + * to handle them by doing nothing. * * Error domains and codes are conventionally named as follows: - * <itemizedlist> - * <listitem><para> - * The error domain is called - * <literal><NAMESPACE>_<MODULE>_ERROR</literal>, + * + * - The error domain is called <NAMESPACE>_<MODULE>_ERROR, * for example %G_SPAWN_ERROR or %G_THREAD_ERROR: - * |[ - * #define G_SPAWN_ERROR g_spawn_error_quark () + * |[<!-- language="C" --> + * #define G_SPAWN_ERROR g_spawn_error_quark () * - * GQuark - * g_spawn_error_quark (void) - * { - * return g_quark_from_static_string ("g-spawn-error-quark"); - * } + * GQuark + * g_spawn_error_quark (void) + * { + * return g_quark_from_static_string ("g-spawn-error-quark"); + * } * ]| - * </para></listitem> - * <listitem><para> - * The quark function for the error domain is called - * <literal><namespace>_<module>_error_quark</literal>, + * + * - The quark function for the error domain is called + * <namespace>_<module>_error_quark, * for example g_spawn_error_quark() or g_thread_error_quark(). - * </para></listitem> - * <listitem><para> - * The error codes are in an enumeration called - * <literal><Namespace><Module>Error</literal>; + * + * - The error codes are in an enumeration called + * <Namespace><Module>Error; * for example,#GThreadError or #GSpawnError. - * </para></listitem> - * <listitem><para> - * Members of the error code enumeration are called - * <literal><NAMESPACE>_<MODULE>_ERROR_<CODE></literal>, + * + * - Members of the error code enumeration are called + * <NAMESPACE>_<MODULE>_ERROR_<CODE>, * for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN. - * </para></listitem> - * <listitem><para> - * If there's a "generic" or "unknown" error code for unrecoverable + * + * - If there's a "generic" or "unknown" error code for unrecoverable * errors it doesn't make sense to distinguish with specific codes, - * it should be called <literal><NAMESPACE>_<MODULE>_ERROR_FAILED</literal>, + * it should be called <NAMESPACE>_<MODULE>_ERROR_FAILED, * for example %G_SPAWN_ERROR_FAILED. - * </para></listitem> - * </itemizedlist> * * Summary of rules for use of #GError: - * <itemizedlist> - * <listitem><para> - * Do not report programming errors via #GError. - * </para></listitem> - * <listitem><para> - * The last argument of a function that returns an error should + * + * - Do not report programming errors via #GError. + * + * - The last argument of a function that returns an error should * be a location where a #GError can be placed (i.e. "#GError** error"). * If #GError is used with varargs, the #GError** should be the last * argument before the "...". - * </para></listitem> - * <listitem><para> - * The caller may pass %NULL for the #GError** if they are not interested + * + * - The caller may pass %NULL for the #GError** if they are not interested * in details of the exact error that occurred. - * </para></listitem> - * <listitem><para> - * If %NULL is passed for the #GError** argument, then errors should + * + * - If %NULL is passed for the #GError** argument, then errors should * not be returned to the caller, but your function should still * abort and return if an error occurs. That is, control flow should * not be affected by whether the caller wants to get a #GError. - * </para></listitem> - * <listitem><para> - * If a #GError is reported, then your function by definition - * <emphasis>had a fatal failure and did not complete whatever - * it was supposed to do</emphasis>. If the failure was not fatal, - * then you handled it and you should not report it. If it was fatal, - * then you must report it and discontinue whatever you were doing - * immediately. - * </para></listitem> - * <listitem><para> - * If a #GError is reported, out parameters are not guaranteed to + * + * - If a #GError is reported, then your function by definition had a + * fatal failure and did not complete whatever it was supposed to do. + * If the failure was not fatal, then you handled it and you should not + * report it. If it was fatal, then you must report it and discontinue + * whatever you were doing immediately. + * + * - If a #GError is reported, out parameters are not guaranteed to * be set to any defined value. - * </para></listitem> - * <listitem><para> - * A #GError* must be initialized to %NULL before passing its address + * + * - A #GError* must be initialized to %NULL before passing its address * to a function that can report errors. - * </para></listitem> - * <listitem><para> - * "Piling up" errors is always a bug. That is, if you assign a + * + * - "Piling up" errors is always a bug. That is, if you assign a * new #GError to a #GError* that is non-%NULL, thus overwriting * the previous error, it indicates that you should have aborted * the operation instead of continuing. If you were able to continue, * you should have cleared the previous error with g_clear_error(). * g_set_error() will complain if you pile up errors. - * </para></listitem> - * <listitem><para> - * By convention, if you return a boolean value indicating success + * + * - By convention, if you return a boolean value indicating success * then %TRUE means success and %FALSE means failure. If %FALSE is - * returned, the error <emphasis>must</emphasis> be set to a non-%NULL - * value. - * </para></listitem> - * <listitem><para> - * A %NULL return value is also frequently used to mean that an error + * returned, the error must be set to a non-%NULL value. + * + * - A %NULL return value is also frequently used to mean that an error * occurred. You should make clear in your documentation whether %NULL * is a valid return value in non-error cases; if %NULL is a valid value, * then users must check whether an error was returned to see if the * function succeeded. - * </para></listitem> - * <listitem><para> - * When implementing a function that can report errors, you may want + * + * - When implementing a function that can report errors, you may want * to add a check at the top of your function that the error return * location is either %NULL or contains a %NULL error (e.g. - * <literal>g_return_if_fail (error == NULL || *error == NULL);</literal>). - * </para></listitem> - * </itemizedlist> + * `g_return_if_fail (error == NULL || *error == NULL);`). */ @@ -5843,8 +5817,8 @@ * * The pathname argument should be in the GLib file name encoding. * On POSIX this is the actual on-disk encoding which might correspond - * to the locale settings of the process (or the - * <envar>G_FILENAME_ENCODING</envar> environment variable), or not. + * to the locale settings of the process (or the `G_FILENAME_ENCODING` + * environment variable), or not. * * On Windows the GLib file name encoding is UTF-8. Note that the * Microsoft C library does not use UTF-8, but has separate APIs for @@ -5866,9 +5840,9 @@ * converting between Unicode and ASCII-encoded forms of * Internationalized Domain Names (IDNs). * - * The <ulink - * url="http://www.ietf.org/rfc/rfc3490.txt">Internationalized Domain - * Names for Applications (IDNA)</ulink> standards allow for the use + * The + * [Internationalized Domain Names for Applications (IDNA)](http://www.ietf.org/rfc/rfc3490.txt) + * standards allow for the use * of Unicode domain names in applications, while providing * backward-compatibility with the old ASCII-only DNS, by defining an * ASCII-Compatible Encoding of any given Unicode name, which can be @@ -5883,7 +5857,7 @@ * @short_description: matches strings against regular expressions * @see_also: <xref linkend="glib-regex-syntax"/> * - * The <function>g_regex_*()</function> functions implement regular + * The g_regex_*() functions implement regular * expression pattern matching using syntax and semantics similar to * Perl regular expression. * @@ -5937,7 +5911,7 @@ * '\U' always matches 'U' instead of being an error in the pattern. Finally, * pattern matching is modified so that back references to an unset subpattern * group produces a match with the empty string instead of an error. See - * <ulink>man:pcreapi(3)</ulink> for more information. + * pcreapi(3) for more information. * * Creating and manipulating the same #GRegex structure from different * threads is not a problem as #GRegex does not modify its internal @@ -5945,8 +5919,9 @@ * is not threadsafe. * * The regular expressions low-level functionalities are obtained through - * the excellent <ulink url="http://www.pcre.org/">PCRE</ulink> library - * written by Philip Hazel. + * the excellent + * [PCRE](http://www.pcre.org/) + * library written by Philip Hazel. */ @@ -5972,8 +5947,9 @@ * @short_description: manipulating URIs * * Functions for manipulating Universal Resource Identifiers (URIs) as - * defined by <ulink url="http://www.ietf.org/rfc/rfc3986.txt"> - * RFC 3986</ulink>. It is highly recommended that you have read and + * defined by + * [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt). + * It is highly recommended that you have read and * understand RFC 3986 for understanding this API. */ @@ -6035,201 +6011,168 @@ * values. #GVariant includes a printer for this language and a parser * with type inferencing. * - * <refsect2> - * <title>Memory Use</title> - * <para> - * #GVariant tries to be quite efficient with respect to memory use. - * This section gives a rough idea of how much memory is used by the - * current implementation. The information here is subject to change - * in the future. - * </para> - * <para> - * The memory allocated by #GVariant can be grouped into 4 broad - * purposes: memory for serialised data, memory for the type - * information cache, buffer management memory and memory for the - * #GVariant structure itself. - * </para> - * <refsect3 id="gvariant-serialised-data-memory"> - * <title>Serialised Data Memory</title> - * <para> - * This is the memory that is used for storing GVariant data in - * serialised form. This is what would be sent over the network or - * what would end up on disk. - * </para> - * <para> - * The amount of memory required to store a boolean is 1 byte. 16, - * 32 and 64 bit integers and double precision floating point numbers - * use their "natural" size. Strings (including object path and - * signature strings) are stored with a nul terminator, and as such - * use the length of the string plus 1 byte. - * </para> - * <para> - * Maybe types use no space at all to represent the null value and - * use the same amount of space (sometimes plus one byte) as the - * equivalent non-maybe-typed value to represent the non-null case. - * </para> - * <para> - * Arrays use the amount of space required to store each of their - * members, concatenated. Additionally, if the items stored in an - * array are not of a fixed-size (ie: strings, other arrays, etc) - * then an additional framing offset is stored for each item. The - * size of this offset is either 1, 2 or 4 bytes depending on the - * overall size of the container. Additionally, extra padding bytes - * are added as required for alignment of child values. - * </para> - * <para> - * Tuples (including dictionary entries) use the amount of space - * required to store each of their members, concatenated, plus one - * framing offset (as per arrays) for each non-fixed-sized item in - * the tuple, except for the last one. Additionally, extra padding - * bytes are added as required for alignment of child values. - * </para> - * <para> - * Variants use the same amount of space as the item inside of the - * variant, plus 1 byte, plus the length of the type string for the - * item inside the variant. - * </para> - * <para> - * As an example, consider a dictionary mapping strings to variants. - * In the case that the dictionary is empty, 0 bytes are required for - * the serialisation. - * </para> - * <para> - * If we add an item "width" that maps to the int32 value of 500 then - * we will use 4 byte to store the int32 (so 6 for the variant - * containing it) and 6 bytes for the string. The variant must be - * aligned to 8 after the 6 bytes of the string, so that's 2 extra - * bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used - * for the dictionary entry. An additional 1 byte is added to the - * array as a framing offset making a total of 15 bytes. - * </para> - * <para> - * If we add another entry, "title" that maps to a nullable string - * that happens to have a value of null, then we use 0 bytes for the - * null value (and 3 bytes for the variant to contain it along with - * its type string) plus 6 bytes for the string. Again, we need 2 - * padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes. - * </para> - * <para> - * We now require extra padding between the two items in the array. - * After the 14 bytes of the first item, that's 2 bytes required. We - * now require 2 framing offsets for an extra two bytes. 14 + 2 + 11 - * + 2 = 29 bytes to encode the entire two-item dictionary. - * </para> - * </refsect3> - * <refsect3> - * <title>Type Information Cache</title> - * <para> - * For each GVariant type that currently exists in the program a type - * information structure is kept in the type information cache. The - * type information structure is required for rapid deserialisation. - * </para> - * <para> - * Continuing with the above example, if a #GVariant exists with the - * type "a{sv}" then a type information struct will exist for - * "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type - * will share the same type information. Additionally, all - * single-digit types are stored in read-only static memory and do - * not contribute to the writable memory footprint of a program using - * #GVariant. - * </para> - * <para> - * Aside from the type information structures stored in read-only - * memory, there are two forms of type information. One is used for - * container types where there is a single element type: arrays and - * maybe types. The other is used for container types where there - * are multiple element types: tuples and dictionary entries. - * </para> - * <para> - * Array type info structures are 6 * sizeof (void *), plus the - * memory required to store the type string itself. This means that - * on 32bit systems, the cache entry for "a{sv}" would require 30 - * bytes of memory (plus malloc overhead). - * </para> - * <para> - * Tuple type info structures are 6 * sizeof (void *), plus 4 * - * sizeof (void *) for each item in the tuple, plus the memory - * required to store the type string itself. A 2-item tuple, for - * example, would have a type information structure that consumed - * writable memory in the size of 14 * sizeof (void *) (plus type - * string) This means that on 32bit systems, the cache entry for - * "{sv}" would require 61 bytes of memory (plus malloc overhead). - * </para> - * <para> - * This means that in total, for our "a{sv}" example, 91 bytes of - * type information would be allocated. - * </para> - * <para> - * The type information cache, additionally, uses a #GHashTable to - * store and lookup the cached items and stores a pointer to this - * hash table in static storage. The hash table is freed when there - * are zero items in the type cache. - * </para> - * <para> - * Although these sizes may seem large it is important to remember - * that a program will probably only have a very small number of - * different types of values in it and that only one type information - * structure is required for many different values of the same type. - * </para> - * </refsect3> - * <refsect3> - * <title>Buffer Management Memory</title> - * <para> - * #GVariant uses an internal buffer management structure to deal - * with the various different possible sources of serialised data - * that it uses. The buffer is responsible for ensuring that the - * correct call is made when the data is no longer in use by - * #GVariant. This may involve a g_free() or a g_slice_free() or - * even g_mapped_file_unref(). - * </para> - * <para> - * One buffer management structure is used for each chunk of - * serialised data. The size of the buffer management structure is 4 - * * (void *). On 32bit systems, that's 16 bytes. - * </para> - * </refsect3> - * <refsect3> - * <title>GVariant structure</title> - * <para> - * The size of a #GVariant structure is 6 * (void *). On 32 bit - * systems, that's 24 bytes. - * </para> - * <para> - * #GVariant structures only exist if they are explicitly created - * with API calls. For example, if a #GVariant is constructed out of - * serialised data for the example given above (with the dictionary) - * then although there are 9 individual values that comprise the - * entire dictionary (two keys, two values, two variants containing - * the values, two dictionary entries, plus the dictionary itself), - * only 1 #GVariant instance exists -- the one referring to the - * dictionary. - * </para> - * <para> - * If calls are made to start accessing the other values then - * #GVariant instances will exist for those values only for as long - * as they are in use (ie: until you call g_variant_unref()). The - * type information is shared. The serialised data and the buffer - * management structure for that serialised data is shared by the - * child. - * </para> - * </refsect3> - * <refsect3> - * <title>Summary</title> - * <para> - * To put the entire example together, for our dictionary mapping - * strings to variants (with two entries, as given above), we are - * using 91 bytes of memory for type information, 29 byes of memory - * for the serialised data, 16 bytes for buffer management and 24 - * bytes for the #GVariant instance, or a total of 160 bytes, plus - * malloc overhead. If we were to use g_variant_get_child_value() to - * access the two dictionary entries, we would use an additional 48 - * bytes. If we were to have other dictionaries of the same type, we - * would use more memory for the serialised data and buffer - * management for those dictionaries, but the type information would - * be shared. - * </para> - * </refsect3> - * </refsect2> + * ## Memory Use + * + * #GVariant tries to be quite efficient with respect to memory use. + * This section gives a rough idea of how much memory is used by the + * current implementation. The information here is subject to change + * in the future. + * + * The memory allocated by #GVariant can be grouped into 4 broad + * purposes: memory for serialised data, memory for the type + * information cache, buffer management memory and memory for the + * #GVariant structure itself. + * + * ## Serialised Data Memory + * + * This is the memory that is used for storing GVariant data in + * serialised form. This is what would be sent over the network or + * what would end up on disk. + * + * The amount of memory required to store a boolean is 1 byte. 16, + * 32 and 64 bit integers and double precision floating point numbers + * use their "natural" size. Strings (including object path and + * signature strings) are stored with a nul terminator, and as such + * use the length of the string plus 1 byte. + * + * Maybe types use no space at all to represent the null value and + * use the same amount of space (sometimes plus one byte) as the + * equivalent non-maybe-typed value to represent the non-null case. + * + * Arrays use the amount of space required to store each of their + * members, concatenated. Additionally, if the items stored in an + * array are not of a fixed-size (ie: strings, other arrays, etc) + * then an additional framing offset is stored for each item. The + * size of this offset is either 1, 2 or 4 bytes depending on the + * overall size of the container. Additionally, extra padding bytes + * are added as required for alignment of child values. + * + * Tuples (including dictionary entries) use the amount of space + * required to store each of their members, concatenated, plus one + * framing offset (as per arrays) for each non-fixed-sized item in + * the tuple, except for the last one. Additionally, extra padding + * bytes are added as required for alignment of child values. + * + * Variants use the same amount of space as the item inside of the + * variant, plus 1 byte, plus the length of the type string for the + * item inside the variant. + * + * As an example, consider a dictionary mapping strings to variants. + * In the case that the dictionary is empty, 0 bytes are required for + * the serialisation. + * + * If we add an item "width" that maps to the int32 value of 500 then + * we will use 4 byte to store the int32 (so 6 for the variant + * containing it) and 6 bytes for the string. The variant must be + * aligned to 8 after the 6 bytes of the string, so that's 2 extra + * bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used + * for the dictionary entry. An additional 1 byte is added to the + * array as a framing offset making a total of 15 bytes. + * + * If we add another entry, "title" that maps to a nullable string + * that happens to have a value of null, then we use 0 bytes for the + * null value (and 3 bytes for the variant to contain it along with + * its type string) plus 6 bytes for the string. Again, we need 2 + * padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes. + * + * We now require extra padding between the two items in the array. + * After the 14 bytes of the first item, that's 2 bytes required. We + * now require 2 framing offsets for an extra two bytes. 14 + 2 + 11 + * + 2 = 29 bytes to encode the entire two-item dictionary. + * + * ## Type Information Cache + * + * For each GVariant type that currently exists in the program a type + * information structure is kept in the type information cache. The + * type information structure is required for rapid deserialisation. + * + * Continuing with the above example, if a #GVariant exists with the + * type "a{sv}" then a type information struct will exist for + * "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type + * will share the same type information. Additionally, all + * single-digit types are stored in read-only static memory and do + * not contribute to the writable memory footprint of a program using + * #GVariant. + * + * Aside from the type information structures stored in read-only + * memory, there are two forms of type information. One is used for + * container types where there is a single element type: arrays and + * maybe types. The other is used for container types where there + * are multiple element types: tuples and dictionary entries. + * + * Array type info structures are 6 * sizeof (void *), plus the + * memory required to store the type string itself. This means that + * on 32-bit systems, the cache entry for "a{sv}" would require 30 + * bytes of memory (plus malloc overhead). + * + * Tuple type info structures are 6 * sizeof (void *), plus 4 * + * sizeof (void *) for each item in the tuple, plus the memory + * required to store the type string itself. A 2-item tuple, for + * example, would have a type information structure that consumed + * writable memory in the size of 14 * sizeof (void *) (plus type + * string) This means that on 32-bit systems, the cache entry for + * "{sv}" would require 61 bytes of memory (plus malloc overhead). + * + * This means that in total, for our "a{sv}" example, 91 bytes of + * type information would be allocated. + * + * The type information cache, additionally, uses a #GHashTable to + * store and lookup the cached items and stores a pointer to this + * hash table in static storage. The hash table is freed when there + * are zero items in the type cache. + * + * Although these sizes may seem large it is important to remember + * that a program will probably only have a very small number of + * different types of values in it and that only one type information + * structure is required for many different values of the same type. + * + * ## Buffer Management Memory + * + * #GVariant uses an internal buffer management structure to deal + * with the various different possible sources of serialised data + * that it uses. The buffer is responsible for ensuring that the + * correct call is made when the data is no longer in use by + * #GVariant. This may involve a g_free() or a g_slice_free() or + * even g_mapped_file_unref(). + * + * One buffer management structure is used for each chunk of + * serialised data. The size of the buffer management structure + * is 4 * (void *). On 32-bit systems, that's 16 bytes. + * + * ## GVariant structure + * + * The size of a #GVariant structure is 6 * (void *). On 32-bit + * systems, that's 24 bytes. + * + * #GVariant structures only exist if they are explicitly created + * with API calls. For example, if a #GVariant is constructed out of + * serialised data for the example given above (with the dictionary) + * then although there are 9 individual values that comprise the + * entire dictionary (two keys, two values, two variants containing + * the values, two dictionary entries, plus the dictionary itself), + * only 1 #GVariant instance exists -- the one referring to the + * dictionary. + * + * If calls are made to start accessing the other values then + * #GVariant instances will exist for those values only for as long + * as they are in use (ie: until you call g_variant_unref()). The + * type information is shared. The serialised data and the buffer + * management structure for that serialised data is shared by the + * child. + * + * ## Summary + * + * To put the entire example together, for our dictionary mapping + * strings to variants (with two entries, as given above), we are + * using 91 bytes of memory for type information, 29 byes of memory + * for the serialised data, 16 bytes for buffer management and 24 + * bytes for the #GVariant instance, or a total of 160 bytes, plus + * malloc overhead. If we were to use g_variant_get_child_value() to + * access the two dictionary entries, we would use an additional 48 + * bytes. If we were to have other dictionaries of the same type, we + * would use more memory for the serialised data and buffer + * management for those dictionaries, but the type information would + * be shared. */ @@ -6239,18 +6182,18 @@ * @short_description: introduction to the GVariant type system * @see_also: #GVariantType, #GVariant * - * This section introduces the GVariant type system. It is based, in - * large part, on the D-Bus type system, with two major changes and some minor - * lifting of restrictions. The <ulink - * url='http://dbus.freedesktop.org/doc/dbus-specification.html'>DBus - * specification</ulink>, therefore, provides a significant amount of + * This section introduces the GVariant type system. It is based, in + * large part, on the D-Bus type system, with two major changes and + * some minor lifting of restrictions. The + * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html), + * therefore, provides a significant amount of * information that is useful when working with GVariant. * * The first major change with respect to the D-Bus type system is the * introduction of maybe (or "nullable") types. Any type in GVariant can be * converted to a maybe type, in which case, "nothing" (or "null") becomes a * valid value. Maybe types have been added by introducing the - * character "<literal>m</literal>" to type strings. + * character "m" to type strings. * * The second major change is that the GVariant type system supports the * concept of "indefinite types" -- types that are less specific than @@ -6258,8 +6201,7 @@ * of "an array of any type" in GVariant, where the D-Bus type system * would require you to speak of "an array of integers" or "an array of * strings". Indefinite types have been added by introducing the - * characters "<literal>*</literal>", "<literal>?</literal>" and - * "<literal>r</literal>" to type strings. + * characters "*", "?" and "r" to type strings. * * Finally, all arbitrary restrictions relating to the complexity of * types are lifted along with the restriction that dictionary entries @@ -6297,67 +6239,32 @@ * that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of * #GtkBin). * - * A detailed description of GVariant type strings is given here: - * - * <refsect2 id='gvariant-typestrings'> - * <title>GVariant Type Strings</title> - * <para> - * A GVariant type string can be any of the following: - * </para> - * <itemizedlist> - * <listitem> - * <para> - * any basic type string (listed below) - * </para> - * </listitem> - * <listitem> - * <para> - * "<literal>v</literal>", "<literal>r</literal>" or - * "<literal>*</literal>" - * </para> - * </listitem> - * <listitem> - * <para> - * one of the characters '<literal>a</literal>' or - * '<literal>m</literal>', followed by another type string - * </para> - * </listitem> - * <listitem> - * <para> - * the character '<literal>(</literal>', followed by a concatenation - * of zero or more other type strings, followed by the character - * '<literal>)</literal>' - * </para> - * </listitem> - * <listitem> - * <para> - * the character '<literal>{</literal>', followed by a basic type - * string (see below), followed by another type string, followed by - * the character '<literal>}</literal>' - * </para> - * </listitem> - * </itemizedlist> - * <para> - * A basic type string describes a basic type (as per - * g_variant_type_is_basic()) and is always a single - * character in length. The valid basic type strings are - * "<literal>b</literal>", "<literal>y</literal>", - * "<literal>n</literal>", "<literal>q</literal>", - * "<literal>i</literal>", "<literal>u</literal>", - * "<literal>x</literal>", "<literal>t</literal>", - * "<literal>h</literal>", "<literal>d</literal>", - * "<literal>s</literal>", "<literal>o</literal>", - * "<literal>g</literal>" and "<literal>?</literal>". - * </para> - * <para> - * The above definition is recursive to arbitrary depth. - * "<literal>aaaaai</literal>" and "<literal>(ui(nq((y)))s)</literal>" - * are both valid type strings, as is - * "<literal>a(aa(ui)(qna{ya(yd)}))</literal>". - * </para> - * <para> - * The meaning of each of the characters is as follows: - * </para> + * ## GVariant Type Strings + * + * A GVariant type string can be any of the following: + * + * - any basic type string (listed below) + * + * - "v", "r" or "*" + * + * - one of the characters 'a' or 'm', followed by another type string + * + * - the character '(', followed by a concatenation of zero or more other + * type strings, followed by the character ')' + * + * - the character '{', followed by a basic type string (see below), + * followed by another type string, followed by the character '}' + * + * A basic type string describes a basic type (as per + * g_variant_type_is_basic()) and is always a single character in length. + * The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t", + * "h", "d", "s", "o", "g" and "?". + * + * The above definition is recursive to arbitrary depth. "aaaaai" and + * "(ui(nq((y)))s)" are both valid type strings, as is + * "a(aa(ui)(qna{ya(yd)}))". + * + * The meaning of each of the characters is as follows: * <informaltable> * <tgroup cols='2'> * <tbody> @@ -6376,7 +6283,7 @@ * <row> * <entry> * <para> - * <literal>b</literal> + * b * </para> * </entry> * <entry> @@ -6388,7 +6295,7 @@ * <row> * <entry> * <para> - * <literal>y</literal> + * y * </para> * </entry> * <entry> @@ -6400,7 +6307,7 @@ * <row> * <entry> * <para> - * <literal>n</literal> + * n * </para> * </entry> * <entry> @@ -6413,7 +6320,7 @@ * <row> * <entry> * <para> - * <literal>q</literal> + * q * </para> * </entry> * <entry> @@ -6426,7 +6333,7 @@ * <row> * <entry> * <para> - * <literal>i</literal> + * i * </para> * </entry> * <entry> @@ -6439,7 +6346,7 @@ * <row> * <entry> * <para> - * <literal>u</literal> + * u * </para> * </entry> * <entry> @@ -6452,7 +6359,7 @@ * <row> * <entry> * <para> - * <literal>x</literal> + * x * </para> * </entry> * <entry> @@ -6465,7 +6372,7 @@ * <row> * <entry> * <para> - * <literal>t</literal> + * t * </para> * </entry> * <entry> @@ -6478,7 +6385,7 @@ * <row> * <entry> * <para> - * <literal>h</literal> + * h * </para> * </entry> * <entry> @@ -6492,7 +6399,7 @@ * <row> * <entry> * <para> - * <literal>d</literal> + * d * </para> * </entry> * <entry> @@ -6505,7 +6412,7 @@ * <row> * <entry> * <para> - * <literal>s</literal> + * s * </para> * </entry> * <entry> @@ -6517,7 +6424,7 @@ * <row> * <entry> * <para> - * <literal>o</literal> + * o * </para> * </entry> * <entry> @@ -6530,7 +6437,7 @@ * <row> * <entry> * <para> - * <literal>g</literal> + * g * </para> * </entry> * <entry> @@ -6543,7 +6450,7 @@ * <row> * <entry> * <para> - * <literal>?</literal> + * ? * </para> * </entry> * <entry> @@ -6556,7 +6463,7 @@ * <row> * <entry> * <para> - * <literal>v</literal> + * v * </para> * </entry> * <entry> @@ -6569,51 +6476,50 @@ * <row> * <entry> * <para> - * <literal>a</literal> + * a * </para> * </entry> * <entry> * <para> * used as a prefix on another type string to mean an array of - * that type; the type string "<literal>ai</literal>", for - * example, is the type of an array of 32 bit signed integers. + * that type; the type string "ai", for example, is the type of + * an array of signed 32-bit integers. * </para> * </entry> * </row> * <row> * <entry> * <para> - * <literal>m</literal> + * m * </para> * </entry> * <entry> * <para> * used as a prefix on another type string to mean a "maybe", or - * "nullable", version of that type; the type string - * "<literal>ms</literal>", for example, is the type of a value - * that maybe contains a string, or maybe contains nothing. + * "nullable", version of that type; the type string "ms", for example, + * is the type of a value that maybe contains a string, or maybe + * contains nothing. * </para> * </entry> * </row> * <row> * <entry> * <para> - * <literal>()</literal> + * () * </para> * </entry> * <entry> * <para> * used to enclose zero or more other concatenated type strings - * to create a tuple type; the type string - * "<literal>(is)</literal>", for example, is the type of a pair - * of an integer and a string. + * to create a tuple type; the type string "(is)", for example, + * is the type of a pair of an integer and a string. * </para> * </entry> * </row> * <row> * <entry> * <para> - * <literal>r</literal> + * r * </para> * </entry> * <entry> @@ -6627,7 +6533,7 @@ * <row> * <entry> * <para> - * <literal>{}</literal> + * {} * </para> * </entry> * <entry> @@ -6635,13 +6541,12 @@ * used to enclose a basic type string concatenated with another * type string to create a dictionary entry type, which usually * appears inside of an array to form a dictionary; the type - * string "<literal>a{sd}</literal>", for example, is the type of - * a dictionary that maps strings to double precision floating - * point values. + * string "a{sd}", for example, is the type of a dictionary that + * maps strings to double precision floating point values. * </para> * <para> * The first type (the basic type) is the key type and the second - * type is the value type. The reason that the first type is + * type is the value type. The reason that the first type is * restricted to being a basic type is so that it can easily be * hashed. * </para> @@ -6650,14 +6555,14 @@ * <row> * <entry> * <para> - * <literal>*</literal> + * * * </para> * </entry> * <entry> * <para> * the type string of %G_VARIANT_TYPE_ANY; the indefinite type * that is a supertype of all types. Note that, as with all type - * strings, this character represents exactly one type. It + * strings, this character represents exactly one type. It * cannot be used inside of tuples to mean "any number of items". * </para> * </entry> @@ -6665,24 +6570,20 @@ * </tbody> * </tgroup> * </informaltable> - * <para> - * Any type string of a container that contains an indefinite type is, - * itself, an indefinite type. For example, the type string - * "<literal>a*</literal>" (corresponding to %G_VARIANT_TYPE_ARRAY) is - * an indefinite type that is a supertype of every array type. - * "<literal>(*s)</literal>" is a supertype of all tuples that - * contain exactly two items where the second item is a string. - * </para> - * <para> - * "<literal>a{?*}</literal>" is an indefinite type that is a - * supertype of all arrays containing dictionary entries where the key - * is any basic type and the value is any type at all. This is, by - * definition, a dictionary, so this type string corresponds to - * %G_VARIANT_TYPE_DICTIONARY. Note that, due to the restriction that - * the key of a dictionary entry must be a basic type, - * "<literal>{**}</literal>" is not a valid type string. - * </para> - * </refsect2> + * + * Any type string of a container that contains an indefinite type is, + * itself, an indefinite type. For example, the type string "a*" + * (corresponding to %G_VARIANT_TYPE_ARRAY) is an indefinite type + * that is a supertype of every array type. "(*s)" is a supertype + * of all tuples that contain exactly two items where the second + * item is a string. + * + * "a{?*}" is an indefinite type that is a supertype of all arrays + * containing dictionary entries where the key is any basic type and + * the value is any type at all. This is, by definition, a dictionary, + * so this type string corresponds to %G_VARIANT_TYPE_DICTIONARY. Note + * that, due to the restriction that the key of a dictionary entry must + * be a basic type, "{**}" is not a valid type string. */ @@ -6747,7 +6648,8 @@ * HMACs should be used when producing a cookie or hash based on data * and a key. Simple mechanisms for using SHA1 and other algorithms to * digest a key and data together are vulnerable to various security - * issues. <ulink url="http://en.wikipedia.org/wiki/HMAC">HMAC</ulink> + * issues. + * [HMAC](http://en.wikipedia.org/wiki/HMAC) * uses algorithms like SHA1 in a secure way to produce a digest of a * key and data. * @@ -6780,12 +6682,12 @@ * easy-to-use form. * * In order to use these macros in an application, you must include - * <filename>glib/gi18n.h</filename>. For use in a library, you must include - * <filename>glib/gi18n-lib.h</filename> <emphasis>after</emphasis> defining - * the GETTEXT_PACKAGE macro suitably for your library: - * |[ - * #define GETTEXT_PACKAGE "gtk20" - * #include <glib/gi18n-lib.h> + * `<glib/gi18n.h>`. For use in a library, you must include + * `<glib/gi18n-lib.h>` + * after defining the %GETTEXT_PACKAGE macro suitably for your library: + * |[<!-- language="C" --> + * #define GETTEXT_PACKAGE "gtk20" + * #include <glib/gi18n-lib.h> * ]| * For an application, note that you also have to call bindtextdomain(), * bind_textdomain_codeset(), textdomain() and setlocale() early on in your @@ -6804,15 +6706,9 @@ /** * SECTION:iochannels * @title: IO Channels - * @short_description: portable support for using files, pipes and - * sockets - * @see_also: <para> <variablelist> <varlistentry> - * <term>g_io_add_watch(), g_io_add_watch_full(), - * g_source_remove()</term> <listitem><para> Convenience - * functions for creating #GIOChannel instances and adding - * them to the <link linkend="glib-The-Main-Event-Loop">main - * event loop</link>. </para></listitem> </varlistentry> - * </variablelist> </para> + * @short_description: portable support for using files, pipes and sockets + * @see_also: g_io_add_watch(), g_io_add_watch_full(), g_source_remove(), + * #GMainLoop * * The #GIOChannel data type aims to provide a portable method for * using file descriptors, pipes, and sockets, and integrating them @@ -6859,17 +6755,15 @@ * @short_description: parses .ini-like config files * * #GKeyFile lets you parse, edit or create files containing groups of - * key-value pairs, which we call <firstterm>key files</firstterm> for - * lack of a better name. Several freedesktop.org specifications use - * key files now, e.g the - * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop - * Entry Specification</ulink> and the - * <ulink url="http://freedesktop.org/Standards/icon-theme-spec">Icon - * Theme Specification</ulink>. + * key-value pairs, which we call "key files" for lack of a better name. + * Several freedesktop.org specifications use key files now, e.g the + * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) + * and the + * [Icon Theme Specification](http://freedesktop.org/Standards/icon-theme-spec). * * The syntax of key files is described in detail in the - * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop - * Entry Specification</ulink>, here is a quick summary: Key files + * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec), + * here is a quick summary: Key files * consists of groups of key-value pairs, interspersed with comments. * * |[ @@ -6900,11 +6794,11 @@ * in '[' and ']', and ended implicitly by the start of the next group or * the end of the file. Each key-value pair must be contained in a group. * - * Key-value pairs generally have the form <literal>key=value</literal>, - * with the exception of localized strings, which have the form - * <literal>key[locale]=value</literal>, with a locale identifier of the - * form <literal>lang_COUNTRY@MODIFIER</literal> where - * <literal>COUNTRY</literal> and <literal>MODIFIER</literal> are optional. + * Key-value pairs generally have the form `key=value`, with the + * exception of localized strings, which have the form + * `key[locale]=value`, with a locale identifier of the + * form `lang_COUNTRY\@MODIFIER` where `COUNTRY` and `MODIFIER` + * are optional. * Space before and after the '=' character are ignored. Newline, tab, * carriage return and backslash characters in value are escaped as \n, * \t, \r, and \\, respectively. To preserve leading spaces in values, @@ -6917,24 +6811,25 @@ * * This syntax is obviously inspired by the .ini files commonly met * on Windows, but there are some important differences: - * <itemizedlist> - * <listitem>.ini files use the ';' character to begin comments, - * key files use the '#' character.</listitem> - * <listitem>Key files do not allow for ungrouped keys meaning only - * comments can precede the first group.</listitem> - * <listitem>Key files are always encoded in UTF-8.</listitem> - * <listitem>Key and Group names are case-sensitive. For example, a - * group called <literal>[GROUP]</literal> is a different from - * <literal>[group]</literal>.</listitem> - * <listitem>.ini files don't have a strongly typed boolean entry type, - * they only have GetProfileInt(). In key files, only - * <literal>true</literal> and <literal>false</literal> (in lower case) - * are allowed.</listitem> - * </itemizedlist> + * + * - .ini files use the ';' character to begin comments, + * key files use the '#' character. + * + * - Key files do not allow for ungrouped keys meaning only + * comments can precede the first group. + * + * - Key files are always encoded in UTF-8. + * + * - Key and Group names are case-sensitive. For example, a group called + * [GROUP] is a different from [group]. + * + * - .ini files don't have a strongly typed boolean entry type, + * they only have GetProfileInt(). In key files, only + * true and false (in lower case) are allowed. * * Note that in contrast to the - * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop - * Entry Specification</ulink>, groups in key files may contain the same + * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec), + * groups in key files may contain the same * key multiple times; the last entry wins. Key files may also contain * multiple groups with the same name; they are merged together. * Another difference is that keys and group names in key files are not @@ -6983,7 +6878,7 @@ * g_list_insert() and g_list_insert_sorted(). * * To visit all elements in the list, use a loop over the list: - * |[ + * |[<!-- language="C" --> * GList *l; * for (l = list; l != NULL; l = l->next) * { @@ -6995,7 +6890,7 @@ * * To loop over the list and modify it (e.g. remove a certain element) * a while loop is more appropriate, for example: - * |[ + * |[<!-- language="C" --> * GList *l = list; * while (l != NULL) * { @@ -7132,42 +7027,46 @@ * GTK+ contains wrappers of some of these functions, e.g. gtk_main(), * gtk_main_quit() and gtk_events_pending(). * - * <refsect2><title>Creating new source types</title> - * <para>One of the unusual features of the #GMainLoop functionality + * ## Creating new source types + * + * One of the unusual features of the #GMainLoop functionality * is that new types of event source can be created and used in * addition to the builtin type of event source. A new event source * type is used for handling GDK events. A new source type is created - * by <firstterm>deriving</firstterm> from the #GSource structure. - * The derived type of source is represented by a structure that has - * the #GSource structure as a first element, and other elements specific - * to the new source type. To create an instance of the new source type, - * call g_source_new() passing in the size of the derived structure and + * by "deriving" from the #GSource structure. The derived type of + * source is represented by a structure that has the #GSource structure + * as a first element, and other elements specific to the new source + * type. To create an instance of the new source type, call + * g_source_new() passing in the size of the derived structure and * a table of functions. These #GSourceFuncs determine the behavior of - * the new source type.</para> - * <para>New source types basically interact with the main context + * the new source type. + * + * New source types basically interact with the main context * in two ways. Their prepare function in #GSourceFuncs can set a timeout * to determine the maximum amount of time that the main loop will sleep * before checking the source again. In addition, or as well, the source * can add file descriptors to the set that the main context checks using - * g_source_add_poll().</para> - * </refsect2> - * <refsect2><title>Customizing the main loop iteration</title> - * <para>Single iterations of a #GMainContext can be run with + * g_source_add_poll(). + * + * ## Customizing the main loop iteration + * + * Single iterations of a #GMainContext can be run with * g_main_context_iteration(). In some cases, more detailed control * of exactly how the details of the main loop work is desired, for * instance, when integrating the #GMainLoop with an external main loop. * In such cases, you can call the component functions of * g_main_context_iteration() directly. These functions are * g_main_context_prepare(), g_main_context_query(), - * g_main_context_check() and g_main_context_dispatch().</para> - * <para>The operation of these functions can best be seen in terms - * of a state diagram, as shown in <xref linkend="mainloop-states"/>.</para> - * <figure id="mainloop-states"><title>States of a Main Context</title> - * <graphic fileref="mainloop-states.gif" format="GIF"></graphic> - * </figure> - * </refsect2> - * - * On Unix, the GLib mainloop is incompatible with fork(). Any program + * g_main_context_check() and g_main_context_dispatch(). + * + * ## State of a Main Context # {#mainloop-states} + * + * The operation of these functions can best be seen in terms + * of a state diagram, as shown in this image. + * + *  + * + * On UNIX, the GLib mainloop is incompatible with fork(). Any program * using the mainloop must either exec() or exit() from the child * without returning to the mainloop. */ @@ -7175,10 +7074,8 @@ /** * SECTION:markup - * @Title: Simple XML Subset Parser - * @Short_description: parses a subset of XML - * @See_also: <ulink url="http://www.w3.org/TR/REC-xml/">XML - * Specification</ulink> + * @Title: Simple XML Subset Parser * @Short_description: parses a subset of XML + * @See_also: [XML Specification](http://www.w3.org/TR/REC-xml/) * * The "GMarkup" parser is intended to parse a simple markup format * that's a subset of XML. This is a small, efficient, easy-to-use @@ -7192,31 +7089,34 @@ * * GMarkup is not guaranteed to signal an error on all invalid XML; * the parser may accept documents that an XML parser would not. - * However, XML documents which are not well-formed<footnote - * id="wellformed">Being wellformed is a weaker condition than being - * valid. See the <ulink url="http://www.w3.org/TR/REC-xml/">XML - * specification</ulink> for definitions of these terms.</footnote> - * are not considered valid GMarkup documents. + * However, XML documents which are not well-formed (which is a + * weaker condition than being valid. See the + * [XML specification](http://www.w3.org/TR/REC-xml/) + * for definitions of these terms.) are not considered valid GMarkup + * documents. * * Simplifications to XML include: - * <itemizedlist> - * <listitem>Only UTF-8 encoding is allowed</listitem> - * <listitem>No user-defined entities</listitem> - * <listitem>Processing instructions, comments and the doctype declaration - * are "passed through" but are not interpreted in any way</listitem> - * <listitem>No DTD or validation.</listitem> - * </itemizedlist> + * + * - Only UTF-8 encoding is allowed + * + * - No user-defined entities + * + * - Processing instructions, comments and the doctype declaration + * are "passed through" but are not interpreted in any way + * + * - No DTD or validation * * The markup format does support: - * <itemizedlist> - * <listitem>Elements</listitem> - * <listitem>Attributes</listitem> - * <listitem>5 standard entities: - * <literal>&amp; &lt; &gt; &quot; &apos;</literal> - * </listitem> - * <listitem>Character references</listitem> - * <listitem>Sections marked as CDATA</listitem> - * </itemizedlist> + * + * - Elements + * + * - Attributes + * + * - 5 standard entities: &amp; &lt; &gt; &quot; &apos; + * + * - Character references + * + * - Sections marked as CDATA */ @@ -7227,18 +7127,15 @@ * * 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(). */ @@ -7255,12 +7152,13 @@ * * To achieve these goals, the slice allocator uses a sophisticated, * layered design that has been inspired by Bonwick's slab allocator - * <footnote><para> - * <ulink url="http://citeseer.ist.psu.edu/bonwick94slab.html">[Bonwick94]</ulink> Jeff Bonwick, The slab allocator: An object-caching kernel + * ([Bonwick94](http://citeseer.ist.psu.edu/bonwick94slab.html) + * Jeff Bonwick, The slab allocator: An object-caching kernel * memory allocator. USENIX 1994, and - * <ulink url="http://citeseer.ist.psu.edu/bonwick01magazines.html">[Bonwick01]</ulink> Bonwick and Jonathan Adams, Magazines and vmem: Extending the - * slab allocator to many cpu's and arbitrary resources. USENIX 2001 - * </para></footnote>. + * [Bonwick01](http://citeseer.ist.psu.edu/bonwick01magazines.html) + * Bonwick and Jonathan Adams, Magazines and vmem: Extending the + * slab allocator to many cpu's and arbitrary resources. USENIX 2001) + * * It uses posix_memalign() to optimize allocations of many equally-sized * chunks, and has per-thread free lists (the so-called magazine layer) * to quickly satisfy allocation requests of already known structure sizes. @@ -7275,36 +7173,33 @@ * unlike malloc(), it does not reserve extra space per block. For large block * sizes, g_slice_new() and g_slice_alloc() will automatically delegate to the * system malloc() implementation. For newly written code it is recommended - * to use the new <literal>g_slice</literal> API instead of g_malloc() and + * to use the new `g_slice` API instead of g_malloc() and * friends, as long as objects are not resized during their lifetime and the * object size used at allocation time is still available when freeing. * - * <example> - * <title>Using the slice allocator</title> - * <programlisting> + * Here is an example for using the slice allocator: + * |[<!-- language="C" --> * gchar *mem[10000]; * gint i; * * /* Allocate 10000 blocks. */ - * for (i = 0; i < 10000; i++) + * for (i = 0; i < 10000; i++) * { * mem[i] = g_slice_alloc (50); * * /* Fill in the memory with some junk. */ - * for (j = 0; j < 50; j++) + * for (j = 0; j < 50; j++) * mem[i][j] = i * j; * } * * /* Now free all of the blocks. */ - * for (i = 0; i < 10000; i++) - * { - * g_slice_free1 (50, mem[i]); - * } - * </programlisting></example> + * for (i = 0; i < 10000; i++) + * g_slice_free1 (50, mem[i]); + * ]| * - * <example> - * <title>Using the slice allocator with data structures</title> - * <programlisting> + * And here is an example for using the using the slice allocator + * with data structures: + * |[<!-- language="C" --> * GRealArray *array; * * /* Allocate one block, using the g_slice_new() macro. */ @@ -7320,7 +7215,7 @@ * * /* We can free the block, so it can be reused. */ * g_slice_free (GRealArray, array); - * </programlisting></example> + * ]| */ @@ -7360,7 +7255,7 @@ * sign, mantissa and exponent of IEEE floats and doubles. These unions are * defined as appropriate for a given platform. IEEE floats and doubles are * supported (used for storage) by at least Intel, PPC and Sparc. See - * <ulink url="http://en.wikipedia.org/wiki/IEEE_float">IEEE 754-2008</ulink> + * [IEEE 754-2008](http://en.wikipedia.org/wiki/IEEE_float) * for more information about IEEE number formats. */ @@ -7374,40 +7269,37 @@ * for the popt library. It supports short and long commandline options, * as shown in the following example: * - * <literal>testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2</literal> + * `testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2` * * The example demonstrates a number of features of the GOption - * commandline parser - * <itemizedlist><listitem><para> - * Options can be single letters, prefixed by a single dash. Multiple - * short options can be grouped behind a single dash. - * </para></listitem><listitem><para> - * Long options are prefixed by two consecutive dashes. - * </para></listitem><listitem><para> - * Options can have an extra argument, which can be a number, a string or + * commandline parser: + * + * - Options can be single letters, prefixed by a single dash. + * + * - Multiple short options can be grouped behind a single dash. + * + * - Long options are prefixed by two consecutive dashes. + * + * - Options can have an extra argument, which can be a number, a string or * a filename. For long options, the extra argument can be appended with * an equals sign after the option name, which is useful if the extra * argument starts with a dash, which would otherwise cause it to be * interpreted as another option. - * </para></listitem><listitem><para> - * Non-option arguments are returned to the application as rest arguments. - * </para></listitem><listitem><para> - * An argument consisting solely of two dashes turns off further parsing, + * + * - Non-option arguments are returned to the application as rest arguments. + * + * - An argument consisting solely of two dashes turns off further parsing, * any remaining arguments (even those starting with a dash) are returned * to the application as rest arguments. - * </para></listitem></itemizedlist> * * Another important feature of GOption is that it can automatically * generate nicely formatted help output. Unless it is explicitly turned * off with g_option_context_set_help_enabled(), GOption will recognize - * the <option>--help</option>, <option>-?</option>, - * <option>--help-all</option> and - * <option>--help-</option><replaceable>groupname</replaceable> options - * (where <replaceable>groupname</replaceable> is the name of a - * #GOptionGroup) and write a text similar to the one shown in the - * following example to stdout. - * - * <informalexample><screen> + * the `--help`, `-?`, `--help-all` and `--help-groupname` options + * (where `groupname` is the name of a #GOptionGroup) and write a text + * similar to the one shown in the following example to stdout. + * + * |[ * Usage: * testtreemodel [OPTION...] - test tree model performance * @@ -7423,9 +7315,9 @@ * -v, --verbose Be verbose * -b, --beep Beep when done * --rand Randomize the data - * </screen></informalexample> + * ]| * - * GOption groups options in #GOptionGroup<!-- -->s, which makes it easy to + * GOption groups options in #GOptionGroups, which makes it easy to * incorporate options from multiple sources. The intended use for this is * to let applications collect option groups from the libraries it uses, * add them to their #GOptionContext, and parse all options by a single call @@ -7439,8 +7331,7 @@ * * Here is a complete example of setting up GOption to parse the example * commandline above and produce the example help output. - * - * <informalexample><programlisting> + * |[<!-- language="C" --> * static gint repeats = 2; * static gint max_size = 8; * static gboolean verbose = FALSE; @@ -7475,7 +7366,7 @@ * /* ... */ * * } - * </programlisting></informalexample> + * ]| * * On UNIX systems, the argv that is passed to main() has no particular * encoding, even to the extent that different parts of it may have @@ -7499,7 +7390,7 @@ * The following example shows how you can use #GOptionContext directly * in order to correctly deal with Unicode filenames on Windows: * - * |[ + * |[<!-- language="C" --> * int * main (int argc, char **argv) * { @@ -7536,16 +7427,14 @@ * @short_description: matches strings against patterns containing '*' * (wildcard) and '?' (joker) * - * The <function>g_pattern_match*</function> functions match a string + * The g_pattern_match* functions match a string * against a pattern containing '*' and '?' wildcards with similar * semantics as the standard glob() function: '*' matches an arbitrary, * possibly empty, string, '?' matches an arbitrary character. * - * Note that in contrast to glob(), the '/' character - * <emphasis>can</emphasis> be matched by the wildcards, there are no - * '[...]' character ranges and '*' and '?' can - * <emphasis>not</emphasis> be escaped to include them literally in a - * pattern. + * Note that in contrast to glob(), the '/' character can be matched by + * the wildcards, there are no '[...]' character ranges and '*' and '?' + * can not be escaped to include them literally in a pattern. * * When multiple strings must be matched against the same pattern, it * is better to compile the pattern to a #GPatternSpec using @@ -7559,7 +7448,7 @@ * SECTION:quarks * @title: Quarks * @short_description: a 2-way association between a string and a - * unique integer identifier + * unique integer identifier * * Quarks are associations between strings and integer identifiers. * Given either the string or the #GQuark identifier it is possible to @@ -7622,51 +7511,47 @@ * The following functions allow you to use a portable, fast and good * pseudo-random number generator (PRNG). * - * <warning><para>Do not use this API for cryptographic purposes such as key - * generation, nonces, salts or one-time pads.</para></warning> + * Do not use this API for cryptographic purposes such as key + * generation, nonces, salts or one-time pads. * * This PRNG is suitable for non-cryptographic use such as in games - * (shuffling a card deck, generating levels), generating data for a - * test suite, etc. If you need random data for cryptographic - * purposes, it is recommended to use platform-specific APIs such as - * <literal>/dev/random</literal> on Unix, or CryptGenRandom() on - * Windows. + * (shuffling a card deck, generating levels), generating data for + * a test suite, etc. If you need random data for cryptographic + * purposes, it is recommended to use platform-specific APIs such + * as `/dev/random` on UNIX, or CryptGenRandom() on Windows. * * GRand uses the Mersenne Twister PRNG, which was originally * developed by Makoto Matsumoto and Takuji Nishimura. Further - * information can be found at <ulink - * url="http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html"> - * http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html</ulink>. - * - * If you just need a random number, you simply call the - * <function>g_random_*</function> functions, which will create a - * globally used #GRand and use the according - * <function>g_rand_*</function> functions internally. Whenever you - * need a stream of reproducible random numbers, you better create a - * #GRand yourself and use the <function>g_rand_*</function> functions - * directly, which will also be slightly faster. Initializing a #GRand - * with a certain seed will produce exactly the same series of random - * numbers on all platforms. This can thus be used as a seed for e.g. - * games. - * - * The <function>g_rand*_range</function> functions will return high - * quality equally distributed random numbers, whereas for example the - * <literal>(g_random_int()%max)</literal> approach often + * information can be found at + * [this page](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html). + * + * If you just need a random number, you simply call the g_random_* + * functions, which will create a globally used #GRand and use the + * according g_rand_* functions internally. Whenever you need a + * stream of reproducible random numbers, you better create a + * #GRand yourself and use the g_rand_* functions directly, which + * will also be slightly faster. Initializing a #GRand with a + * certain seed will produce exactly the same series of random + * numbers on all platforms. This can thus be used as a seed for + * e.g. games. + * + * The g_rand*_range functions will return high quality equally + * distributed random numbers, whereas for example the + * `(g_random_int()%max)` approach often * doesn't yield equally distributed numbers. * * GLib changed the seeding algorithm for the pseudo-random number - * generator Mersenne Twister, as used by - * <structname>GRand</structname> and <structname>GRandom</structname>. - * This was necessary, because some seeds would yield very bad - * pseudo-random streams. Also the pseudo-random integers generated by - * <function>g_rand*_int_range()</function> will have a slightly better - * equal distribution with the new version of GLib. + * generator Mersenne Twister, as used by #GRand. This was necessary, + * because some seeds would yield very bad pseudo-random streams. + * Also the pseudo-random integers generated by g_rand*_int_range() + * will have a slightly better equal distribution with the new + * version of GLib. * - * The original seeding and generation algorithms, as found in GLib - * 2.0.x, can be used instead of the new ones by setting the - * environment variable <envar>G_RANDOM_VERSION</envar> to the value of - * '2.0'. Use the GLib-2.0 algorithms only if you have sequences of - * numbers generated with Glib-2.0 that you need to reproduce exactly. + * The original seeding and generation algorithms, as found in + * GLib 2.0.x, can be used instead of the new ones by setting the + * environment variable `G_RANDOM_VERSION` to the value of '2.0'. + * Use the GLib-2.0 algorithms only if you have sequences of numbers + * generated with Glib-2.0 that you need to reproduce exactly. */ @@ -7693,12 +7578,11 @@ * linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>, * or simply pointers to any type of data. * - * A #GSequence is accessed through <firstterm>iterators</firstterm>, - * represented by a #GSequenceIter. An iterator represents a position - * between two elements of the sequence. For example, the - * <firstterm>begin</firstterm> iterator represents the gap immediately - * before the first element of the sequence, and the - * <firstterm>end</firstterm> iterator represents the gap immediately + * A #GSequence is accessed through "iterators", represented by a + * #GSequenceIter. An iterator represents a position between two + * elements of the sequence. For example, the "begin" iterator + * represents the gap immediately before the first element of the + * sequence, and the "end" iterator represents the gap immediately * after the last element. In an empty sequence, the begin and end * iterators are the same. * @@ -7711,7 +7595,7 @@ * * The function g_sequence_get() is used with an iterator to access the * element immediately following the gap that the iterator represents. - * The iterator is said to <firstterm>point</firstterm> to that element. + * The iterator is said to "point" to that element. * * Iterators are stable across most operations on a #GSequence. For * example an iterator pointing to some element of a sequence will @@ -7777,27 +7661,25 @@ * * Note that the functions g_printf(), g_fprintf(), g_sprintf(), * g_snprintf(), g_vprintf(), g_vfprintf(), g_vsprintf() and g_vsnprintf() - * are declared in the header <filename>gprintf.h</filename> which is - * <emphasis>not</emphasis> included in <filename>glib.h</filename> - * (otherwise using <filename>glib.h</filename> would drag in - * <filename>stdio.h</filename>), so you'll have to explicitly include - * <literal><glib/gprintf.h></literal> in order to use the GLib + * are declared in the header `gprintf.h` which is not included in `glib.h` + * (otherwise using `glib.h` would drag in `stdio.h`), so you'll have to + * explicitly include `<glib/gprintf.h>` in order to use the GLib * printf() functions. * - * <para id="string-precision">While you may use the printf() functions - * to format UTF-8 strings, notice that the precision of a - * <literal>%Ns</literal> parameter is interpreted as the - * number of <emphasis>bytes</emphasis>, not <emphasis>characters</emphasis> - * to print. On top of that, the GNU libc implementation of the printf() - * functions has the "feature" that it checks that the string given for - * the <literal>%Ns</literal> parameter consists of a whole number - * of characters in the current encoding. So, unless you are sure you are - * always going to be in an UTF-8 locale or your know your text is restricted - * to ASCII, avoid using <literal>%Ns</literal>. If your intention is - * to format strings for a certain number of columns, then - * <literal>%Ns</literal> is not a correct solution anyway, since it - * fails to take wide characters (see g_unichar_iswide()) into account. - * </para> + * ## String precision pitfalls # {#string-precision} + * + * While you may use the printf() functions to format UTF-8 strings, + * notice that the precision of a %Ns parameter is interpreted + * as the number of bytes, not characters to print. On top of that, + * the GNU libc implementation of the printf() functions has the + * "feature" that it checks that the string given for the %Ns + * parameter consists of a whole number of characters in the current + * encoding. So, unless you are sure you are always going to be in an + * UTF-8 locale or your know your text is restricted to ASCII, avoid + * using %Ns. If your intention is to format strings for a + * certain number of columns, then %Ns is not a correct solution + * anyway, since it fails to take wide characters (see g_unichar_iswide()) + * into account. */ @@ -7833,30 +7715,22 @@ * to established concepts found in the other test frameworks (JUnit, NUnit, * RUnit), which in turn is based on smalltalk unit testing concepts. * - * <variablelist> - * <varlistentry> - * <term>Test case</term> - * <listitem>Tests (test methods) are grouped together with their - * fixture into test cases.</listitem> - * </varlistentry> - * <varlistentry> - * <term>Fixture</term> - * <listitem>A test fixture consists of fixture data and setup and - * teardown methods to establish the environment for the test - * functions. We use fresh fixtures, i.e. fixtures are newly set - * up and torn down around each test invocation to avoid dependencies - * between tests.</listitem> - * </varlistentry> - * <varlistentry> - * <term>Test suite</term> - * <listitem>Test cases can be grouped into test suites, to allow - * subsets of the available tests to be run. Test suites can be - * grouped into other test suites as well.</listitem> - * </varlistentry> - * </variablelist> + * - Test case: Tests (test methods) are grouped together with their + * fixture into test cases. + * + * - Fixture: A test fixture consists of fixture data and setup and + * teardown methods to establish the environment for the test + * functions. We use fresh fixtures, i.e. fixtures are newly set + * up and torn down around each test invocation to avoid dependencies + * between tests. + * + * - Test suite: Test cases can be grouped into test suites, to allow + * subsets of the available tests to be run. Test suites can be + * grouped into other test suites as well. + * * The API is designed to handle creation and registration of test suites * and test cases implicitly. A simple call like - * |[ + * |[<!-- language="C" --> * g_test_add_func ("/misc/assertions", test_assertions); * ]| * creates a test suite called "misc" with a single test case named @@ -7954,54 +7828,46 @@ * Originally, UNIX did not have threads, and therefore some traditional * UNIX APIs are problematic in threaded programs. Some notable examples * are - * <itemizedlist> - * <listitem> - * C library functions that return data in statically allocated - * buffers, such as strtok() or strerror(). For many of these, - * there are thread-safe variants with a _r suffix, or you can - * look at corresponding GLib APIs (like g_strsplit() or g_strerror()). - * </listitem> - * <listitem> - * setenv() and unsetenv() manipulate the process environment in - * a not thread-safe way, and may interfere with getenv() calls - * in other threads. Note that getenv() calls may be - * <quote>hidden</quote> behind other APIs. For example, GNU gettext() - * calls getenv() under the covers. In general, it is best to treat - * the environment as readonly. If you absolutely have to modify the - * environment, do it early in main(), when no other threads are around yet. - * </listitem> - * <listitem> - * setlocale() changes the locale for the entire process, affecting - * all threads. Temporary changes to the locale are often made to - * change the behavior of string scanning or formatting functions - * like scanf() or printf(). GLib offers a number of string APIs - * (like g_ascii_formatd() or g_ascii_strtod()) that can often be - * used as an alternative. Or you can use the uselocale() function - * to change the locale only for the current thread. - * </listitem> - * <listitem> - * fork() only takes the calling thread into the child's copy of the - * process image. If other threads were executing in critical - * sections they could have left mutexes locked which could easily - * cause deadlocks in the new child. For this reason, you should - * call exit() or exec() as soon as possible in the child and only - * make signal-safe library calls before that. - * </listitem> - * <listitem> - * daemon() uses fork() in a way contrary to what is described - * above. It should not be used with GLib programs. - * </listitem> - * </itemizedlist> + * + * - C library functions that return data in statically allocated + * buffers, such as strtok() or strerror(). For many of these, + * there are thread-safe variants with a _r suffix, or you can + * look at corresponding GLib APIs (like g_strsplit() or g_strerror()). + * + * - setenv() and unsetenv() manipulate the process environment in + * a not thread-safe way, and may interfere with getenv() calls + * in other threads. Note that getenv() calls may be hidden behind + * other APIs. For example, GNU gettext() calls getenv() under the + * covers. In general, it is best to treat the environment as readonly. + * If you absolutely have to modify the environment, do it early in + * main(), when no other threads are around yet. + * + * - setlocale() changes the locale for the entire process, affecting + * all threads. Temporary changes to the locale are often made to + * change the behavior of string scanning or formatting functions + * like scanf() or printf(). GLib offers a number of string APIs + * (like g_ascii_formatd() or g_ascii_strtod()) that can often be + * used as an alternative. Or you can use the uselocale() function + * to change the locale only for the current thread. + * + * - fork() only takes the calling thread into the child's copy of the + * process image. If other threads were executing in critical + * sections they could have left mutexes locked which could easily + * cause deadlocks in the new child. For this reason, you should + * call exit() or exec() as soon as possible in the child and only + * make signal-safe library calls before that. + * + * - daemon() uses fork() in a way contrary to what is described + * above. It should not be used with GLib programs. * * GLib itself is internally completely thread-safe (all global data is * automatically locked), but individual data structure instances are * not automatically locked for performance reasons. For example, * you must coordinate accesses to the same #GHashTable from multiple * threads. The two notable exceptions from this rule are #GMainLoop - * and #GAsyncQueue, which <emphasis>are</emphasis> thread-safe and - * need no further application-level locking to be accessed from - * multiple threads. Most refcounting functions such as g_object_ref() - * are also thread-safe. + * and #GAsyncQueue, which are thread-safe and need no further + * application-level locking to be accessed from multiple threads. + * Most refcounting functions such as g_object_ref() are also thread-safe. */ @@ -8137,7 +8003,7 @@ * data" to a callback, in the form of a void pointer. From time to time * you want to pass an integer instead of a pointer. You could allocate * an integer, with something like: - * |[ + * |[<!-- language="C" --> * int *ip = g_new (int, 1); * *ip = 42; * ]| @@ -8147,15 +8013,15 @@ * Pointers are always at least 32 bits in size (on all platforms GLib * intends to support). Thus you can store at least 32-bit integer values * in a pointer value. Naively, you might try this, but it's incorrect: - * |[ + * |[<!-- language="C" --> * gpointer p; * int i; * p = (void*) 42; * i = (int) p; * ]| - * Again, that example was <emphasis>not</emphasis> correct, don't copy it. + * Again, that example was not correct, don't copy it. * The problem is that on some systems you need to do this: - * |[ + * |[<!-- language="C" --> * gpointer p; * int i; * p = (void*) (long) 42; @@ -8164,11 +8030,10 @@ * The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care * to do the right thing on the every platform. * - * <warning><para>You may not store pointers in integers. This is not - * portable in any way, shape or form. These macros <emphasis>only</emphasis> - * allow storing integers in pointers, and only preserve 32 bits of the - * integer; values outside the range of a 32-bit integer will be mangled. - * </para></warning> + * Warning: You may not store pointers in integers. This is not + * portable in any way, shape or form. These macros only allow storing + * integers in pointers, and only preserve 32 bits of the integer; values + * outside the range of a 32-bit integer will be mangled. */ @@ -8206,16 +8071,16 @@ * @See_also: g_locale_to_utf8(), g_locale_from_utf8() * * This section describes a number of functions for dealing with - * Unicode characters and strings. There are analogues of the - * traditional <filename>ctype.h</filename> character classification - * and case conversion functions, UTF-8 analogues of some string utility - * functions, functions to perform normalization, case conversion and - * collation on UTF-8 strings and finally functions to convert between - * the UTF-8, UTF-16 and UCS-4 encodings of Unicode. + * Unicode characters and strings. There are analogues of the + * traditional `ctype.h` character classification and case conversion + * functions, UTF-8 analogues of some string utility functions, + * functions to perform normalization, case conversion and collation + * on UTF-8 strings and finally functions to convert between the UTF-8, + * UTF-16 and UCS-4 encodings of Unicode. * * The implementations of the Unicode functions in GLib are based * on the Unicode Character Data tables, which are available from - * <ulink url="http://www.unicode.org/">www.unicode.org</ulink>. + * [www.unicode.org](http://www.unicode.org/). * GLib 2.8 supports Unicode 4.0, GLib 2.10 supports Unicode 4.1, * GLib 2.12 supports Unicode 5.0, GLib 2.16.3 supports Unicode 5.1, * GLib 2.30 supports Unicode 6.0. @@ -8252,15 +8117,16 @@ * * These functions provide support for outputting messages. * - * The <function>g_return</function> family of macros (g_return_if_fail(), - * g_return_val_if_fail(), g_return_if_reached(), g_return_val_if_reached()) - * should only be used for programming errors, a typical use case is - * checking for invalid parameters at the beginning of a public function. - * They should not be used if you just mean "if (error) return", they - * should only be used if you mean "if (bug in program) return". - * The program behavior is generally considered undefined after one - * of these checks fails. They are not intended for normal control - * flow, only to give a perhaps-helpful warning before giving up. + * The g_return family of macros (g_return_if_fail(), + * g_return_val_if_fail(), g_return_if_reached(), + * g_return_val_if_reached()) should only be used for programming + * errors, a typical use case is checking for invalid parameters at + * the beginning of a public function. They should not be used if + * you just mean "if (error) return", they should only be used if + * you mean "if (bug in program) return". The program behavior is + * generally considered undefined after one of these checks fails. + * They are not intended for normal control flow, only to give a + * perhaps-helpful warning before giving up. */ @@ -8322,44 +8188,44 @@ * See your C library manual for more details about access(). * * Returns: zero if the pathname refers to an existing file system - * object that has all the tested permissions, or -1 otherwise or on - * error. + * object that has all the tested permissions, or -1 otherwise + * or on error. * Since: 2.8 */ /** * 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 */ /** * 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_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 @@ -8369,95 +8235,94 @@ * 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(). */ /** * 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 */ /** * 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. * - * <example> - * <title>Getting a pointer to an element in a #GArray</title> - * <programlisting> + * This example gets a pointer to an element in a #GArray: + * |[<!-- language="C" --> * EDayViewEvent *event; - * /<!-- -->* This gets a pointer to the 4th element - * in the array of EDayViewEvent structs. *<!-- -->/ - * event = &g_array_index (events, EDayViewEvent, 3); - * </programlisting> - * </example> + * /* This gets a pointer to the 4th element + * * in the array of EDayViewEvent structs. + * */ + * event = &g_array_index (events, EDayViewEvent, 3); + * ]| * - * Returns: the element of the #GArray at the index given by @i. + * Returns: the element of the #GArray at the index given by @i */ /** * 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 */ /** * 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_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 */ /** * 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. @@ -8466,20 +8331,19 @@ * 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 */ /** * 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. * @@ -8487,58 +8351,58 @@ * existing elements in the array have to be moved to make space for * the new elements. * - * Returns: the #GArray. + * Returns: the #GArray */ /** * 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 */ /** * 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 */ /** * 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 */ /** * 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 */ @@ -8564,38 +8428,38 @@ /** * 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 */ /** * 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. + * Returns: the new #GArray */ /** * 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 @@ -8608,9 +8472,9 @@ /** * 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. @@ -8625,7 +8489,7 @@ /** * 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 @@ -8638,15 +8502,14 @@ /** * 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. * - * Returns: If @c is a decimal digit (according to - * g_ascii_isdigit()), its numeric value. Otherwise, -1. + * Returns: If @c is a decimal digit (according to g_ascii_isdigit()), + * its numeric value. Otherwise, -1. */ @@ -8698,9 +8561,9 @@ * Unlike the standard C library isalnum() function, this only * recognizes standard ASCII letters and ignores the locale, * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a <type>char</type>, - * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to - * cast to #guchar before passing a possibly non-ASCII character in. + * the standard library function, this takes a char, not an int, + * so don't call it on %EOF, but no need to cast to #guchar before + * passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII alphanumeric character */ @@ -8715,9 +8578,9 @@ * Unlike the standard C library isalpha() function, this only * recognizes standard ASCII letters and ignores the locale, * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a <type>char</type>, - * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to - * cast to #guchar before passing a possibly non-ASCII character in. + * the standard library function, this takes a char, not an int, + * so don't call it on %EOF, but no need to cast to #guchar before + * passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII alphabetic character */ @@ -8732,9 +8595,9 @@ * Unlike the standard C library iscntrl() function, this only * recognizes standard ASCII control characters and ignores the * locale, returning %FALSE for all non-ASCII characters. Also, - * unlike the standard library function, this takes a <type>char</type>, - * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to - * cast to #guchar before passing a possibly non-ASCII character in. + * unlike the standard library function, this takes a char, not + * an int, so don't call it on %EOF, but no need to cast to #guchar + * before passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII control character. */ @@ -8747,9 +8610,8 @@ * Determines whether a character is digit (0-9). * * Unlike the standard C library isdigit() function, this takes - * a <type>char</type>, not an <type>int</type>, so don't call it - * on <literal>EOF</literal>, but no need to cast to #guchar before passing a possibly - * non-ASCII character in. + * a char, not an int, so don't call it on %EOF, but no need to + * cast to #guchar before passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII digit. */ @@ -8764,9 +8626,9 @@ * Unlike the standard C library isgraph() function, this only * recognizes standard ASCII characters and ignores the locale, * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a <type>char</type>, - * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need - * to cast to #guchar before passing a possibly non-ASCII character in. + * the standard library function, this takes a char, not an int, + * so don't call it on %EOF, but no need to cast to #guchar before + * passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII printing character other than space. */ @@ -8781,10 +8643,9 @@ * Unlike the standard C library islower() function, this only * recognizes standard ASCII letters and ignores the locale, * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a <type>char</type>, - * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need - * to worry about casting to #guchar before passing a possibly - * non-ASCII character in. + * the standard library function, this takes a char, not an int, + * so don't call it on %EOF, but no need to worry about casting + * to #guchar before passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII lower case letter */ @@ -8799,9 +8660,9 @@ * Unlike the standard C library isprint() function, this only * recognizes standard ASCII characters and ignores the locale, * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a <type>char</type>, - * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need - * to cast to #guchar before passing a possibly non-ASCII character in. + * the standard library function, this takes a char, not an int, + * so don't call it on %EOF, but no need to cast to #guchar before + * passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII printing character. */ @@ -8816,9 +8677,9 @@ * Unlike the standard C library ispunct() function, this only * recognizes standard ASCII letters and ignores the locale, * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a <type>char</type>, - * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to - * cast to #guchar before passing a possibly non-ASCII character in. + * the standard library function, this takes a char, not an int, + * so don't call it on %EOF, but no need to cast to #guchar before + * passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII punctuation character. */ @@ -8833,9 +8694,9 @@ * Unlike the standard C library isspace() function, this only * recognizes standard ASCII white-space and ignores the locale, * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a <type>char</type>, - * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to - * cast to #guchar before passing a possibly non-ASCII character in. + * the standard library function, this takes a char, not an int, + * so don't call it on %EOF, but no need to cast to #guchar before + * passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII white-space character */ @@ -8850,10 +8711,9 @@ * Unlike the standard C library isupper() function, this only * recognizes standard ASCII letters and ignores the locale, * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a <type>char</type>, - * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to - * worry about casting to #guchar before passing a possibly non-ASCII - * character in. + * the standard library function, this takes a char, not an int, + * so don't call it on %EOF, but no need to worry about casting + * to #guchar before passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII upper case letter */ @@ -8866,9 +8726,8 @@ * Determines whether a character is a hexadecimal-digit character. * * Unlike the standard C library isxdigit() function, this takes - * a <type>char</type>, not an <type>int</type>, so don't call it - * on <literal>EOF</literal>, but no need to cast to #guchar before passing a - * possibly non-ASCII character in. + * a char, not an int, so don't call it on %EOF, but no need to + * cast to #guchar before passing a possibly non-ASCII character in. * * Returns: %TRUE if @c is an ASCII hexadecimal-digit character. */ @@ -8876,8 +8735,8 @@ /** * 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. * @@ -8896,30 +8755,29 @@ * Both @s1 and @s2 must be non-%NULL. * * Returns: 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. */ /** * 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. * * Returns: 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.) */ /** * 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. @@ -8933,7 +8791,7 @@ * corresponding to ASCII letters always represent themselves. * * Returns: 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. */ @@ -8959,12 +8817,12 @@ * To convert from a #gdouble to a string in a locale-insensitive * way, use g_ascii_dtostr(). * - * If the correct value would cause overflow, plus or minus <literal>HUGE_VAL</literal> - * is returned (according to the sign of the value), and <literal>ERANGE</literal> is - * stored in <literal>errno</literal>. If the correct value would cause underflow, - * zero is returned and <literal>ERANGE</literal> is stored in <literal>errno</literal>. + * If the correct value would cause overflow, plus or minus %HUGE_VAL + * is returned (according to the sign of the value), and %ERANGE is + * stored in %errno. If the correct value would cause underflow, + * zero is returned and %ERANGE is stored in %errno. * - * This function resets <literal>errno</literal> before calling strtod() so that + * This function resets %errno before calling strtod() so that * you can reliably detect overflow and underflow. * * Returns: the #gdouble value. @@ -8990,9 +8848,9 @@ * locale-sensitive system strtoll() function. * * If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64 - * is returned, and <literal>ERANGE</literal> is stored in <literal>errno</literal>. + * is returned, and `ERANGE` is stored in `errno`. * If the base is outside the valid range, zero is returned, and - * <literal>EINVAL</literal> is stored in <literal>errno</literal>. If the + * `EINVAL` is stored in `errno`. If the * string conversion fails, zero is returned, and @endptr returns @nptr * (if @endptr is non-%NULL). * @@ -9020,9 +8878,9 @@ * locale-sensitive system strtoull() function. * * If the correct value would cause overflow, %G_MAXUINT64 - * is returned, and <literal>ERANGE</literal> is stored in <literal>errno</literal>. + * is returned, and `ERANGE` is stored in `errno`. * If the base is outside the valid range, zero is returned, and - * <literal>EINVAL</literal> is stored in <literal>errno</literal>. + * `EINVAL` is stored in `errno`. * If the string conversion fails, zero is returned, and @endptr returns * @nptr (if @endptr is non-%NULL). * @@ -9033,22 +8891,21 @@ /** * 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. * * Returns: 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.) */ /** * g_ascii_tolower: - * @c: any character. + * @c: any character * * Convert a character to ASCII lower case. * @@ -9057,18 +8914,17 @@ * 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. * - * Returns: the result of converting @c to lower case. - * If @c is not an ASCII upper case letter, - * @c is returned unchanged. + * Returns: the result of converting @c to lower case. If @c is + * not an ASCII upper case letter, @c is returned unchanged. */ /** * g_ascii_toupper: - * @c: any character. + * @c: any character * * Convert a character to ASCII upper case. * @@ -9077,12 +8933,11 @@ * 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. * - * Returns: the result of converting @c to upper case. - * If @c is not an ASCII lower case letter, - * @c is returned unchanged. + * Returns: the result of converting @c to upper case. If @c is not + * an ASCII lower case letter, @c is returned unchanged. */ @@ -9095,8 +8950,8 @@ * a char, so there's no worry about sign extension if characters * are signed. * - * Returns: If @c is a hex digit (according to - * g_ascii_isxdigit()), its numeric value. Otherwise, -1. + * Returns: If @c is a hex digit (according to g_ascii_isxdigit()), + * its numeric value. Otherwise, -1. */ @@ -9109,7 +8964,7 @@ * an error message is logged and the application is terminated. * * The macro can be turned off in final releases of code by defining - * <envar>G_DISABLE_ASSERT</envar> when compiling the application. + * `G_DISABLE_ASSERT` when compiling the application. */ @@ -9122,8 +8977,8 @@ * * Debugging macro to compare two floating point numbers. * - * The effect of <literal>g_assert_cmpfloat (n1, op, n2)</literal> is - * the same as <literal>g_assert_true (n1 op n2)</literal>. The advantage + * The effect of `g_assert_cmpfloat (n1, op, n2)` is + * the same as `g_assert_true (n1 op n2)`. The advantage * of this macro is that it can produce a message that includes the * actual values of @n1 and @n2. * @@ -9156,8 +9011,8 @@ * * Debugging macro to compare two integers. * - * The effect of <literal>g_assert_cmpint (n1, op, n2)</literal> is - * the same as <literal>g_assert_true (n1 op n2)</literal>. The advantage + * The effect of `g_assert_cmpint (n1, op, n2)` is + * the same as `g_assert_true (n1 op n2)`. The advantage * of this macro is that it can produce a message that includes the * actual values of @n1 and @n2. * @@ -9177,12 +9032,12 @@ * or the testcase marked as failed. * The strings are compared using g_strcmp0(). * - * The effect of <literal>g_assert_cmpstr (s1, op, s2)</literal> is - * the same as <literal>g_assert_true (g_strcmp0 (s1, s2) op 0)</literal>. + * The effect of `g_assert_cmpstr (s1, op, s2)` is + * the same as `g_assert_true (g_strcmp0 (s1, s2) op 0)`. * The advantage of this macro is that it can produce a message that * includes the actual values of @s1 and @s2. * - * |[ + * |[<!-- language="C" --> * g_assert_cmpstr (mystring, ==, "fubar"); * ]| * @@ -9199,8 +9054,8 @@ * * Debugging macro to compare two unsigned integers. * - * The effect of <literal>g_assert_cmpuint (n1, op, n2)</literal> is - * the same as <literal>g_assert_true (n1 op n2)</literal>. The advantage + * The effect of `g_assert_cmpuint (n1, op, n2)` is + * the same as `g_assert_true (n1 op n2)`. The advantage * of this macro is that it can produce a message that includes the * actual values of @n1 and @n2. * @@ -9217,15 +9072,15 @@ * Debugging macro to check that a method has returned * the correct #GError. * - * The effect of <literal>g_assert_error (err, dom, c)</literal> is - * the same as <literal>g_assert_true (err != NULL && err->domain - * == dom && err->code == c)</literal>. The advantage of this + * The effect of `g_assert_error (err, dom, c)` is + * the same as `g_assert_true (err != NULL && err->domain + * == dom && err->code == c)`. The advantage of this * macro is that it can produce a message that includes the incorrect * error message and code. * * This can only be used to test for a specific error. If you want to * test that @err is set, but don't care what it's set to, just use - * <literal>g_assert (err != NULL)</literal> + * `g_assert (err != NULL)` * * Since: 2.20 */ @@ -9253,8 +9108,8 @@ * * Debugging macro to check that a #GError is not set. * - * The effect of <literal>g_assert_no_error (err)</literal> is - * the same as <literal>g_assert_true (err == NULL)</literal>. The advantage + * The effect of `g_assert_no_error (err)` is + * the same as `g_assert_true (err == NULL)`. The advantage * of this macro is that it can produce a message that includes * the error message and code. * @@ -9286,7 +9141,7 @@ * application is terminated. * * The macro can be turned off in final releases of code by defining - * <envar>G_DISABLE_ASSERT</envar> when compiling the application. + * `G_DISABLE_ASSERT` when compiling the application. */ @@ -9369,8 +9224,8 @@ * Call g_async_queue_unlock() to drop the lock again. * * While holding the lock, you can only call the - * <function>g_async_queue_*_unlocked()</function> functions - * on @queue. Otherwise, deadlock may occur. + * g_async_queue_*_unlocked() functions on @queue. Otherwise, + * deadlock may occur. */ @@ -9531,7 +9386,7 @@ * * If you were sorting a list of priority numbers to make sure the * lowest priority would be at the top of the queue, you could use: - * |[ + * |[<!-- language="C" --> * gint32 id1; * gint32 id2; * @@ -9750,7 +9605,7 @@ * Atomically adds @val to the value of @atomic. * * Think of this operation as an atomic version of - * <literal>{ tmp = *atomic; *@atomic += @val; return tmp; }</literal> + * `{ tmp = *atomic; *@atomic += @val; return tmp; }`. * * This call acts as a full compiler and hardware memory barrier. * @@ -9773,7 +9628,7 @@ * This call acts as a full compiler and hardware memory barrier. * * Think of this operation as an atomic version of - * <literal>{ tmp = *atomic; *@atomic &= @val; return tmp; }</literal> + * `{ tmp = *atomic; *@atomic &= @val; return tmp; }`. * * Returns: the value of @atomic before the operation, unsigned * Since: 2.30 @@ -9792,7 +9647,7 @@ * This compare and exchange is done atomically. * * Think of this operation as an atomic version of - * <literal>{ if (*@atomic == @oldval) { *@atomic = @newval; return TRUE; } else return FALSE; }</literal> + * `{ if (*@atomic == @oldval) { *@atomic = @newval; return TRUE; } else return FALSE; }`. * * This call acts as a full compiler and hardware memory barrier. * @@ -9808,7 +9663,7 @@ * Decrements the value of @atomic by 1. * * Think of this operation as an atomic version of - * <literal>{ *@atomic -= 1; return (*@atomic == 0); }</literal> + * `{ *@atomic -= 1; return (*@atomic == 0); }`. * * This call acts as a full compiler and hardware memory barrier. * @@ -9852,8 +9707,7 @@ * * Increments the value of @atomic by 1. * - * Think of this operation as an atomic version of - * <literal>{ *@atomic += 1; }</literal> + * Think of this operation as an atomic version of `{ *@atomic += 1; }`. * * This call acts as a full compiler and hardware memory barrier. * @@ -9870,7 +9724,7 @@ * storing the result back in @atomic. * * Think of this operation as an atomic version of - * <literal>{ tmp = *atomic; *@atomic |= @val; return tmp; }</literal> + * `{ tmp = *atomic; *@atomic |= @val; return tmp; }`. * * This call acts as a full compiler and hardware memory barrier. * @@ -9902,7 +9756,7 @@ * storing the result back in @atomic. * * Think of this operation as an atomic version of - * <literal>{ tmp = *atomic; *@atomic ^= @val; return tmp; }</literal> + * `{ tmp = *atomic; *@atomic ^= @val; return tmp; }`. * * This call acts as a full compiler and hardware memory barrier. * @@ -9919,7 +9773,7 @@ * Atomically adds @val to the value of @atomic. * * Think of this operation as an atomic version of - * <literal>{ tmp = *atomic; *@atomic += @val; return tmp; }</literal> + * `{ tmp = *atomic; *@atomic += @val; return tmp; }`. * * This call acts as a full compiler and hardware memory barrier. * @@ -9937,7 +9791,7 @@ * storing the result back in @atomic. * * Think of this operation as an atomic version of - * <literal>{ tmp = *atomic; *@atomic &= @val; return tmp; }</literal> + * `{ tmp = *atomic; *@atomic &= @val; return tmp; }`. * * This call acts as a full compiler and hardware memory barrier. * @@ -9958,7 +9812,7 @@ * This compare and exchange is done atomically. * * Think of this operation as an atomic version of - * <literal>{ if (*@atomic == @oldval) { *@atomic = @newval; return TRUE; } else return FALSE; }</literal> + * `{ if (*@atomic == @oldval) { *@atomic = @newval; return TRUE; } else return FALSE; }`. * * This call acts as a full compiler and hardware memory barrier. * @@ -9990,7 +9844,7 @@ * storing the result back in @atomic. * * Think of this operation as an atomic version of - * <literal>{ tmp = *atomic; *@atomic |= @val; return tmp; }</literal> + * `{ tmp = *atomic; *@atomic |= @val; return tmp; }`. * * This call acts as a full compiler and hardware memory barrier. * @@ -10022,7 +9876,7 @@ * storing the result back in @atomic. * * Think of this operation as an atomic version of - * <literal>{ tmp = *atomic; *@atomic ^= @val; return tmp; }</literal> + * `{ tmp = *atomic; *@atomic ^= @val; return tmp; }`. * * This call acts as a full compiler and hardware memory barrier. * @@ -10143,9 +9997,9 @@ * @break_lines is typically used when putting base64-encoded data in emails. * It breaks the lines at 72 columns instead of putting all of the text on * the same line. This avoids problems with long lines in the email system. - * Note however that it breaks the lines with <literal>LF</literal> - * characters, not <literal>CR LF</literal> sequences, so the result cannot - * be passed directly to SMTP or certain other protocols. + * Note however that it breaks the lines with `LF` characters, not + * `CR LF` sequences, so the result cannot be passed directly to SMTP + * or certain other protocols. * * Returns: The number of bytes of output that was written * Since: 2.12 @@ -10980,15 +10834,14 @@ * Creates a filename from a series of elements using the correct * separator for filenames. * - * On Unix, this function behaves identically to <literal>g_build_path - * (G_DIR_SEPARATOR_S, first_element, ....)</literal>. + * On Unix, this function behaves identically to `g_build_path + * (G_DIR_SEPARATOR_S, first_element, ....)`. * * On Windows, it takes into account that either the backslash - * (<literal>\</literal> or slash (<literal>/</literal>) can be used - * as separator in filenames, but otherwise behaves as on Unix. When - * file pathname separators need to be inserted, the one that last - * previously occurred in the parameters (reading from left to right) - * is used. + * (`\` or slash (`/`) can be used as separator in filenames, but + * otherwise behaves as on UNIX. When file pathname separators need + * to be inserted, the one that last previously occurred in the + * parameters (reading from left to right) is used. * * No attempt is made to force the resulting filename to be an absolute * path. If the first element is a relative path, the result will @@ -11033,8 +10886,7 @@ * the same as the number of trailing copies of the separator on * the last non-empty element. (Determination of the number of * trailing copies is done without stripping leading copies, so - * if the separator is <literal>ABA</literal>, <literal>ABABA</literal> - * has 1 trailing copy.) + * if the separator is `ABA`, then `ABABA` has 1 trailing copy.) * * However, if there is only a single non-empty element, and there * are no characters in that element not part of the leading or @@ -11065,21 +10917,21 @@ /** * 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. + * Adds the given bytes to the end of the #GByteArray. + * The array will grow in size automatically if necessary. * - * Returns: the #GByteArray. + * Returns: the #GByteArray */ /** * 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 @@ -11105,8 +10957,8 @@ * together. * * 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 */ @@ -11115,7 +10967,7 @@ * * Creates a new #GByteArray with a reference count of 1. * - * Returns: (transfer full): the new #GByteArray. + * Returns: (transfer full): the new #GByteArray */ @@ -11134,97 +10986,97 @@ /** * 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. + * Adds the given data to the start of the #GByteArray. + * The array will grow in size automatically if necessary. * - * Returns: the #GByteArray. + * Returns: the #GByteArray */ /** * 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. + * Atomically increments the reference count of @array by one. + * This function is thread-safe and may be called from any thread. * - * Returns: The passed in #GByteArray. + * Returns: The passed in #GByteArray * Since: 2.22 */ /** * 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. + * Removes the byte at the given index from a #GByteArray. + * The following bytes are moved down one place. * - * Returns: the #GByteArray. + * Returns: the #GByteArray */ /** * 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. + * Returns: the #GByteArray */ /** * 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 */ /** * 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. + * Returns: the #GByteArray */ /** * 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. + * Returns: the new #GByteArray */ /** * 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 @@ -11241,9 +11093,9 @@ /** * 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. @@ -11252,11 +11104,11 @@ /** * 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 - * released. This function is MT-safe and may be called from any + * released. This function is thread-safe and may be called from any * thread. * * Since: 2.22 @@ -11706,8 +11558,7 @@ * executed. * * Note that child watch sources can only be used in conjunction with - * <literal>g_spawn...</literal> when the %G_SPAWN_DO_NOT_REAP_CHILD - * flag is used. + * `g_spawn...` when the %G_SPAWN_DO_NOT_REAP_CHILD flag is used. * * Note that on platforms where #GPid must be explicitly closed * (see g_spawn_close_pid()) @pid must not be closed while the @@ -11715,9 +11566,9 @@ * g_spawn_close_pid() in the callback function for the source. * * Note further that using g_child_watch_source_new() is not - * compatible with calling <literal>waitpid</literal> with a - * nonpositive first argument in the application. Calling waitpid() - * for individual pids will still work fine. + * compatible with calling `waitpid` with a nonpositive first + * argument in the application. Calling waitpid() for individual + * pids will still work fine. * * Returns: the newly-created child watch source * Since: 2.4 @@ -11740,7 +11591,7 @@ * * See your C library manual for more details about chmod(). * - * Returns: zero if the operation succeeded, -1 on error. + * Returns: 0 if the operation succeeded, -1 on error * Since: 2.8 */ @@ -11981,10 +11832,10 @@ * passed. * * The following code shows how to correctly perform a timed wait on a - * condition variable (extended the example presented in the + * condition variable (extending the example presented in the * documentation for #GCond): * - * |[ + * |[<!-- language="C" --> * gpointer * pop_data_timed (void) * { @@ -11997,12 +11848,12 @@ * while (!current_data) * if (!g_cond_wait_until (&data_cond, &data_mutex, end_time)) * { - * // timeout has passed. + * /* timeout has passed. */ * g_mutex_unlock (&data_mutex); * return NULL; * } * - * // there is data for us + * /* there is data for us */ * data = current_data; * current_data = NULL; * @@ -12028,13 +11879,9 @@ * g_convert: * @str: the string to convert * @len: the length of the string, or -1 if the string is - * nul-terminated<footnote id="nul-unsafe"> - * <para> - * Note that some encodings may allow nul bytes to - * occur inside strings. In that case, using -1 for - * the @len parameter is unsafe. - * </para> - * </footnote>. + * nul-terminated (Note that some encodings may allow nul + * bytes to occur inside strings. In that case, using -1 + * for the @len parameter is unsafe) * @to_codeset: name of character set into which to convert @str * @from_codeset: character set of @str. * @bytes_read: (out): location to store the number of bytes in the @@ -12052,8 +11899,15 @@ * * Converts a string from one character set to another. * - * Note that you should use g_iconv() for streaming - * conversions<footnoteref linkend="streaming-state"/>. + * Note that you should use g_iconv() for streaming conversions. + * Despite the fact that @byes_read can return information about partial + * characters, the g_convert_... functions are not generally suitable + * for streaming. If the underlying converter maintains internal state, + * then this won't be preserved across successive calls to g_convert(), + * g_convert_with_iconv() or g_convert_with_fallback(). (An example of + * this is the GNU C converter for CP1255 which does not emit a base + * character until it knows that the next character is not a mark that + * could combine with the base character.) * * Returns: If the conversion was successful, a newly allocated * nul-terminated string, which must be freed with @@ -12065,7 +11919,9 @@ * g_convert_with_fallback: * @str: the string to convert * @len: the length of the string, or -1 if the string is - * nul-terminated<footnoteref linkend="nul-unsafe"/>. + * nul-terminated (Note that some encodings may allow nul + * bytes to occur inside strings. In that case, using -1 + * for the @len parameter is unsafe) * @to_codeset: name of character set into which to convert @str * @from_codeset: character set of @str. * @fallback: UTF-8 string to use in place of character not @@ -12091,8 +11947,15 @@ * to @to_codeset in their iconv() functions, * in which case GLib will simply return that approximate conversion. * - * Note that you should use g_iconv() for streaming - * conversions<footnoteref linkend="streaming-state"/>. + * Note that you should use g_iconv() for streaming conversions. + * Despite the fact that @byes_read can return information about partial + * characters, the g_convert_... functions are not generally suitable + * for streaming. If the underlying converter maintains internal state, + * then this won't be preserved across successive calls to g_convert(), + * g_convert_with_iconv() or g_convert_with_fallback(). (An example of + * this is the GNU C converter for CP1255 which does not emit a base + * character until it knows that the next character is not a mark that + * could combine with the base character.) * * Returns: If the conversion was successful, a newly allocated * nul-terminated string, which must be freed with @@ -12104,7 +11967,9 @@ * g_convert_with_iconv: * @str: the string to convert * @len: the length of the string, or -1 if the string is - * nul-terminated<footnoteref linkend="nul-unsafe"/>. + * nul-terminated (Note that some encodings may allow nul + * bytes to occur inside strings. In that case, using -1 + * for the @len parameter is unsafe) * @converter: conversion descriptor from g_iconv_open() * @bytes_read: location to store the number of bytes in the * input string that were successfully converted, or %NULL. @@ -12121,20 +11986,15 @@ * * Converts a string from one character set to another. * - * Note that you should use g_iconv() for streaming - * conversions<footnote id="streaming-state"> - * <para> + * Note that you should use g_iconv() for streaming conversions. * Despite the fact that @byes_read can return information about partial - * characters, the <literal>g_convert_...</literal> functions - * are not generally suitable for streaming. If the underlying converter - * being used maintains internal state, then this won't be preserved - * across successive calls to g_convert(), g_convert_with_iconv() or - * g_convert_with_fallback(). (An example of this is the GNU C converter - * for CP1255 which does not emit a base character until it knows that - * the next character is not a mark that could combine with the base - * character.) - * </para> - * </footnote>. + * characters, the g_convert_... functions are not generally suitable + * for streaming. If the underlying converter maintains internal state, + * then this won't be preserved across successive calls to g_convert(), + * g_convert_with_iconv() or g_convert_with_fallback(). (An example of + * this is the GNU C converter for CP1255 which does not emit a base + * character until it knows that the next character is not a mark that + * could combine with the base character.) * * Returns: If the conversion was successful, a newly allocated * nul-terminated string, which must be freed with @@ -12167,8 +12027,9 @@ * * See your C library manual for more details about creat(). * - * Returns: a new file descriptor, or -1 if an error occurred. The - * return value can be used exactly like the return value from creat(). + * Returns: a new file descriptor, or -1 if an error occurred. + * The return value can be used exactly like the return value + * from creat(). * Since: 2.8 */ @@ -12186,8 +12047,8 @@ * example. * * You can also make critical warnings fatal at runtime by - * setting the <envar>G_DEBUG</envar> environment variable (see - * <ulink url="glib-running.html">Running GLib Applications</ulink>). + * setting the `G_DEBUG` environment variable (see + * [Running GLib Applications](glib-running.html)). * * If g_log_default_handler() is used as the log handler function, a new-line * character will automatically be appended to @..., and need not be entered @@ -12862,11 +12723,11 @@ * @year: year to check * * Returns %TRUE if the year is a leap year. - * <footnote><para>For the purposes of this function, - * leap year is every year divisible by 4 unless that year - * is divisible by 100. If it is divisible by 100 it would - * be a leap year only if that year is also divisible - * by 400.</para></footnote> + * + * For the purposes of this function, leap year is every year + * divisible by 4 unless that year is divisible by 100. If it + * is divisible by 100 it would be a leap year only if that year + * is also divisible by 400. * * Returns: %TRUE if the year is a leap year */ @@ -12997,14 +12858,14 @@ /** * g_date_set_time_t: * @date: a #GDate - * @timet: <type>time_t</type> value to set + * @timet: time_t value to set * * Sets the value of a date to the date corresponding to a time * specified as a time_t. The time to date conversion is done using * the user's current timezone. * * To set the value of a date to the current day, you could write: - * |[ + * |[<!-- language="C" --> * g_date_set_time_t (date, time (NULL)); * ]| * @@ -13293,266 +13154,81 @@ * * The following format specifiers are supported: * - * <variablelist> - * <varlistentry><term> - * <literal>\%a</literal>: - * </term><listitem><simpara> - * the abbreviated weekday name according to the current locale - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%A</literal>: - * </term><listitem><simpara> - * the full weekday name according to the current locale - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%b</literal>: - * </term><listitem><simpara> - * the abbreviated month name according to the current locale - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%B</literal>: - * </term><listitem><simpara> - * the full month name according to the current locale - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%c</literal>: - * </term><listitem><simpara> - * the preferred date and time representation for the current locale - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%C</literal>: - * </term><listitem><simpara> - * The century number (year/100) as a 2-digit integer (00-99) - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%d</literal>: - * </term><listitem><simpara> - * the day of the month as a decimal number (range 01 to 31) - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%e</literal>: - * </term><listitem><simpara> - * the day of the month as a decimal number (range 1 to 31) - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%F</literal>: - * </term><listitem><simpara> - * equivalent to <literal>\%Y-\%m-\%d</literal> (the ISO 8601 date - * format) - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%g</literal>: - * </term><listitem><simpara> - * the last two digits of the ISO 8601 week-based year as a decimal - * number (00-99). This works well with \%V and \%u. - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%G</literal>: - * </term><listitem><simpara> - * the ISO 8601 week-based year as a decimal number. This works well - * with \%V and \%u. - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%h</literal>: - * </term><listitem><simpara> - * equivalent to <literal>\%b</literal> - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%H</literal>: - * </term><listitem><simpara> - * the hour as a decimal number using a 24-hour clock (range 00 to - * 23) - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%I</literal>: - * </term><listitem><simpara> - * the hour as a decimal number using a 12-hour clock (range 01 to - * 12) - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%j</literal>: - * </term><listitem><simpara> - * the day of the year as a decimal number (range 001 to 366) - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%k</literal>: - * </term><listitem><simpara> - * the hour (24-hour clock) as a decimal number (range 0 to 23); - * single digits are preceded by a blank - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%l</literal>: - * </term><listitem><simpara> - * the hour (12-hour clock) as a decimal number (range 1 to 12); - * single digits are preceded by a blank - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%m</literal>: - * </term><listitem><simpara> - * the month as a decimal number (range 01 to 12) - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%M</literal>: - * </term><listitem><simpara> - * the minute as a decimal number (range 00 to 59) - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%p</literal>: - * </term><listitem><simpara> - * either "AM" or "PM" according to the given time value, or the - * corresponding strings for the current locale. Noon is treated as - * "PM" and midnight as "AM". - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%P</literal>: - * </term><listitem><simpara> - * like \%p but lowercase: "am" or "pm" or a corresponding string for - * the current locale - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%r</literal>: - * </term><listitem><simpara> - * the time in a.m. or p.m. notation - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%R</literal>: - * </term><listitem><simpara> - * the time in 24-hour notation (<literal>\%H:\%M</literal>) - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%s</literal>: - * </term><listitem><simpara> - * the number of seconds since the Epoch, that is, since 1970-01-01 - * 00:00:00 UTC - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%S</literal>: - * </term><listitem><simpara> - * the second as a decimal number (range 00 to 60) - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%t</literal>: - * </term><listitem><simpara> - * a tab character - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%T</literal>: - * </term><listitem><simpara> - * the time in 24-hour notation with seconds (<literal>\%H:\%M:\%S</literal>) - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%u</literal>: - * </term><listitem><simpara> - * the ISO 8601 standard day of the week as a decimal, range 1 to 7, - * Monday being 1. This works well with \%G and \%V. - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%V</literal>: - * </term><listitem><simpara> - * the ISO 8601 standard week number of the current year as a decimal - * number, range 01 to 53, where week 1 is the first week that has at - * least 4 days in the new year. See g_date_time_get_week_of_year(). - * This works well with \%G and \%u. - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%w</literal>: - * </term><listitem><simpara> - * the day of the week as a decimal, range 0 to 6, Sunday being 0. - * This is not the ISO 8601 standard format -- use \%u instead. - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%x</literal>: - * </term><listitem><simpara> - * the preferred date representation for the current locale without - * the time - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%X</literal>: - * </term><listitem><simpara> - * the preferred time representation for the current locale without - * the date - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%y</literal>: - * </term><listitem><simpara> - * the year as a decimal number without the century - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%Y</literal>: - * </term><listitem><simpara> - * the year as a decimal number including the century - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%z</literal>: - * </term><listitem><simpara> - * the time zone as an offset from UTC (+hhmm) - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%:z</literal>: - * </term><listitem><simpara> - * the time zone as an offset from UTC (+hh:mm). This is a gnulib strftime extension. Since: 2.38 - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%::z</literal>: - * </term><listitem><simpara> - * the time zone as an offset from UTC (+hh:mm:ss). This is a gnulib strftime extension. Since: 2.38 - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%:::z</literal>: - * </term><listitem><simpara> - * the time zone as an offset from UTC, with : to necessary precision - * (e.g., -04, +05:30). This is a gnulib strftime extension. Since: 2.38 - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%Z</literal>: - * </term><listitem><simpara> - * the time zone or name or abbreviation - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%\%</literal>: - * </term><listitem><simpara> - * a literal <literal>\%</literal> character - * </simpara></listitem></varlistentry> - * </variablelist> + * - \%a: the abbreviated weekday name according to the current locale + * - \%A: the full weekday name according to the current locale + * - \%b: the abbreviated month name according to the current locale + * - \%B: the full month name according to the current locale + * - \%c: the preferred date and time rpresentation for the current locale + * - \%C: the century number (year/100) as a 2-digit integer (00-99) + * - \%d: the day of the month as a decimal number (range 01 to 31) + * - \%e: the day of the month as a decimal number (range 1 to 31) + * - \%F: equivalent to `\%Y-\%m-\%d` (the ISO 8601 date format) + * - \%g: the last two digits of the ISO 8601 week-based year as a + * decimal number (00-99). This works well with \%V and \%u. + * - \%G: the ISO 8601 week-based year as a decimal number. This works + * well with \%V and \%u. + * - \%h: equivalent to \%b + * - \%H: the hour as a decimal number using a 24-hour clock (range 00 to 23) + * - \%I: the hour as a decimal number using a 12-hour clock (range 01 to 12) + * - \%j: the day of the year as a decimal number (range 001 to 366) + * - \%k: the hour (24-hour clock) as a decimal number (range 0 to 23); + * single digits are preceded by a blank + * - \%l: the hour (12-hour clock) as a decimal number (range 1 to 12); + * single digits are preceded by a blank + * - \%m: the month as a decimal number (range 01 to 12) + * - \%M: the minute as a decimal number (range 00 to 59) + * - \%p: either "AM" or "PM" according to the given time value, or the + * corresponding strings for the current locale. Noon is treated as + * "PM" and midnight as "AM". + * - \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for + * the current locale + * - \%r: the time in a.m. or p.m. notation + * - \%R: the time in 24-hour notation (\%H:\%M) + * - \%s: the number of seconds since the Epoch, that is, since 1970-01-01 + * 00:00:00 UTC + * - \%S: the second as a decimal number (range 00 to 60) + * - \%t: a tab character + * - \%T: the time in 24-hour notation with seconds (\%H:\%M:\%S) + * - \%u: the ISO 8601 standard day of the week as a decimal, range 1 to 7, + * Monday being 1. This works well with \%G and \%V. + * - \%V: the ISO 8601 standard week number of the current year as a decimal + * number, range 01 to 53, where week 1 is the first week that has at + * least 4 days in the new year. See g_date_time_get_week_of_year(). + * This works well with \%G and \%u. + * - \%w: the day of the week as a decimal, range 0 to 6, Sunday being 0. + * This is not the ISO 8601 standard format -- use \%u instead. + * - \%x: the preferred date representation for the current locale without + * the time + * - \%X: the preferred time representation for the current locale without + * the date + * - \%y: the year as a decimal number without the century + * - \%Y: the year as a decimal number including the century + * - \%z: the time zone as an offset from UTC (+hhmm) + * - \%:z: the time zone as an offset from UTC (+hh:mm). + * This is a gnulib strftime() extension. Since: 2.38 + * - \%::z: the time zone as an offset from UTC (+hh:mm:ss). This is a + * gnulib strftime() extension. Since: 2.38 + * - \%:::z: the time zone as an offset from UTC, with : to necessary + * precision (e.g., -04, +05:30). This is a gnulib strftime() extension. Since: 2.38 + * - \%Z: the time zone or name or abbreviation + * - \%\%: a literal \% character * * Some conversion specifications can be modified by preceding the * conversion specifier by one or more modifier characters. The * following modifiers are supported for many of the numeric * conversions: - * <variablelist> - * <varlistentry> - * <term>O</term> - * <listitem> - * Use alternative numeric symbols, if the current locale - * supports those. - * </listitem> - * </varlistentry> - * <varlistentry> - * <term>_</term> - * <listitem> - * Pad a numeric result with spaces. - * This overrides the default padding for the specifier. - * </listitem> - * </varlistentry> - * <varlistentry> - * <term>-</term> - * <listitem> - * Do not pad a numeric result. - * This overrides the default padding for the specifier. - * </listitem> - * </varlistentry> - * <varlistentry> - * <term>0</term> - * <listitem> - * Pad a numeric result with zeros. - * This overrides the default padding for the specifier. - * </listitem> - * </varlistentry> - * </variablelist> + * + * - O: Use alternative numeric symbols, if the current locale supports those. + * - _: Pad a numeric result with spaces. This overrides the default padding + * for the specifier. + * - -: Do not pad a numeric result. This overrides the default padding + * for the specifier. + * - 0: Pad a numeric result with zeros. This overrides the default padding + * for the specifier. * * Returns: a newly allocated string formatted to the requested format - * or %NULL in the case that there was an error. The string - * should be freed with g_free(). + * or %NULL in the case that there was an error. The string + * should be freed with g_free(). * Since: 2.26 */ @@ -14140,12 +13816,11 @@ /** * g_date_to_struct_tm: - * @date: a #GDate to set the <structname>struct tm</structname> from - * @tm: <structname>struct tm</structname> to fill + * @date: a #GDate to set the struct tm from + * @tm: struct tm to fill * - * Fills in the date-related bits of a <structname>struct tm</structname> - * using the @date value. Initializes the non-date parts with something - * sane but meaningless. + * Fills in the date-related bits of a struct tm using the @date value. + * Initializes the non-date parts with something sane but meaningless. */ @@ -14238,7 +13913,7 @@ * @category: a locale category * * This is a variant of g_dgettext() that allows specifying a locale - * category instead of always using <envar>LC_MESSAGES</envar>. See g_dgettext() for + * category instead of always using `LC_MESSAGES`. See g_dgettext() for * more information about how this functions differs from calling * dcgettext() directly. * @@ -14286,17 +13961,19 @@ * * This function disables translations if and only if upon its first * call all the following conditions hold: - * <itemizedlist> - * <listitem>@domain is not %NULL</listitem> - * <listitem>textdomain() has been called to set a default text domain</listitem> - * <listitem>there is no translations available for the default text domain - * and the current locale</listitem> - * <listitem>current locale is not "C" or any English locales (those - * starting with "en_")</listitem> - * </itemizedlist> + * + * - @domain is not %NULL + * + * - textdomain() has been called to set a default text domain + * + * - there is no translations available for the default text domain + * and the current locale + * + * - current locale is not "C" or any English locales (those + * starting with "en_") * * Note that this behavior may not be desired for example if an application - * has its untranslated messages in a language other than English. In those + * has its untranslated messages in a language other than English. In those * cases the application should call textdomain() after initializing GTK+. * * Applications should normally not use this function directly, @@ -14370,8 +14047,7 @@ * factors. * * %NULL may also be returned in case of errors. On Unix, you can - * check <literal>errno</literal> to find out if %NULL was returned - * because of an error. + * check `errno` to find out if %NULL was returned because of an error. * * On Unix, the '.' and '..' entries are omitted, and the returned * name is in the on-disk encoding. @@ -14401,11 +14077,11 @@ * * Compares two #gpointer arguments and returns %TRUE if they are equal. * It can be passed to g_hash_table_new() as the @key_equal_func - * parameter, when using opaque pointers compared by pointer value as keys - * in a #GHashTable. + * parameter, when using opaque pointers compared by pointer value as + * keys in a #GHashTable. * - * This equality function is also appropriate for keys that are integers stored - * in pointers, such as <literal>GINT_TO_POINTER (n)</literal>. + * This equality function is also appropriate for keys that are integers + * stored in pointers, such as `GINT_TO_POINTER (n)`. * * Returns: %TRUE if the two keys match. */ @@ -14420,8 +14096,8 @@ * when using opaque pointers compared by pointer value as keys in a * #GHashTable. * - * This hash function is also appropriate for keys that are integers stored - * in pointers, such as <literal>GINT_TO_POINTER (n)</literal>. + * This hash function is also appropriate for keys that are integers + * stored in pointers, such as `GINT_TO_POINTER (n)`. * * Returns: a hash value corresponding to the key. */ @@ -14695,8 +14371,8 @@ * @err_no: an "errno" value * * Gets a #GFileError constant based on the passed-in @err_no. - * For example, if you pass in <literal>EEXIST</literal> this function returns - * #G_FILE_ERROR_EXIST. Unlike <literal>errno</literal> values, you can portably + * For example, if you pass in `EEXIST` this function returns + * #G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably * assume that all #GFileError values will exist. * * Normally a #GFileError value goes into a #GError returned @@ -14790,24 +14466,19 @@ * * This write is atomic in the sense that it is first written to a temporary * file which is then renamed to the final name. Notes: - * <itemizedlist> - * <listitem> - * On Unix, if @filename already exists hard links to @filename will break. - * Also since the file is recreated, existing permissions, access control - * lists, metadata etc. may be lost. If @filename is a symbolic link, - * the link itself will be replaced, not the linked file. - * </listitem> - * <listitem> - * On Windows renaming a file will not remove an existing file with the + * + * - On UNIX, if @filename already exists hard links to @filename will break. + * Also since the file is recreated, existing permissions, access control + * lists, metadata etc. may be lost. If @filename is a symbolic link, + * the link itself will be replaced, not the linked file. + * + * - On Windows renaming a file will not remove an existing file with the * new name, so on Windows there is a race condition between the existing * file being removed and the temporary file being renamed. - * </listitem> - * <listitem> - * On Windows there is no way to remove a file that is open to some + * + * - On Windows there is no way to remove a file that is open to some * process, or mapped into memory. Thus, this function will fail if * @filename already exists and is open. - * </listitem> - * </itemizedlist> * * If the call was successful, it returns %TRUE. If the call was not successful, * it returns %FALSE and sets @error. The error domain is #G_FILE_ERROR. @@ -14827,11 +14498,11 @@ * @test: bitfield of #GFileTest flags * * Returns %TRUE if any of the tests in the bitfield @test are - * %TRUE. For example, <literal>(G_FILE_TEST_EXISTS | - * G_FILE_TEST_IS_DIR)</literal> will return %TRUE if the file exists; - * the check whether it's a directory doesn't matter since the existence - * test is %TRUE. With the current set of available tests, there's no point - * passing in more than one test at a time. + * %TRUE. For example, `(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)` + * will return %TRUE if the file exists; the check whether it's a + * directory doesn't matter since the existence test is %TRUE. With + * the current set of available tests, there's no point passing in + * more than one test at a time. * * Apart from %G_FILE_TEST_IS_SYMLINK all tests follow symbolic links, * so for a symbolic link to a regular file g_file_test() will return @@ -14846,7 +14517,7 @@ * For example, you might think you could use %G_FILE_TEST_IS_SYMLINK * to know whether it is safe to write to a file without being * tricked into writing into a different location. It doesn't work! - * |[ + * |[<!-- language="C" --> * /* DON'T DO THIS */ * if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK)) * { @@ -14866,7 +14537,7 @@ * %G_FILE_TEST_IS_SYMLINK will always return %FALSE. Testing for * %G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and * its name indicates that it is executable, checking for well-known - * extensions and those listed in the <envar>PATHEXT</envar> environment variable. + * extensions and those listed in the `PATHEXT` environment variable. * * Returns: whether a test was %TRUE */ @@ -14991,7 +14662,9 @@ * g_filename_to_utf8: * @opsysstring: a string in the encoding for filenames * @len: the length of the string, or -1 if the string is - * nul-terminated<footnoteref linkend="nul-unsafe"/>. + * nul-terminated (Note that some encodings may allow nul + * bytes to occur inside strings. In that case, using -1 + * for the @len parameter is unsafe) * @bytes_read: location to store the number of bytes in the * input string that were successfully converted, or %NULL. * Even if the conversion was successful, this may be @@ -15026,15 +14699,15 @@ * * On Windows, if @program does not have a file type suffix, tries * with the suffixes .exe, .cmd, .bat and .com, and the suffixes in - * the <envar>PATHEXT</envar> environment variable. + * the `PATHEXT` environment variable. * * On Windows, it looks for the file in the same way as CreateProcess() * would. This means first in the directory where the executing * program was loaded from, then in the current directory, then in the * Windows 32-bit system directory, then in the Windows directory, and - * finally in the directories in the <envar>PATH</envar> environment - * variable. If the program is found, the return value contains the - * full name including the type suffix. + * finally in the directories in the `PATH` environment variable. If + * the program is found, the return value contains the full name + * including the type suffix. * * Returns: a newly-allocated string with the absolute path, or %NULL */ @@ -15043,24 +14716,22 @@ /** * g_fopen: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) - * @mode: a string describing the mode in which the file should be - * opened + * @mode: a string describing the mode in which the file should be opened * * A wrapper for the stdio fopen() function. The fopen() function * opens a file and associates a new stream with it. * * Because file descriptors are specific to the C library on Windows, - * and a file descriptor is partof the <type>FILE</type> struct, the - * <type>FILE</type> pointer returned by this function makes sense - * only to functions in the same C library. Thus if the GLib-using - * code uses a different C library than GLib does, the - * <type>FILE</type> pointer returned by this function cannot be - * passed to C library functions like fprintf() or fread(). + * and a file descriptor is part of the FILE struct, the FILE* returned + * by this function makes sense only to functions in the same C library. + * Thus if the GLib-using code uses a different C library than GLib does, + * the FILE* returned by this function cannot be passed to C library + * functions like fprintf() or fread(). * * See your C library manual for more details about fopen(). * - * Returns: A <type>FILE</type> pointer if the file was successfully - * opened, or %NULL if an error occurred + * Returns: A FILE* if the file was successfully opened, or %NULL if + * an error occurred * Since: 2.6 */ @@ -15152,8 +14823,7 @@ /** * g_freopen: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) - * @mode: a string describing the mode in which the file should be - * opened + * @mode: a string describing the mode in which the file should be opened * @stream: (allow-none): an existing stream which will be reused, or %NULL * * A wrapper for the POSIX freopen() function. The freopen() function @@ -15161,8 +14831,8 @@ * * See your C library manual for more details about freopen(). * - * Returns: A <literal>FILE</literal> pointer if the file was successfully - * opened, or %NULL if an error occurred. + * Returns: A FILE* if the file was successfully opened, or %NULL if + * an error occurred. * Since: 2.6 */ @@ -15277,24 +14947,23 @@ * representation of a filename, see g_filename_display_name(). * * On Unix, the character sets are determined by consulting the - * environment variables <envar>G_FILENAME_ENCODING</envar> and - * <envar>G_BROKEN_FILENAMES</envar>. On Windows, the character set - * used in the GLib API is always UTF-8 and said environment variables - * have no effect. - * - * <envar>G_FILENAME_ENCODING</envar> may be set to a comma-separated list - * of character set names. The special token "@locale" is taken to - * mean the character set for the <link linkend="setlocale">current - * locale</link>. If <envar>G_FILENAME_ENCODING</envar> is not set, but - * <envar>G_BROKEN_FILENAMES</envar> is, the character set of the current - * locale is taken as the filename encoding. If neither environment variable + * environment variables `G_FILENAME_ENCODING` and `G_BROKEN_FILENAMES`. + * On Windows, the character set used in the GLib API is always UTF-8 + * and said environment variables have no effect. + * + * `G_FILENAME_ENCODING` may be set to a comma-separated list of + * character set names. The special token "@locale" is taken + * to mean the character set for the <link linkend="setlocale">current + * locale</link>. If `G_FILENAME_ENCODING` is not set, but + * `G_BROKEN_FILENAMES` is, the character set of the current locale + * is taken as the filename encoding. If neither environment variable * is set, UTF-8 is taken as the filename encoding, but the character * set of the current locale is also put in the list of encodings. * * The returned @charsets belong to GLib and must not be freed. * * Note that on Unix, regardless of the locale character set or - * <envar>G_FILENAME_ENCODING</envar> value, the actual file names present + * `G_FILENAME_ENCODING` value, the actual file names present * on a system might be in any random encoding or just gibberish. * * Returns: %TRUE if the filename encoding is UTF-8. @@ -15308,28 +14977,23 @@ * Gets the current user's home directory. * * As with most UNIX tools, this function will return the value of the - * <envar>HOME</envar> environment variable if it is set to an existing - * absolute path name, falling back to the <filename>passwd</filename> - * file in the case that it is unset. - * - * 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> + * `HOME` environment variable if it is set to an existing absolute path + * name, falling back to the `passwd` file in the case that it is unset. + * + * If the path given in `HOME` is non-absolute, does not exist, or is + * not a directory, the result is undefined. + * + * Before version 2.36 this function would ignore the `HOME` environment + * variable, taking the value from the `passwd` database instead. This was + * changed to increase the compatibility of GLib with other programs (and + * the XDG basedir specification) and to increase testability of programs + * based on GLib (by making it easier to run them from test frameworks). + * + * If your program has a strong requirement for either the new or the + * old behaviour (and if you don't wish to increase your GLib + * dependency to ensure that the new behaviour is in effect) then you + * should either directly check the `HOME` environment variable yourself + * or unset it before calling any functions in GLib. * * Returns: the current user's home directory */ @@ -15367,9 +15031,9 @@ * For example, if LANGUAGE=de:en_US, then the returned list is * "de", "en_US", "en", "C". * - * This function consults the environment variables <envar>LANGUAGE</envar>, - * <envar>LC_ALL</envar>, <envar>LC_MESSAGES</envar> and <envar>LANG</envar> - * to find the list of locales specified by the user. + * This function consults the environment variables `LANGUAGE`, `LC_ALL`, + * `LC_MESSAGES` and `LANG` to find the list of locales specified by the + * user. * * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib * that must not be modified or freed. @@ -15389,7 +15053,7 @@ * For example, if @locale is "fr_BE", then the returned list * is "fr_BE", "fr". * - * If you need the list of variants for the <emphasis>current locale</emphasis>, + * If you need the list of variants for the current locale, * use g_get_language_names(). * * Returns: (transfer full) (array zero-terminated=1) (element-type utf8): a newly @@ -15404,12 +15068,12 @@ * * Queries the system monotonic time, if available. * - * On POSIX systems with clock_gettime() and <literal>CLOCK_MONOTONIC</literal> this call + * On POSIX systems with clock_gettime() and `CLOCK_MONOTONIC` this call * is a very shallow wrapper for that. Otherwise, we make a best effort * that probably involves returning the wall clock time (with at least * microsecond accuracy, subject to the limitations of the OS kernel). * - * It's important to note that POSIX <literal>CLOCK_MONOTONIC</literal> does + * It's important to note that POSIX `CLOCK_MONOTONIC` does * not count time spent while the machine is suspended. * * On Windows, "limitations of the OS kernel" is a rather substantial @@ -15440,24 +15104,25 @@ /** * g_get_prgname: * - * Gets the name of the program. This name should <emphasis>not</emphasis> - * be localized, contrast with g_get_application_name(). - * (If you are using GDK or GTK+ the program name is set in gdk_init(), + * Gets the name of the program. This name should not be localized, + * in contrast to g_get_application_name(). + * + * If you are using GDK or GTK+ the program name is set in gdk_init(), * which is called by gtk_init(). The program name is found by taking - * the last component of <literal>argv[0]</literal>.) + * the last component of @argv[0]. * * Returns: the name of the program. The returned string belongs - * to GLib and must not be modified or freed. + * to GLib and must not be modified or freed. */ /** * g_get_real_name: * - * Gets the real name of the user. This usually comes from the user's entry - * in the <filename>passwd</filename> file. The encoding of the returned - * string is system-defined. (On Windows, it is, however, always UTF-8.) - * If the real user name cannot be determined, the string "Unknown" is + * Gets the real name of the user. This usually comes from the user's + * entry in the `passwd` file. The encoding of the returned string is + * system-defined. (On Windows, it is, however, always UTF-8.) If the + * real user name cannot be determined, the string "Unknown" is * returned. * * Returns: the user's real name. @@ -15488,10 +15153,10 @@ * Returns an ordered list of base directories in which to access * system-wide configuration information. * - * On UNIX platforms this is determined using the mechanisms described in - * the <ulink url="http://www.freedesktop.org/Standards/basedir-spec"> - * XDG Base Directory Specification</ulink>. - * In this case the list of directories retrieved will be XDG_CONFIG_DIRS. + * On UNIX platforms this is determined using the mechanisms described + * in the + * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). + * In this case the list of directories retrieved will be `XDG_CONFIG_DIRS`. * * On Windows is the directory that contains application data for all users. * A typical path is C:\Documents and Settings\All Users\Application Data. @@ -15512,9 +15177,9 @@ * Returns an ordered list of base directories in which to access * system-wide application data. * - * On UNIX platforms this is determined using the mechanisms described in - * the <ulink url="http://www.freedesktop.org/Standards/basedir-spec"> - * XDG Base Directory Specification</ulink> + * On UNIX platforms this is determined using the mechanisms described + * in the + * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec) * In this case the list of directories retrieved will be XDG_DATA_DIRS. * * On Windows the first elements in the list are the Application Data @@ -15550,17 +15215,18 @@ * * Gets the directory to use for temporary files. * - * On UNIX, this is taken from the <envar>TMPDIR</envar> environment - * variable. If the variable is not set, <literal>P_tmpdir</literal> is - * used, as defined by the system C library. Failing that, a hard-coded - * default of "/tmp" is returned. + * On UNIX, this is taken from the `TMPDIR` environment variable. + * If the variable is not set, `P_tmpdir` is + * used, as defined by the system C library. Failing that, a + * hard-coded default of "/tmp" is returned. * - * On Windows, the <envar>TEMP</envar> environment variable is used, - * with the root directory of the Windows installation (eg: "C:\") used + * On Windows, the `TEMP` environment variable is used, with the + * root directory of the Windows installation (eg: "C:\") used * as a default. * - * The encoding of the returned string is system-defined. On Windows, it - * is always UTF-8. The return value is never %NULL or the empty string. + * The encoding of the returned string is system-defined. On Windows, + * it is always UTF-8. The return value is never %NULL or the empty + * string. * * Returns: the directory to use for temporary files. */ @@ -15572,9 +15238,9 @@ * Returns a base directory in which to store non-essential, cached * data specific to particular user. * - * On UNIX platforms this is determined using the mechanisms described in - * the <ulink url="http://www.freedesktop.org/Standards/basedir-spec"> - * XDG Base Directory Specification</ulink>. + * On UNIX platforms this is determined using the mechanisms described + * in the + * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). * In this case the directory retrieved will be XDG_CACHE_HOME. * * On Windows is the directory that serves as a common repository for @@ -15594,10 +15260,10 @@ * Returns a base directory in which to store user-specific application * configuration information such as user preferences and settings. * - * On UNIX platforms this is determined using the mechanisms described in - * the <ulink url="http://www.freedesktop.org/Standards/basedir-spec"> - * XDG Base Directory Specification</ulink>. - * In this case the directory retrieved will be XDG_CONFIG_HOME. + * On UNIX platforms this is determined using the mechanisms described + * in the + * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). + * In this case the directory retrieved will be `XDG_CONFIG_HOME`. * * On Windows this is the folder to use for local (as opposed to * roaming) application data. See documentation for @@ -15616,10 +15282,10 @@ * Returns a base directory in which to access application data such * as icons that is customized for a particular user. * - * On UNIX platforms this is determined using the mechanisms described in - * the <ulink url="http://www.freedesktop.org/Standards/basedir-spec"> - * XDG Base Directory Specification</ulink>. - * In this case the directory retrieved will be XDG_DATA_HOME. + * On UNIX platforms this is determined using the mechanisms described + * in the + * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). + * In this case the directory retrieved will be `XDG_DATA_HOME`. * * On Windows this is the folder to use for local (as opposed to * roaming) application data. See documentation for @@ -15650,10 +15316,11 @@ * Returns a directory that is unique to the current user on the local * system. * - * On UNIX platforms this is determined using the mechanisms described in - * the <ulink url="http://www.freedesktop.org/Standards/basedir-spec"> - * XDG Base Directory Specification</ulink>. This is the directory - * specified in the <envar>XDG_RUNTIME_DIR</envar> environment variable. + * On UNIX platforms this is determined using the mechanisms described + * in the + * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). + * This is the directory + * specified in the `XDG_RUNTIME_DIR` environment variable. * In the case that this variable is not set, GLib will issue a warning * message to stderr and return the value of g_get_user_cache_dir(). * @@ -15673,10 +15340,10 @@ * * Returns the full path of a special directory using its logical id. * - * On Unix this is done using the XDG special user directories. + * On UNIX this is done using the XDG special user directories. * For compatibility with existing practise, %G_USER_DIRECTORY_DESKTOP - * falls back to <filename>$HOME/Desktop</filename> when XDG special - * user directories have not been set up. + * falls back to `$HOME/Desktop` when XDG special user directories have + * not been set up. * * Depending on the platform, the user might be able to change the path * of the special directory without requiring the session to restart; GLib @@ -15935,7 +15602,7 @@ * Initializes a key/value pair iterator and associates it with * @hash_table. Modifying the hash table after calling this function * invalidates the returned iterator. - * |[ + * |[<!-- language="C" --> * GHashTableIter iter; * gpointer key, value; * @@ -16505,7 +16172,7 @@ * g_hook_list_init: * @hook_list: a #GHookList * @hook_size: the size of each element in the #GHookList, - * typically <literal>sizeof (GHook)</literal> + * typically `sizeof (GHook)`. * * Initializes a #GHookList. * This must be called before the #GHookList is used. @@ -16887,9 +16554,9 @@ * parameter, when using non-%NULL pointers to integers as keys in a * #GHashTable. * - * Note that this function acts on pointers to #gint, not on #gint directly: - * if your hash table's keys are of the form - * <literal>GINT_TO_POINTER (n)</literal>, use g_direct_equal() instead. + * Note that this function acts on pointers to #gint, not on #gint + * directly: if your hash table's keys are of the form + * `GINT_TO_POINTER (n)`, use g_direct_equal() instead. * * Returns: %TRUE if the two keys match. */ @@ -16903,9 +16570,9 @@ * It can be passed to g_hash_table_new() as the @hash_func parameter, * when using non-%NULL pointers to integer values as keys in a #GHashTable. * - * Note that this function acts on pointers to #gint, not on #gint directly: - * if your hash table's keys are of the form - * <literal>GINT_TO_POINTER (n)</literal>, use g_direct_hash() instead. + * Note that this function acts on pointers to #gint, not on #gint + * directly: if your hash table's keys are of the form + * `GINT_TO_POINTER (n)`, use g_direct_hash() instead. * * Returns: a hash value corresponding to the key. */ @@ -16986,9 +16653,9 @@ /** * g_io_channel_error_from_errno: - * @en: an <literal>errno</literal> error number, e.g. <literal>EINVAL</literal> + * @en: an `errno` error number, e.g. `EINVAL` * - * Converts an <literal>errno</literal> error number to a #GIOChannelError. + * Converts an `errno` error number to a #GIOChannelError. * * Returns: a #GIOChannelError error number, e.g. * %G_IO_CHANNEL_ERROR_INVAL. @@ -17347,43 +17014,34 @@ * * The encoding can only be set if one of the following conditions * is true: - * <itemizedlist> - * <listitem><para> - * The channel was just created, and has not been written to or read - * from yet. - * </para></listitem> - * <listitem><para> - * The channel is write-only. - * </para></listitem> - * <listitem><para> - * The channel is a file, and the file pointer was just - * repositioned by a call to g_io_channel_seek_position(). - * (This flushes all the internal buffers.) - * </para></listitem> - * <listitem><para> - * The current encoding is %NULL or UTF-8. - * </para></listitem> - * <listitem><para> - * One of the (new API) read functions has just returned %G_IO_STATUS_EOF - * (or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL). - * </para></listitem> - * <listitem><para> - * One of the functions g_io_channel_read_chars() or + * + * - The channel was just created, and has not been written to or read from yet. + * + * - The channel is write-only. + * + * - The channel is a file, and the file pointer was just repositioned + * by a call to g_io_channel_seek_position(). (This flushes all the + * internal buffers.) + * + * - The current encoding is %NULL or UTF-8. + * + * - One of the (new API) read functions has just returned %G_IO_STATUS_EOF + * (or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL). + * + * - One of the functions g_io_channel_read_chars() or * g_io_channel_read_unichar() has returned %G_IO_STATUS_AGAIN or * %G_IO_STATUS_ERROR. This may be useful in the case of * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. * Returning one of these statuses from g_io_channel_read_line(), * g_io_channel_read_line_string(), or g_io_channel_read_to_end() - * does <emphasis>not</emphasis> guarantee that the encoding can - * be changed. - * </para></listitem> - * </itemizedlist> + * does not guarantee that the encoding can be changed. + * * Channels which do not meet one of the above conditions cannot call * g_io_channel_seek_position() with an offset of %G_SEEK_CUR, and, if * they are "seekable", cannot call g_io_channel_write_chars() after * calling one of the API "read" functions. * - * Returns: %G_IO_STATUS_NORMAL if the encoding was successfully set. + * Returns: %G_IO_STATUS_NORMAL if the encoding was successfully set */ @@ -17995,16 +17653,15 @@ * 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. * - * Returns: %TRUE if @key is a part of @group_name, %FALSE - * otherwise. + * Returns: %TRUE if @key is a part of @group_name, %FALSE otherwise * Since: 2.6 */ @@ -18453,7 +18110,7 @@ * to avoid the inefficiency is to use g_list_prepend() and reverse * the list with g_list_reverse() when all elements have been added. * - * |[ + * |[<!-- language="C" --> * /* Notice that these are initialized to the empty list. */ * GList *string_list = NULL, *number_list = NULL; * @@ -18482,7 +18139,7 @@ * * This function is for example used to move an element in the list. * The following example moves an element to the top of the list: - * |[ + * |[<!-- language="C" --> * list = g_list_remove_link (list, llink); * list = g_list_concat (llink, list); * ]| @@ -18497,12 +18154,10 @@ * * 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 */ @@ -18525,12 +18180,12 @@ * if the copy function takes only one argument. * * For instance, if @list holds a list of GObjects, you can do: - * |[ + * |[<!-- language="C" --> * another_list = g_list_copy_deep (list, (GCopyFunc) g_object_ref, NULL); * ]| * * And, to entirely free the new list, you could do: - * |[ + * |[<!-- language="C" --> * g_list_free_full (another_list, g_object_unref); * ]| * @@ -18608,13 +18263,10 @@ * @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. */ @@ -18698,12 +18350,10 @@ * 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 */ @@ -18722,12 +18372,10 @@ * 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 * Since: 2.10 @@ -18751,11 +18399,9 @@ * * 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 */ @@ -18832,7 +18478,7 @@ * Note that the return value is the new start of the list, * which will have changed, so make sure you store the new value. * - * |[ + * |[<!-- language="C" --> * /* Notice that it is initialized to the empty list. */ * GList *list = NULL; * @@ -18840,10 +18486,8 @@ * 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 @@ -18902,7 +18546,7 @@ * This function is for example used to move an element in the list * (see the example for g_list_concat()) or to remove an element in * the list before freeing its data: - * |[ + * |[<!-- language="C" --> * list = g_list_remove_link (list, llink); * free_some_data_that_may_access_the_list_again (llink->data); * g_list_free (llink); @@ -18974,7 +18618,9 @@ * g_locale_from_utf8: * @utf8string: a UTF-8 encoded string * @len: the length of the string, or -1 if the string is - * nul-terminated<footnoteref linkend="nul-unsafe"/>. + * nul-terminated (Note that some encodings may allow nul + * bytes to occur inside strings. In that case, using -1 + * for the @len parameter is unsafe) * @bytes_read: location to store the number of bytes in the * input string that were successfully converted, or %NULL. * Even if the conversion was successful, this may be @@ -19003,7 +18649,9 @@ * @opsysstring: a string in the encoding of the current locale. On Windows * this means the system codepage. * @len: the length of the string, or -1 if the string is - * nul-terminated<footnoteref linkend="nul-unsafe"/>. + * nul-terminated (Note that some encodings may allow nul + * bytes to occur inside strings. In that case, using -1 + * for the @len parameter is unsafe) * @bytes_read: location to store the number of bytes in the * input string that were successfully converted, or %NULL. * Even if the conversion was successful, this may be @@ -19063,23 +18711,14 @@ * * The behavior of this log handler can be influenced by a number of * environment variables: - * <variablelist> - * <varlistentry> - * <term><envar>G_MESSAGES_PREFIXED</envar></term> - * <listitem> - * A :-separated list of log levels for which messages should - * be prefixed by the program name and PID of the aplication. - * </listitem> - * </varlistentry> - * <varlistentry> - * <term><envar>G_MESSAGES_DEBUG</envar></term> - * <listitem> - * A space-separated list of log domains for which debug and - * informational messages are printed. By default these - * messages are not printed. - * </listitem> - * </varlistentry> - * </variablelist> + * + * - `G_MESSAGES_PREFIXED`: A :-separated list of log levels for which + * messages should be prefixed by the program name and PID of the + * aplication. + * + * - `G_MESSAGES_DEBUG`: A space-separated list of log domains for + * which debug and informational messages are printed. By default + * these messages are not printed. * * stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL, * %G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for @@ -19108,8 +18747,8 @@ * %G_LOG_LEVEL_ERROR is always fatal. * * You can also make some message levels fatal at runtime by setting - * the <envar>G_DEBUG</envar> environment variable (see - * <ulink url="glib-running.html">Running GLib Applications</ulink>). + * the `G_DEBUG` environment variable (see + * [Running GLib Applications](glib-running.html)). * * Returns: the old fatal mask */ @@ -19162,31 +18801,24 @@ * you want to set a handler for this log level you must combine it with * #G_LOG_FLAG_FATAL. * - * <example> - * <title>Adding a log handler for all warning messages in the default - * (application) domain</title> - * <programlisting> + * Here is an example for adding a log handler for all warning messages + * in the default domain: + * |[<!-- language="C" --> * g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL * | G_LOG_FLAG_RECURSION, my_log_handler, NULL); - * </programlisting> - * </example> + * ]| * - * <example> - * <title>Adding a log handler for all critical messages from GTK+</title> - * <programlisting> + * This example adds a log handler for all critical messages from GTK+: + * |[<!-- language="C" --> * g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL * | G_LOG_FLAG_RECURSION, my_log_handler, NULL); - * </programlisting> - * </example> + * ]| * - * <example> - * <title>Adding a log handler for <emphasis>all</emphasis> messages from - * GLib</title> - * <programlisting> + * This example adds a log handler for all messages from GLib: + * |[<!-- language="C" --> * g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL * | G_LOG_FLAG_RECURSION, my_log_handler, NULL); - * </programlisting> - * </example> + * ]| * * Returns: the id of the new handler */ @@ -19213,8 +18845,8 @@ /** * g_lstat: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) - * @buf: a pointer to a <structname>stat</structname> struct, which - * will be filled with the file information + * @buf: a pointer to a stat struct, which will be filled with the file + * information * * A wrapper for the POSIX lstat() function. The lstat() function is * like stat() except that in the case of symbolic links, it returns @@ -19224,8 +18856,8 @@ * * See your C library manual for more details about lstat(). * - * Returns: 0 if the information was successfully retrieved, -1 if an error - * occurred + * Returns: 0 if the information was successfully retrieved, + * -1 if an error occurred * Since: 2.6 */ @@ -19354,7 +18986,7 @@ * operations that want to be able to be run in contexts other than * the default one should call this method or * g_main_context_ref_thread_default() to get a #GMainContext to add - * their #GSource<!-- -->s to. (Note that even in single-threaded + * their #GSources to. (Note that even in single-threaded * programs applications may sometimes want to temporarily push a * non-default context, so it is not safe to assume that this will * always return %NULL if you are running in the default thread.) @@ -19512,10 +19144,9 @@ * started in this thread to run under @context and deliver their * results to its main loop, rather than running under the global * default context in the main thread. Note that calling this function - * changes the context returned by - * g_main_context_get_thread_default(), <emphasis>not</emphasis> the - * one returned by g_main_context_default(), so it does not affect the - * context used by functions like g_idle_add(). + * changes the context returned by g_main_context_get_thread_default(), + * not the one returned by g_main_context_default(), so it does not affect + * the context used by functions like g_idle_add(). * * Normally you would call this function shortly after creating a new * thread, passing it a #GMainContext which will be run by a @@ -19660,7 +19291,7 @@ * Another related use for this function is when implementing a main * loop with a termination condition, computed from multiple threads: * - * |[ + * |[<!-- language="C" --> * #define NUM_TASKS 10 * static volatile gint tasks_remaining = NUM_TASKS; * ... @@ -19670,7 +19301,7 @@ * ]| * * Then in a thread: - * |[ + * |[<!-- language="C" --> * perform_work(); * * if (g_atomic_int_dec_and_test (&tasks_remaining)) @@ -19703,7 +19334,7 @@ * This function is useful in a situation like the following: * Imagine an extremely simple "garbage collected" system. * - * |[ + * |[<!-- language="C" --> * static GList *free_list; * * gpointer @@ -19740,7 +19371,7 @@ * doesn't work, since the idle function could be called from a * recursive callback. This can be fixed by using g_main_depth() * - * |[ + * |[<!-- language="C" --> * gpointer * allocate_memory (gsize size) * { @@ -19785,23 +19416,14 @@ * many things that the user could do. Instead, you can use the * following techniques: * - * <orderedlist> - * <listitem> - * <para> - * Use gtk_widget_set_sensitive() or modal dialogs to prevent - * the user from interacting with elements while the main - * loop is recursing. - * </para> - * </listitem> - * <listitem> - * <para> - * Avoid main loop recursion in situations where you can't handle - * arbitrary callbacks. Instead, structure your code so that you - * simply return to the main loop and then get called again when - * there is more work to do. - * </para> - * </listitem> - * </orderedlist> + * 1. Use gtk_widget_set_sensitive() or modal dialogs to prevent + * the user from interacting with elements while the main + * loop is recursing. + * + * 2. Avoid main loop recursion in situations where you can't handle + * arbitrary callbacks. Instead, structure your code so that you + * simply return to the main loop and then get called again when + * there is more work to do. * * Returns: The main loop recursion level in the current thread */ @@ -20326,7 +19948,7 @@ * As an example, see the following implementation of a simple * parser that counts the number of tags encountered. * - * |[ + * |[<!-- language="C" --> * typedef struct * { * gint tag_count; @@ -20368,7 +19990,7 @@ * In order to allow this parser to be easily used as a subparser, the * following interface is provided: * - * |[ + * |[<!-- language="C" --> * void * start_counting (GMarkupParseContext *context) * { @@ -20393,7 +20015,7 @@ * * The subparser would then be used as follows: * - * |[ + * |[<!-- language="C" --> * static void start_element (context, element_name, ...) * { * if (strcmp (element_name, "count-these") == 0) @@ -20449,15 +20071,15 @@ * output, without having to worry that the strings * might themselves contain markup. * - * |[ - * const char *store = "Fortnum & Mason"; + * |[<!-- language="C" --> + * const char *store = "Fortnum & Mason"; * const char *item = "Tea"; * char *output; - * - * output = g_markup_printf_escaped ("<purchase>" - * "<store>%s</store>" - * "<item>%s</item>" - * "</purchase>", + * + * output = g_markup_printf_escaped ("<purchase>" + * "<store>%s</store>" + * "<item>%s</item>" + * "</purchase>", * store, item); * ]| * @@ -20516,7 +20138,7 @@ * @match_info: #GMatchInfo structure * @match_num: number of the sub expression * - * Retrieves the text matching the @match_num<!-- -->'th capturing + * Retrieves the text matching the @match_num'th capturing * parentheses. 0 is the full text of the match, 1 is the first paren * set, 2 the second, and so on. * @@ -20618,7 +20240,7 @@ * @end_pos: (out) (allow-none): pointer to location where to store * the end position, or %NULL * - * Retrieves the position in bytes of the @match_num<!-- -->'th capturing + * Retrieves the position in bytes of the @match_num'th capturing * parentheses. 0 is the full text of the match, 1 is the first * paren set, 2 the second, and so on. * @@ -20730,7 +20352,7 @@ * There were formerly some restrictions on the pattern for partial matching. * The restrictions no longer apply. * - * See <ulink>man:pcrepartial</ulink> for more information on partial matching. + * See pcrepartial(3) for more information on partial matching. * * Returns: %TRUE if the match was partial, %FALSE otherwise * Since: 2.14 @@ -20791,8 +20413,8 @@ /** * g_mem_gc_friendly: * - * This variable is %TRUE if the <envar>G_DEBUG</envar> environment variable - * includes the key <literal>gc-friendly</literal>. + * This variable is %TRUE if the `G_DEBUG` environment variable + * includes the key `gc-friendly`. */ @@ -20831,13 +20453,17 @@ * g_mem_set_vtable: * @vtable: table of memory allocation routines. * - * Sets the #GMemVTable to use for memory allocation. You can use this to provide - * custom memory allocation routines. <emphasis>This function must be called - * before using any other GLib functions.</emphasis> The @vtable only needs to - * provide malloc(), realloc(), and free() functions; GLib can provide default - * implementations of the others. The malloc() and realloc() implementations - * should return %NULL on failure, GLib will handle error-checking for you. - * @vtable is copied, so need not persist after this function has been called. + * Sets the #GMemVTable to use for memory allocation. You can use this + * to provide custom memory allocation routines. + * + * The @vtable only needs to provide malloc(), realloc(), and free() + * functions; GLib can provide default implementations of the others. + * The malloc() and realloc() implementations should return %NULL on + * failure, GLib will handle error-checking for you. @vtable is copied, + * so need not persist after this function has been called. + * + * Note that this function must be called before using any other GLib + * functions. */ @@ -21035,7 +20661,7 @@ * It is not necessary to initialize a mutex that has been * statically allocated. * - * |[ + * |[<!-- language="C" --> * typedef struct { * GMutex m; * ... @@ -21065,10 +20691,10 @@ * 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). */ @@ -21080,11 +20706,10 @@ * 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 */ @@ -21448,19 +21073,19 @@ /** * g_on_error_query: - * @prg_name: the program name, needed by <command>gdb</command> - * for the [S]tack trace option. If @prg_name is %NULL, g_get_prgname() - * is called to get the program name (which will work correctly if - * gdk_init() or gtk_init() has been called) + * @prg_name: the program name, needed by gdb for the "[S]tack trace" + * option. If @prg_name is %NULL, g_get_prgname() is called to get + * the program name (which will work correctly if gdk_init() or + * gtk_init() has been called) * * Prompts the user with - * <computeroutput>[E]xit, [H]alt, show [S]tack trace or [P]roceed</computeroutput>. + * `[E]xit, [H]alt, show [S]tack trace or [P]roceed`. * This function is intended to be used for debugging use only. * The following example shows how it can be used together with * the g_log() functions. * - * |[ - * #include <glib.h> + * |[<!-- language="C" --> + * #include <glib.h> * * static void * log_handler (const gchar *log_domain, @@ -21482,17 +21107,17 @@ * G_LOG_LEVEL_CRITICAL, * log_handler, * NULL); - * /* ... */ + * ... * ]| * - * If [E]xit is selected, the application terminates with a call - * to <literal>_exit(0)</literal>. + * If "[E]xit" is selected, the application terminates with a call + * to _exit(0). * - * If [S]tack trace is selected, g_on_error_stack_trace() is called. - * This invokes <command>gdb</command>, which attaches to the current - * process and shows a stack trace. The prompt is then shown again. + * If "[S]tack" trace is selected, g_on_error_stack_trace() is called. + * This invokes gdb, which attaches to the current process and shows + * a stack trace. The prompt is then shown again. * - * If [P]roceed is selected, the function returns. + * If "[P]roceed" is selected, the function returns. * * This function may cause different actions on non-UNIX platforms. */ @@ -21500,14 +21125,14 @@ /** * g_on_error_stack_trace: - * @prg_name: the program name, needed by <command>gdb</command> - * for the [S]tack trace option. + * @prg_name: the program name, needed by gdb for the "[S]tack trace" + * option * - * Invokes <command>gdb</command>, which attaches to the current - * process and shows a stack trace. Called by g_on_error_query() - * when the [S]tack trace option is selected. You can get the current - * process's "program name" with g_get_prgname(), assuming that you - * have called gtk_init() or gdk_init(). + * Invokes gdb, which attaches to the current process and shows a + * stack trace. Called by g_on_error_query() when the "[S]tack trace" + * option is selected. You can get the current process's program name + * with g_get_prgname(), assuming that you have called gtk_init() or + * gdk_init(). * * This function may cause different actions on non-UNIX platforms. */ @@ -21534,7 +21159,7 @@ * Calling g_once() recursively on the same #GOnce struct in * @func will lead to a deadlock. * - * |[ + * |[<!-- language="C" --> * gpointer * get_debug_flags (void) * { @@ -21564,17 +21189,17 @@ * blocked until initialization completed. To be used in constructs * like this: * - * |[ + * |[<!-- language="C" --> * static gsize initialization_value = 0; * - * if (g_once_init_enter (&initialization_value)) + * if (g_once_init_enter (&initialization_value)) * { - * gsize setup_value = 42; /** initialization code here **/ + * gsize setup_value = 42; /* initialization code here */ * - * g_once_init_leave (&initialization_value, setup_value); + * g_once_init_leave (&initialization_value, setup_value); * } * - * /** use initialization_value here **/ + * /* use initialization_value here */ * ]| * * Returns: %TRUE if the initialization section should be entered, @@ -21623,8 +21248,9 @@ * * See your C library manual for more details about open(). * - * Returns: a new file descriptor, or -1 if an error occurred. The - * return value can be used exactly like the return value from open(). + * Returns: a new file descriptor, or -1 if an error occurred. + * The return value can be used exactly like the return value + * from open(). * Since: 2.6 */ @@ -21647,9 +21273,9 @@ /** * g_option_context_add_main_entries: * @context: a #GOptionContext - * @entries: a %NULL-terminated array of #GOptionEntry<!-- -->s + * @entries: a %NULL-terminated array of #GOptionEntrys * @translation_domain: (allow-none): a translation domain to use for translating - * the <option>--help</option> output for the options in @entries + * the `--help` output for the options in @entries * with gettext(), or %NULL * * A convenience function which creates a main group if it doesn't @@ -21691,12 +21317,12 @@ * @group: (allow-none): the #GOptionGroup to create help for, or %NULL * * Returns a formatted, translated help text for the given context. - * To obtain the text produced by <option>--help</option>, call - * <literal>g_option_context_get_help (context, TRUE, NULL)</literal>. - * To obtain the text produced by <option>--help-all</option>, call - * <literal>g_option_context_get_help (context, FALSE, NULL)</literal>. + * To obtain the text produced by `--help`, call + * `g_option_context_get_help (context, TRUE, NULL)`. + * To obtain the text produced by `--help-all`, call + * `g_option_context_get_help (context, FALSE, NULL)`. * To obtain the help text for an option group, call - * <literal>g_option_context_get_help (context, FALSE, group)</literal>. + * `g_option_context_get_help (context, FALSE, group)`. * * Returns: A newly allocated string containing the help text * Since: 2.14 @@ -21707,7 +21333,7 @@ * g_option_context_get_help_enabled: * @context: a #GOptionContext * - * Returns whether automatic <option>--help</option> generation + * Returns whether automatic `--help` generation * is turned on for @context. See g_option_context_set_help_enabled(). * * Returns: %TRUE if automatic help generation is turned on. @@ -21754,9 +21380,8 @@ /** * g_option_context_new: * @parameter_string: (allow-none): a string which is displayed in - * the first line of <option>--help</option> output, after the - * usage summary - * <literal><replaceable>programname</replaceable> [OPTION...]</literal> + * the first line of `--help` output, after the usage summary + * `programname [OPTION...]` * * Creates a new option context. * @@ -21803,11 +21428,11 @@ * or some of the options after it start with '-'. In case * of an error, @argc and @argv are left unmodified. * - * If automatic <option>--help</option> support is enabled + * If automatic `--help` support is enabled * (see g_option_context_set_help_enabled()), and the * @argv array contains one of the recognized help options, * this function will produce help output to stdout and - * call <literal>exit (0)</literal>. + * call `exit (0)`. * * Note that function depends on the * <link linkend="setlocale">current locale</link> for @@ -21853,12 +21478,11 @@ /** * g_option_context_set_description: * @context: a #GOptionContext - * @description: (allow-none): a string to be shown in <option>--help</option> output + * @description: (allow-none): a string to be shown in `--help` output * after the list of options, or %NULL * - * Adds a string to be displayed in <option>--help</option> output - * after the list of options. This text often includes a bug reporting - * address. + * Adds a string to be displayed in `--help` output after the list + * of options. This text often includes a bug reporting address. * * Note that the summary is translated (see * g_option_context_set_translate_func()). @@ -21870,14 +21494,12 @@ /** * g_option_context_set_help_enabled: * @context: a #GOptionContext - * @help_enabled: %TRUE to enable <option>--help</option>, %FALSE to disable it + * @help_enabled: %TRUE to enable `--help`, %FALSE to disable it * - * Enables or disables automatic generation of <option>--help</option> - * output. By default, g_option_context_parse() recognizes - * <option>--help</option>, <option>-h</option>, - * <option>-?</option>, <option>--help-all</option> - * and <option>--help-</option><replaceable>groupname</replaceable> and creates - * suitable output to stdout. + * Enables or disables automatic generation of `--help` output. + * By default, g_option_context_parse() recognizes `--help`, `-h`, + * `-?`, `--help-all` and `--help-groupname` and creates suitable + * output to stdout. * * Since: 2.6 */ @@ -21909,7 +21531,7 @@ * Sets a #GOptionGroup as main group of the @context. * This has the same effect as calling g_option_context_add_group(), * the only difference is that the options in the main group are - * treated differently when generating <option>--help</option> output. + * treated differently when generating `--help` output. * * Since: 2.6 */ @@ -21918,12 +21540,11 @@ /** * g_option_context_set_summary: * @context: a #GOptionContext - * @summary: (allow-none): a string to be shown in <option>--help</option> output + * @summary: (allow-none): a string to be shown in `--help` output * before the list of options, or %NULL * - * Adds a string to be displayed in <option>--help</option> output - * before the list of options. This is typically a summary of the - * program functionality. + * Adds a string to be displayed in `--help` output before the list + * of options. This is typically a summary of the program functionality. * * Note that the summary is translated (see * g_option_context_set_translate_func() and @@ -21941,8 +21562,8 @@ * @destroy_notify: (allow-none): a function which gets called to free @data, or %NULL * * Sets the function which is used to translate the contexts - * user-visible strings, for <option>--help</option> output. - * If @func is %NULL, strings are not translated. + * user-visible strings, for `--help` output. If @func is %NULL, + * strings are not translated. * * Note that option groups have their own translation functions, * this function only affects the @parameter_string (see g_option_context_new()), @@ -21971,7 +21592,7 @@ /** * g_option_group_add_entries: * @group: a #GOptionGroup - * @entries: a %NULL-terminated array of #GOptionEntry<!-- -->s + * @entries: a %NULL-terminated array of #GOptionEntrys * * Adds the options specified in @entries to @group. * @@ -21983,8 +21604,8 @@ * g_option_group_free: * @group: a #GOptionGroup * - * Frees a #GOptionGroup. Note that you must <emphasis>not</emphasis> - * free groups which have been added to a #GOptionContext. + * Frees a #GOptionGroup. Note that you must not free groups + * which have been added to a #GOptionContext. * * Since: 2.6 */ @@ -21993,11 +21614,11 @@ /** * g_option_group_new: * @name: the name for the option group, this is used to provide - * help for the options in this group with <option>--help-</option>@name + * help for the options in this group with `--help-`@name * @description: a description for this group to be shown in - * <option>--help</option>. This string is translated using the translation + * `--help`. This string is translated using the translation * domain or translation function of the group - * @help_description: a description for the <option>--help-</option>@name option. + * @help_description: a description for the `--help-`@name option. * This string is translated using the translation domain or translation function * of the group * @user_data: (allow-none): user data that will be passed to the pre- and post-parse hooks, @@ -22052,10 +21673,9 @@ * @data: (allow-none): user data to pass to @func, or %NULL * @destroy_notify: (allow-none): a function which gets called to free @data, or %NULL * - * Sets the function which is used to translate user-visible - * strings, for <option>--help</option> output. Different - * groups can use different #GTranslateFunc<!-- -->s. If @func - * is %NULL, strings are not translated. + * Sets the function which is used to translate user-visible strings, + * for `--help` output. Different groups can use different + * #GTranslateFuncs. If @func is %NULL, strings are not translated. * * If you are using gettext(), you only need to set the translation * domain, see g_option_group_set_translation_domain(). @@ -22082,19 +21702,19 @@ * commas, or %NULL. * @keys: (array length=nkeys): pointer to an array of #GDebugKey which associate * strings with bit flags. - * @nkeys: the number of #GDebugKey<!-- -->s in the array. + * @nkeys: the number of #GDebugKeys in the array. * * Parses a string containing debugging options * into a %guint containing bit flags. This is used * within GDK and GTK+ to parse the debug options passed on the * command line or through environment variables. * - * If @string is equal to <code>"all"</code>, all flags are set. Any flags - * specified along with <code>"all"</code> in @string are inverted; thus, - * <code>"all,foo,bar"</code> or <code>"foo,bar,all"</code> sets all flags - * except those corresponding to <code>"foo"</code> and <code>"bar"</code>. + * If @string is equal to "all", all flags are set. Any flags + * specified along with "all" in @string are inverted; thus, + * "all,foo,bar" or "foo,bar,all" sets all flags except those + * corresponding to "foo" and "bar". * - * If @string is equal to <code>"help"</code>, all the available keys in @keys + * If @string is equal to "help", all the available keys in @keys * are printed out to standard error. * * Returns: the combined set of bit flags. @@ -22179,7 +21799,7 @@ * g_pattern_match: * @pspec: a #GPatternSpec * @string_length: the length of @string (in bytes, i.e. strlen(), - * <emphasis>not</emphasis> g_utf8_strlen()) + * not g_utf8_strlen()) * @string: the UTF-8 encoded string to match * @string_reversed: (allow-none): the reverse of @string or %NULL * @@ -22197,10 +21817,9 @@ * constructions thereof in the various calls to g_pattern_match(). * * Note also that the reverse of a UTF-8 encoded string can in general - * <emphasis>not</emphasis> be obtained by g_strreverse(). This works - * only if the string doesn't contain any multibyte characters. GLib - * offers the g_utf8_strreverse() function to reverse UTF-8 encoded - * strings. + * not be obtained by g_strreverse(). This works only if the string + * does not contain any multibyte characters. GLib offers the + * g_utf8_strreverse() function to reverse UTF-8 encoded strings. * * Returns: %TRUE if @string matches @pspec */ @@ -22331,7 +21950,7 @@ * file descriptor, but the situation is much more complicated on * Windows. If you need to use g_poll() in code that has to run on * Windows, the easiest solution is to construct all of your - * #GPollFD<!-- -->s with g_io_channel_win32_make_pollfd(). + * #GPollFDs with g_io_channel_win32_make_pollfd(). * * Returns: the number of entries in @fds whose %revents fields * were filled in, or 0 if the operation timed out, or -1 on error or @@ -22346,16 +21965,13 @@ * @format: printf()-style format string * @...: arguments to @format * - * Formats a string according to @format and - * prefix it to an existing error message. If - * @err is %NULL (ie: no error variable) then do + * Formats a string according to @format and prefix it to an existing + * error message. If @err is %NULL (ie: no error variable) then do * nothing. * - * If *@err is %NULL (ie: an error variable is - * present but there is no error condition) then - * also do nothing. Whether or not it makes - * sense to take advantage of this feature is up - * to you. + * If *@err is %NULL (ie: an error variable is present but there is no + * error condition) then also do nothing. Whether or not it makes sense + * to take advantage of this feature is up to you. * * Since: 2.16 */ @@ -22485,9 +22101,8 @@ * @format: printf()-style format string * @...: arguments to @format * - * If @dest is %NULL, free @src; otherwise, - * moves @src into *@dest. *@dest must be %NULL. - * After the move, add a prefix as with + * If @dest is %NULL, free @src; otherwise, moves @src into *@dest. + * *@dest must be %NULL. After the move, add a prefix as with * g_prefix_error(). * * Since: 2.16 @@ -22496,8 +22111,8 @@ /** * 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. @@ -22518,8 +22133,8 @@ /** * 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 @@ -22528,34 +22143,33 @@ * 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(). */ /** * 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 */ /** * 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 @@ -22570,38 +22184,40 @@ * * Creates a new #GPtrArray with a reference count of 1. * - * Returns: the new #GPtrArray. + * Returns: the new #GPtrArray */ /** * 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 */ /** * 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 */ @@ -22620,8 +22236,8 @@ /** * 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 @@ -22631,55 +22247,55 @@ * 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 */ /** * 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 */ /** * 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 */ /** * 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 */ @@ -22690,9 +22306,9 @@ * @length: the number of pointers to remove * * Removes the given number of pointers starting at the given index - * from a #GPtrArray. The following elements are moved to close the - * gap. If @array has a non-%NULL #GDestroyNotify function it is called - * for the removed elements. + * from a #GPtrArray. The following elements are moved to close the + * gap. If @array has a non-%NULL #GDestroyNotify function it is + * called for the removed elements. * * Returns: the @array * Since: 2.4 @@ -22701,8 +22317,9 @@ /** * 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 @@ -22714,8 +22331,8 @@ /** * 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, @@ -22726,30 +22343,30 @@ /** * 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 */ /** * 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. */ @@ -22757,16 +22374,16 @@ /** * 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. */ @@ -22774,7 +22391,7 @@ /** * 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 @@ -22802,7 +22419,7 @@ /** * g_quark_from_static_string: - * @string: (allow-none): a string. + * @string: (allow-none): a string * * Gets the #GQuark identifying the given (static) string. If the * string does not currently have an associated #GQuark, a new #GQuark @@ -22811,27 +22428,25 @@ * Note that this function is identical to g_quark_from_string() except * that if a new #GQuark is created the string itself is used rather * than a copy. This saves memory, but can only be used if the string - * will <emphasis>always</emphasis> exist. It can be used with - * statically allocated strings in the main program, but not with + * will continue to exist until the program terminates. It can be used + * with statically allocated strings in the main program, but not with * statically allocated memory in dynamically loaded modules, if you * expect to ever unload the module again (e.g. do not use this * function in GTK+ theme engines). * - * Returns: the #GQuark identifying the string, or 0 if @string is - * %NULL. + * Returns: the #GQuark identifying the string, or 0 if @string is %NULL */ /** * g_quark_from_string: - * @string: (allow-none): a string. + * @string: (allow-none): a string * * Gets the #GQuark identifying the given string. If the string does * not currently have an associated #GQuark, a new #GQuark is created, * using a copy of the string. * - * Returns: the #GQuark identifying the string, or 0 if @string is - * %NULL. + * Returns: the #GQuark identifying the string, or 0 if @string is %NULL */ @@ -22847,7 +22462,7 @@ /** * g_quark_try_string: - * @string: (allow-none): a string. + * @string: (allow-none): a string * * Gets the #GQuark associated with the given string, or 0 if string is * %NULL or it has no associated #GQuark. @@ -22856,7 +22471,7 @@ * use g_quark_from_string() or g_quark_from_static_string(). * * Returns: the #GQuark associated with the string, or 0 if @string is - * %NULL or there is no #GQuark associated with it. + * %NULL or there is no #GQuark associated with it */ @@ -22887,7 +22502,7 @@ /** * g_queue_delete_link: * @queue: a #GQueue - * @link_: a #GList link that <emphasis>must</emphasis> be part of @queue + * @link_: a #GList link that must be part of @queue * * Removes @link_ from @queue and frees it. * @@ -22948,11 +22563,8 @@ * 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. */ @@ -23008,7 +22620,7 @@ /** * g_queue_insert_after: * @queue: a #GQueue - * @sibling: a #GList link that <emphasis>must</emphasis> be part of @queue + * @sibling: a #GList link that must be part of @queue * @data: the data to insert * * Inserts @data into @queue after @sibling @@ -23022,7 +22634,7 @@ /** * g_queue_insert_before: * @queue: a #GQueue - * @sibling: a #GList link that <emphasis>must</emphasis> be part of @queue + * @sibling: a #GList link that must be part of @queue * @data: the data to insert * * Inserts @data into @queue before @sibling. @@ -23232,8 +22844,7 @@ /** * g_queue_push_head_link: * @queue: a #GQueue - * @link_: a single #GList element, <emphasis>not</emphasis> a list with - * more than one element + * @link_: a single #GList element, not a list with more than one element * * Adds a new element at the head of the queue. */ @@ -23279,8 +22890,7 @@ /** * g_queue_push_tail_link: * @queue: a #GQueue - * @link_: a single #GList element, <emphasis>not</emphasis> a list with - * more than one element + * @link_: a single #GList element, not a list with more than one element * * Adds a new element at the tail of the queue. */ @@ -23338,10 +22948,10 @@ /** * g_queue_unlink: * @queue: a #GQueue - * @link_: a #GList link that <emphasis>must</emphasis> be part of @queue + * @link_: a #GList link that must be part of @queue * - * Unlinks @link_ so that it will no longer be part of @queue. The link is - * not freed. + * Unlinks @link_ so that it will no longer be part of @queue. + * The link is not freed. * * @link_ must be part of @queue. * @@ -23351,55 +22961,55 @@ /** * g_rand_boolean: - * @rand_: a #GRand. + * @rand_: a #GRand * - * Returns a random #gboolean from @rand_. This corresponds to a - * unbiased coin toss. + * Returns a random #gboolean from @rand_. + * This corresponds to a unbiased coin toss. * - * Returns: a random #gboolean. + * Returns: a random #gboolean */ /** * g_rand_copy: - * @rand_: a #GRand. + * @rand_: a #GRand * * Copies a #GRand into a new one with the same exact state as before. * This way you can take a snapshot of the random number generator for * replaying later. * - * Returns: the new #GRand. + * Returns: the new #GRand * Since: 2.4 */ /** * g_rand_double: - * @rand_: a #GRand. + * @rand_: a #GRand * * Returns the next random #gdouble from @rand_ equally distributed over * the range [0..1). * - * Returns: A random number. + * Returns: a random number */ /** * g_rand_double_range: - * @rand_: a #GRand. - * @begin: lower closed bound of the interval. - * @end: upper open bound of the interval. + * @rand_: a #GRand + * @begin: lower closed bound of the interval + * @end: upper open bound of the interval * * Returns the next random #gdouble from @rand_ equally distributed over * the range [@begin..@end). * - * Returns: A random number. + * Returns: a random number */ /** * g_rand_free: - * @rand_: a #GRand. + * @rand_: a #GRand * * Frees the memory allocated for the #GRand. */ @@ -23407,25 +23017,25 @@ /** * g_rand_int: - * @rand_: a #GRand. + * @rand_: a #GRand * * Returns the next random #guint32 from @rand_ equally distributed over * the range [0..2^32-1]. * - * Returns: A random number. + * Returns: a random number */ /** * g_rand_int_range: - * @rand_: a #GRand. - * @begin: lower closed bound of the interval. - * @end: upper open bound of the interval. + * @rand_: a #GRand + * @begin: lower closed bound of the interval + * @end: upper open bound of the interval * * Returns the next random #gint32 from @rand_ equally distributed over * the range [@begin..@end-1]. * - * Returns: A random number. + * Returns: a random number */ @@ -23433,40 +23043,42 @@ * g_rand_new: * * Creates a new random number generator initialized with a seed taken - * either from <filename>/dev/urandom</filename> (if existing) or from - * the current time (as a fallback). On Windows, the seed is taken from - * rand_s(). + * either from `/dev/urandom` (if existing) or from the current time + * (as a fallback). + * + * On Windows, the seed is taken from rand_s(). * - * Returns: the new #GRand. + * Returns: the new #GRand */ /** * g_rand_new_with_seed: - * @seed: a value to initialize the random number generator. + * @seed: a value to initialize the random number generator * * Creates a new random number generator initialized with @seed. * - * Returns: the new #GRand. + * Returns: the new #GRand */ /** * g_rand_new_with_seed_array: - * @seed: an array of seeds to initialize the random number generator. - * @seed_length: an array of seeds to initialize the random number generator. + * @seed: an array of seeds to initialize the random number generator + * @seed_length: an array of seeds to initialize the random number + * generator * * Creates a new random number generator initialized with @seed. * - * Returns: the new #GRand. + * Returns: the new #GRand * Since: 2.4 */ /** * g_rand_set_seed: - * @rand_: a #GRand. - * @seed: a value to reinitialize the random number generator. + * @rand_: a #GRand + * @seed: a value to reinitialize the random number generator * * Sets the seed for the random number generator #GRand to @seed. */ @@ -23474,15 +23086,15 @@ /** * g_rand_set_seed_array: - * @rand_: a #GRand. + * @rand_: a #GRand * @seed: array to initialize with * @seed_length: length of array * - * Initializes the random number generator by an array of - * longs. Array can be of arbitrary size, though only the - * first 624 values are taken. This function is useful - * if you have many low entropy seeds, or if you require more then - * 32bits of actual entropy for your application. + * Initializes the random number generator by an array of longs. + * Array can be of arbitrary size, though only the first 624 values + * are taken. This function is useful if you have many low entropy + * seeds, or if you require more then 32 bits of actual entropy for + * your application. * * Since: 2.4 */ @@ -23491,9 +23103,10 @@ /** * g_random_boolean: * - * Returns a random #gboolean. This corresponds to a unbiased coin toss. + * Returns a random #gboolean. + * This corresponds to a unbiased coin toss. * - * Returns: a random #gboolean. + * Returns: a random #gboolean */ @@ -23502,18 +23115,19 @@ * * Returns a random #gdouble equally distributed over the range [0..1). * - * Returns: A random number. + * Returns: a random number */ /** * g_random_double_range: - * @begin: lower closed bound of the interval. - * @end: upper open bound of the interval. + * @begin: lower closed bound of the interval + * @end: upper open bound of the interval * - * Returns a random #gdouble equally distributed over the range [@begin..@end). + * Returns a random #gdouble equally distributed over the range + * [@begin..@end). * - * Returns: A random number. + * Returns: a random number */ @@ -23523,28 +23137,28 @@ * Return a random #guint32 equally distributed over the range * [0..2^32-1]. * - * Returns: A random number. + * Returns: a random number */ /** * g_random_int_range: - * @begin: lower closed bound of the interval. - * @end: upper open bound of the interval. + * @begin: lower closed bound of the interval + * @end: upper open bound of the interval * * Returns a random #gint32 equally distributed over the range * [@begin..@end-1]. * - * Returns: A random number. + * Returns: a random number */ /** * g_random_set_seed: - * @seed: a value to reinitialize the global random number generator. + * @seed: a value to reinitialize the global random number generator * * Sets the seed for the global random number generator, which is used - * by the <function>g_random_*</function> functions, to @seed. + * by the g_random_* functions, to @seed. */ @@ -23607,7 +23221,7 @@ * It is not necessary to initialise a recursive mutex that has been * statically allocated. * - * |[ + * |[<!-- language="C" --> * typedef struct { * GRecMutex m; * ... @@ -23844,16 +23458,16 @@ * To retrieve all the non-overlapping matches of the pattern in * string you can use g_match_info_next(). * - * |[ + * |[<!-- language="C" --> * static void * print_uppercase_words (const gchar *string) * { * /* Print all uppercase-only words. */ * GRegex *regex; * GMatchInfo *match_info; - * + * * regex = g_regex_new ("[A-Z]+", 0, 0, NULL); - * g_regex_match (regex, string, 0, &match_info); + * g_regex_match (regex, string, 0, &match_info); * while (g_match_info_matches (match_info)) * { * gchar *word = g_match_info_fetch (match_info, 0); @@ -23989,7 +23603,7 @@ * To retrieve all the non-overlapping matches of the pattern in * string you can use g_match_info_next(). * - * |[ + * |[<!-- language="C" --> * static void * print_uppercase_words (const gchar *string) * { @@ -23997,15 +23611,15 @@ * GRegex *regex; * GMatchInfo *match_info; * GError *error = NULL; - * + * * regex = g_regex_new ("[A-Z]+", 0, 0, NULL); - * g_regex_match_full (regex, string, -1, 0, 0, &match_info, &error); + * g_regex_match_full (regex, string, -1, 0, 0, &match_info, &error); * while (g_match_info_matches (match_info)) * { * gchar *word = g_match_info_fetch (match_info, 0); * g_print ("Found: %s\n", word); * g_free (word); - * g_match_info_next (match_info, &error); + * g_match_info_next (match_info, &error); * } * g_match_info_free (match_info); * g_regex_unref (regex); @@ -24089,35 +23703,14 @@ * to the captured subexpression with the given name. '\0' refers to the * complete match, but '\0' followed by a number is the octal representation * of a character. To include a literal '\' in the replacement, write '\\'. + * * There are also escapes that changes the case of the following text: * - * <variablelist> - * <varlistentry><term>\l</term> - * <listitem> - * <para>Convert to lower case the next character</para> - * </listitem> - * </varlistentry> - * <varlistentry><term>\u</term> - * <listitem> - * <para>Convert to upper case the next character</para> - * </listitem> - * </varlistentry> - * <varlistentry><term>\L</term> - * <listitem> - * <para>Convert to lower case till \E</para> - * </listitem> - * </varlistentry> - * <varlistentry><term>\U</term> - * <listitem> - * <para>Convert to upper case till \E</para> - * </listitem> - * </varlistentry> - * <varlistentry><term>\E</term> - * <listitem> - * <para>End case modification</para> - * </listitem> - * </varlistentry> - * </variablelist> + * - \l: Convert to lower case the next character + * - \u: Convert to upper case the next character + * - \L: Convert to lower case till \E + * - \U: Convert to upper case till \E + * - \E: End case modification * * If you do not need to use backreferences use g_regex_replace_literal(). * @@ -24154,7 +23747,7 @@ * * The following example uses g_regex_replace_eval() to replace multiple * strings at once: - * |[ + * |[<!-- language="C" --> * static gboolean * eval_cb (const GMatchInfo *info, * GString *res, @@ -24444,7 +24037,7 @@ * necessary to initialise a reader-writer lock that has been statically * allocated. * - * |[ + * |[<!-- language="C" --> * typedef struct { * GRWLock l; * ... @@ -24911,8 +24504,8 @@ * @seq: a #GSequence * * Frees the memory allocated for @seq. If @seq has a data destroy - * function associated with it, that function is called on all items in - * @seq. + * function associated with it, that function is called on all items + * in @seq. * * Since: 2.14 */ @@ -24954,7 +24547,7 @@ /** * g_sequence_get_iter_at_pos: * @seq: a #GSequence - * @pos: a position in @seq, or -1 for the end. + * @pos: a position in @seq, or -1 for the end * * Returns the iterator at position @pos. If @pos is negative or larger * than the number of items in @seq, the end iterator is returned. @@ -25044,8 +24637,8 @@ * * The @a and @b iterators must point into the same sequence. * - * Returns: A negative number if @a comes before @b, 0 if they are - * equal, and a positive number if @a comes after @b. + * Returns: a negative number if @a comes before @b, 0 if they are + * equal, and a positive number if @a comes after @b * Since: 2.14 */ @@ -25067,7 +24660,7 @@ * * Returns the #GSequence that @iter points into. * - * Returns: the #GSequence that @iter points into. + * Returns: the #GSequence that @iter points into * Since: 2.14 */ @@ -25089,7 +24682,7 @@ * * Returns whether @iter is the end iterator * - * Returns: Whether @iter is the end iterator. + * Returns: Whether @iter is the end iterator * Since: 2.14 */ @@ -25098,14 +24691,14 @@ * g_sequence_iter_move: * @iter: a #GSequenceIter * @delta: A positive or negative number indicating how many positions away - * from @iter the returned #GSequenceIter will be. + * from @iter the returned #GSequenceIter will be * * Returns the #GSequenceIter which is @delta positions away from @iter. * If @iter is closer than -@delta positions to the beginning of the sequence, * the begin iterator is returned. If @iter is closer than @delta positions * to the end of the sequence, the end iterator is returned. * - * Returns: a #GSequenceIter which is @delta positions away from @iter. + * Returns: a #GSequenceIter which is @delta positions away from @iter * Since: 2.14 */ @@ -25114,10 +24707,10 @@ * g_sequence_iter_next: * @iter: a #GSequenceIter * - * Returns an iterator pointing to the next position after @iter. If - * @iter is the end iterator, the end iterator is returned. + * Returns an iterator pointing to the next position after @iter. + * If @iter is the end iterator, the end iterator is returned. * - * Returns: a #GSequenceIter pointing to the next position after @iter. + * Returns: a #GSequenceIter pointing to the next position after @iter * Since: 2.14 */ @@ -25126,11 +24719,11 @@ * g_sequence_iter_prev: * @iter: a #GSequenceIter * - * Returns an iterator pointing to the previous position before @iter. If - * @iter is the begin iterator, the begin iterator is returned. + * Returns an iterator pointing to the previous position before @iter. + * If @iter is the begin iterator, the begin iterator is returned. * - * Returns: a #GSequenceIter pointing to the previous position before - * @iter. + * Returns: a #GSequenceIter pointing to the previous position + * before @iter * Since: 2.14 */ @@ -25140,7 +24733,7 @@ * @seq: a #GSequence * @data: data to lookup * @cmp_func: the function used to compare items in the sequence - * @cmp_data: user data passed to @cmp_func. + * @cmp_data: user data passed to @cmp_func * * Returns an iterator pointing to the position of the first item found * equal to @data according to @cmp_func and @cmp_data. If more than one @@ -25153,17 +24746,15 @@ * 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> * * Returns: an #GSequenceIter pointing to the position of the * first item found equal to @data according to @cmp_func and - * @cmp_data, or %NULL if no such item exists. + * @cmp_data, or %NULL if no such item exists * Since: 2.28 */ @@ -25183,17 +24774,15 @@ * 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> * * Returns: an #GSequenceIter pointing to the position of * the first item found equal to @data according to @cmp_func - * and @cmp_data, or %NULL if no such item exists. + * and @cmp_data, or %NULL if no such item exists * Since: 2.28 */ @@ -25202,7 +24791,7 @@ * g_sequence_move: * @src: a #GSequenceIter pointing to the item to move * @dest: a #GSequenceIter pointing to the position to which - * the item is moved. + * the item is moved * * Moves the item pointed to by @src to the position indicated by @dest. * After calling this function @dest will point to the position immediately @@ -25264,13 +24853,13 @@ * * Finds an iterator somewhere in the range (@begin, @end). This * iterator will be close to the middle of the range, but is not - * guaranteed to be <emphasis>exactly</emphasis> in the middle. + * guaranteed to be exactly in the middle. * - * The @begin and @end iterators must both point to the same sequence and - * @begin must come before or be equal to @end in the sequence. + * The @begin and @end iterators must both point to the same sequence + * and @begin must come before or be equal to @end in the sequence. * - * Returns: A #GSequenceIter pointing somewhere in the - * (@begin, @end) range. + * Returns: a #GSequenceIter pointing somewhere in the + * (@begin, @end) range * Since: 2.14 */ @@ -25308,7 +24897,7 @@ * @seq: a #GSequence * @data: data for the new item * @cmp_func: the function used to compare items in the sequence - * @cmp_data: user data passed to @cmp_func. + * @cmp_data: user data passed to @cmp_func * * Returns an iterator pointing to the position where @data would * be inserted according to @cmp_func and @cmp_data. @@ -25321,16 +24910,14 @@ * 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> * * Returns: an #GSequenceIter pointing to the position where @data - * would have been inserted according to @cmp_func and @cmp_data. + * would have been inserted according to @cmp_func and @cmp_data * Since: 2.14 */ @@ -25353,17 +24940,15 @@ * 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> * * Returns: a #GSequenceIter pointing to the position in @seq * where @data would have been inserted according to @iter_cmp - * and @cmp_data. + * and @cmp_data * Since: 2.14 */ @@ -25521,9 +25106,10 @@ * g_set_prgname: * @prgname: the name of the program. * - * Sets the name of the program. This name should <emphasis>not</emphasis> - * be localized, contrast with g_set_application_name(). Note that for - * thread-safety reasons this function can only be called once. + * Sets the name of the program. This name should not be localized, + * in contrast to g_set_application_name(). + * + * Note that for thread-safety reasons this function can only be called once. */ @@ -25573,20 +25159,18 @@ * Note that on some systems, when variables are overwritten, the memory * used for the previous variables and its value isn't reclaimed. * - * <warning><para> - * Environment variable handling in UNIX is not thread-safe, and your - * program may crash if one thread calls g_setenv() while another - * thread is calling getenv(). (And note that many functions, such as - * gettext(), call getenv() internally.) This function is only safe to - * use at the very start of your program, before creating any other - * threads (or creating objects that create worker threads of their - * own). - * </para><para> + * You should be mindful fo the fact that environment variable handling + * in UNIX is not thread-safe, and your program may crash if one thread + * calls g_setenv() while another thread is calling getenv(). (And note + * that many functions, such as gettext(), call getenv() internally.) + * This function is only safe to use at the very start of your program, + * before creating any other threads (or creating objects that create + * worker threads of their own). + * * If you need to set up the environment for a child process, you can * use g_get_environ() to get an environment array, modify that with * g_environ_setenv() and g_environ_unsetenv(), and then pass that * array directly to execvpe(), g_spawn_async(), or the like. - * </para></warning> * * Returns: %FALSE if the environment variable couldn't be set. * Since: 2.4 @@ -25666,7 +25250,7 @@ * * Allocates a block of memory from the slice allocator. * The block adress handed out can be expected to be aligned - * to at least <literal>1 * sizeof (void*)</literal>, + * to at least 1 * sizeof (void*), * though in general slices are 2 * sizeof (void*) bytes aligned, * if a malloc() fallback implementation is used instead, * the alignment may be reduced in a libc dependent fashion. @@ -25715,7 +25299,7 @@ * A convenience macro to duplicate a block of memory using * the slice allocator. * - * It calls g_slice_copy() with <literal>sizeof (@type)</literal> + * It calls g_slice_copy() with `sizeof (@type)` * and casts the returned pointer to a pointer of the given type, * avoiding a type cast in the source code. * Note that the underlying slice allocation mechanism can @@ -25735,7 +25319,7 @@ * A convenience macro to free a block of memory that has * been allocated from the slice allocator. * - * It calls g_slice_free1() using <literal>sizeof (type)</literal> + * It calls g_slice_free1() using `sizeof (type)` * as the block size. * Note that the exact release behaviour can be changed with the * <link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment @@ -25813,11 +25397,11 @@ * A convenience macro to allocate a block of memory from the * slice allocator. * - * It calls g_slice_alloc() with <literal>sizeof (@type)</literal> - * and casts the returned pointer to a pointer of the given type, - * avoiding a type cast in the source code. - * Note that the underlying slice allocation mechanism can - * be changed with the <link linkend="G_SLICE">G_SLICE=always-malloc</link> + * It calls g_slice_alloc() with `sizeof (@type)` and casts the + * returned pointer to a pointer of the given type, avoiding a type + * cast in the source code. Note that the underlying slice allocation + * mechanism can be changed with the + * <link linkend="G_SLICE">G_SLICE=always-malloc</link> * environment variable. * * Returns: a pointer to the allocated block, cast to a pointer to @type @@ -25832,7 +25416,7 @@ * A convenience macro to allocate a block of memory from the * slice allocator and set the memory to 0. * - * It calls g_slice_alloc0() with <literal>sizeof (@type)</literal> + * It calls g_slice_alloc0() with `sizeof (@type)` * and casts the returned pointer to a pointer of the given type, * avoiding a type cast in the source code. * Note that the underlying slice allocation mechanism can @@ -25861,19 +25445,15 @@ * * 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> * - * |[ + * |[<!-- language="C" --> * /* Notice that these are initialized to the empty list. */ * GSList *list = NULL, *number_list = NULL; * @@ -25909,12 +25489,10 @@ * * 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 */ @@ -25936,12 +25514,12 @@ * one argument. * * For instance, if @list holds a list of GObjects, you can do: - * |[ + * |[<!-- language="C" --> * another_list = g_slist_copy_deep (list, (GCopyFunc) g_object_ref, NULL); * ]| * * And, to entirely free the new list, you could do: - * |[ + * |[<!-- language="C" --> * g_slist_free_full (another_list, g_object_unref); * ]| * @@ -25959,11 +25537,11 @@ * 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 */ @@ -26017,11 +25595,9 @@ * 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> */ @@ -26133,9 +25709,7 @@ * * 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 @@ -26148,10 +25722,8 @@ * * 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 */ @@ -26211,12 +25783,10 @@ * * 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> * - * |[ + * |[<!-- language="C" --> * /* Notice that it is initialized to the empty list. */ * GSList *list = NULL; * list = g_slist_prepend (list, "last"); @@ -26264,11 +25834,11 @@ * 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 */ @@ -26426,7 +25996,8 @@ * * Removes a source from its #GMainContext, if any, and mark it as * destroyed. The source cannot be subsequently added to another - * context. + * context. It is safe to call this on sources which have already been + * removed from their context. */ @@ -26549,16 +26120,16 @@ * from within idle handlers, but may have freed the object * before the dispatch of your idle handler. * - * |[ + * |[<!-- language="C" --> * static gboolean * idle_callback (gpointer data) * { * SomeWidget *self = data; * - * GDK_THREADS_ENTER (<!-- -->); - * /<!-- -->* do stuff with self *<!-- -->/ + * GDK_THREADS_ENTER (); + * /* do stuff with self */ * self->idle_id = 0; - * GDK_THREADS_LEAVE (<!-- -->); + * GDK_THREADS_LEAVE (); * * return G_SOURCE_REMOVE; * } @@ -26587,7 +26158,7 @@ * this particular problem, is to check to if the source * has already been destroy within the callback. * - * |[ + * |[<!-- language="C" --> * static gboolean * idle_callback (gpointer data) * { @@ -26596,7 +26167,7 @@ * GDK_THREADS_ENTER (); * if (!g_source_is_destroyed (g_main_current_source ())) * { - * /<!-- -->* do stuff with self *<!-- -->/ + * /* do stuff with self */ * } * GDK_THREADS_LEAVE (); * @@ -26637,7 +26208,7 @@ * Creates a new #GSource structure. The size is specified to * allow creating structures derived from #GSource that contain * additional data. The size passed in must be at least - * <literal>sizeof (GSource)</literal>. + * `sizeof (GSource)`. * * The source will not initially be associated with any #GMainContext * and must be added to one with g_source_attach() before it will be @@ -26936,17 +26507,14 @@ * 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. * * Returns: %TRUE on success, %FALSE if error is set */ @@ -26968,18 +26536,18 @@ * * Executes a child program asynchronously (your program will not * block waiting for the child to exit). The child program is - * specified by the only argument that must be provided, @argv. @argv - * should be a %NULL-terminated array of strings, to be passed as the - * argument vector for the child. The first string in @argv is of - * course the name of the program to execute. By default, the name of - * the program must be a full path. If @flags contains the - * %G_SPAWN_SEARCH_PATH flag, the <envar>PATH</envar> environment variable - * is used to search for the executable. If @flags contains the - * %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the <envar>PATH</envar> variable from - * @envp is used to search for the executable. - * If both the %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP - * flags are set, the <envar>PATH</envar> variable from @envp takes precedence - * over the environment variable. + * specified by the only argument that must be provided, @argv. + * @argv should be a %NULL-terminated array of strings, to be passed + * as the argument vector for the child. The first string in @argv + * is of course the name of the program to execute. By default, the + * name of the program must be a full path. If @flags contains the + * %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is + * used to search for the executable. If @flags contains the + * %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from + * @envp is used to search for the executable. If both the + * %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags + * are set, the `PATH` variable from @envp takes precedence over + * the environment variable. * * If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not * used, then the program will be run from the current directory (or @@ -27004,21 +26572,19 @@ * 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 @@ -27026,9 +26592,8 @@ * identifiers are different concepts on Windows. * * @envp is a %NULL-terminated array of strings, where each string - * has the form <literal>KEY=VALUE</literal>. This will become - * the child's environment. If @envp is %NULL, the child inherits its - * parent's environment. + * has the form `KEY=VALUE`. This will become the child's environment. + * If @envp is %NULL, the child inherits its parent's environment. * * @flags should be the bitwise OR of any flags you want to affect the * function's behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that the @@ -27037,22 +26602,21 @@ * 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. - * %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 + * descriptors will be inherited by the child; otherwise all descriptors + * except stdin/stdout/stderr will be closed before calling exec() in + * the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an + * absolute path, it will be looked for in the `PATH` environment + * variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an + * absolute path, it will be looked for in the `PATH` variable from + * @envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP + * are used, the value from @envp takes precedence over the environment. + * %G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output + * will be discarded, instead of going to the same location as the parent's * standard output. If you use this flag, @standard_output must be %NULL. * %G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error * will be discarded, instead of going to the same location as the parent's @@ -27061,42 +26625,40 @@ * 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. - * - * 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 + * 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 * 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. @@ -27110,11 +26672,11 @@ * 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 `message` field of returned + * errors should be displayed to users. Possible errors are those from + * the #G_SPAWN_ERROR domain. * * If an error occurs, @child_pid, @standard_input, @standard_output, * and @standard_error will not be filled with valid values. @@ -27122,12 +26684,10 @@ * 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> * * Returns: %TRUE on success, %FALSE if an error was set */ @@ -27143,25 +26703,23 @@ * * 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. @@ -27173,12 +26731,12 @@ * * 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 */ @@ -27209,7 +26767,7 @@ * * The same concerns on Windows apply as for g_spawn_command_line_sync(). * - * Returns: %TRUE on success, %FALSE if error is set. + * Returns: %TRUE on success, %FALSE if error is set */ @@ -27280,7 +26838,7 @@ * function for full details on the other parameters and details on * how these functions work on Windows. * - * Returns: %TRUE on success, %FALSE if an error was set. + * Returns: %TRUE on success, %FALSE if an error was set */ @@ -27309,33 +26867,32 @@ /** * g_stat: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) - * @buf: a pointer to a <structname>stat</structname> struct, which - * will be filled with the file information + * @buf: a pointer to a stat struct, which will be filled with the file + * information * * A wrapper for the POSIX stat() function. The stat() function * returns information about a file. On Windows the stat() function in * the C library checks only the FAT-style READONLY attribute and does * not look at the ACL at all. Thus on Windows the protection bits in - * the st_mode field are a fabrication of little use. + * the @st_mode field are a fabrication of little use. * * On Windows the Microsoft C libraries have several variants of the - * <structname>stat</structname> struct and stat() function with names - * like "_stat", "_stat32", "_stat32i64" and "_stat64i32". The one - * used here is for 32-bit code the one with 32-bit size and time - * fields, specifically called "_stat32". + * stat struct and stat() function with names like _stat(), _stat32(), + * _stat32i64() and _stat64i32(). The one used here is for 32-bit code + * the one with 32-bit size and time fields, specifically called _stat32(). * - * In Microsoft's compiler, by default "struct stat" means one with - * 64-bit time fields while in MinGW "struct stat" is the legacy one + * In Microsoft's compiler, by default struct stat means one with + * 64-bit time fields while in MinGW struct stat is the legacy one * with 32-bit fields. To hopefully clear up this messs, the gstdio.h - * header defines a type GStatBuf which is the appropriate struct type + * header defines a type #GStatBuf which is the appropriate struct type * depending on the platform and/or compiler being used. On POSIX it - * is just "struct stat", but note that even on POSIX platforms, - * "stat" might be a macro. + * is just struct stat, but note that even on POSIX platforms, stat() + * might be a macro. * * See your C library manual for more details about stat(). * - * Returns: 0 if the information was successfully retrieved, -1 if an error - * occurred + * Returns: 0 if the information was successfully retrieved, + * -1 if an error occurred * Since: 2.6 */ @@ -27402,11 +26959,11 @@ * * Converts a string to a hash value. * - * This function implements the widely used "djb" hash apparently posted - * by Daniel Bernstein to comp.lang.c some time ago. The 32 bit - * unsigned hash value starts at 5381 and for each byte 'c' in the - * string, is updated: <literal>hash = hash * 33 + c</literal>. This - * function uses the signed value of each byte. + * This function implements the widely used "djb" hash apparently + * posted by Daniel Bernstein to comp.lang.c some time ago. The 32 + * bit unsigned hash value starts at 5381 and for each byte 'c' in + * the string, is updated: `hash = hash * 33 + c`. This function + * uses the signed value of each byte. * * It can be passed to g_hash_table_new() as the @hash_func parameter, * when using non-%NULL strings as keys in a #GHashTable. @@ -27417,12 +26974,12 @@ /** * g_str_is_ascii: - * @string: a string. + * @str: a string * - * Determines if a string is pure ASCII. A string is pure ASCII if it + * Determines if a string is pure ASCII. A string is pure ASCII if it * contains no bytes with the high bit set. * - * Returns: %TRUE if @string is ascii + * Returns: %TRUE if @str is ASCII * Since: 2.40 */ @@ -27496,11 +27053,11 @@ * @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 + * |[<!-- language="C" --> * g_ascii_strup (g_strcanon (str, "abc", '?')) * ]| * @@ -27510,16 +27067,16 @@ /** * 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. * * Returns: 0 if the strings match, a negative 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. + * 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. */ @@ -27592,17 +27149,16 @@ * @string1: the first string to add, which must not be %NULL * @...: a %NULL-terminated list of strings to append to the string * - * Concatenates all of the given strings into one long string. - * The returned string should be freed with g_free() when no longer needed. + * Concatenates all of the given strings into one long string. The + * returned string should be freed with g_free() when no longer needed. + * + * The variable argument list must end with %NULL. If you forget the %NULL, + * g_strconcat() will start appending random memory junk to your string. * * Note that this function is usually not the right function to use to * assemble a translated message from pieces, since proper translation * often requires the pieces to be reordered. * - * <warning><para>The variable argument list <emphasis>must</emphasis> end - * with %NULL. If you forget the %NULL, g_strconcat() will start appending - * random memory junk to your string.</para></warning> - * * Returns: a newly-allocated string containing all the string arguments */ @@ -27610,8 +27166,8 @@ /** * 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. @@ -27619,7 +27175,7 @@ * changed to the @new_delimiter character. Modifies @string in place, * and returns @string itself, not a copy. The return value is to * allow nesting such as - * |[ + * |[<!-- language="C" --> * g_ascii_strup (g_strdelimit (str, "abc", '?')) * ]| * @@ -28359,7 +27915,8 @@ /** * 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 @@ -28373,7 +27930,8 @@ /** * 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 @@ -28397,19 +27955,18 @@ * 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. */ @@ -28422,17 +27979,17 @@ * Portability wrapper that calls strlcpy() on systems which have it, * and emulates strlcpy() otherwise. Copies @src to @dest; @dest is * guaranteed to be nul-terminated; @src must be nul-terminated; - * @dest_size is the buffer size, not the number of chars to copy. + * @dest_size is the buffer size, not the number of bytes to copy. * - * At most dest_size - 1 characters will be copied. Always nul-terminates - * (unless dest_size == 0). This function does <emphasis>not</emphasis> - * allocate memory. Unlike strncpy(), this function doesn't pad dest (so - * it's often faster). It returns the size of the attempted result, - * strlen (src), so if @retval >= @dest_size, truncation occurred. + * At most @dest_size - 1 characters will be copied. Always nul-terminates + * (unless @dest_size is 0). This function does not allocate memory. Unlike + * strncpy(), this function doesn't pad @dest (so 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 */ @@ -28440,31 +27997,31 @@ /** * 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. * * Returns: 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. + * 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. + * 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. */ @@ -28474,18 +28031,16 @@ * @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> + * To copy a number of characters from a UTF-8 encoded string, + * use g_utf8_strncpy() instead. * * Returns: a newly-allocated buffer containing the first @n bytes - * of @str, nul-terminated + * of @str, nul-terminated */ @@ -28506,8 +28061,7 @@ * @string: the string to reverse * * Reverses all of the bytes in a string. For example, - * <literal>g_strreverse ("abcdef")</literal> will result - * in "fedcba". + * `g_strreverse ("abcdef")` will result in "fedcba". * * Note that g_strreverse() doesn't work on UTF-8 strings * containing multibyte characters. For that purpose, use @@ -28547,8 +28101,7 @@ /** * g_strsignal: - * @signum: the signal number. See the <literal>signal</literal> - * documentation + * @signum: the signal number. See the `signal` documentation * * Returns a string describing the given signal, e.g. "Segmentation fault". * You should use this function in preference to strsignal(), because it @@ -28673,13 +28226,14 @@ /** * g_strup: - * @string: the string to convert. + * @string: the string to convert * * Converts a string to upper case. * * Returns: 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. */ @@ -28729,8 +28283,7 @@ * * If @testpath includes the component "subprocess" anywhere in it, * the test will be skipped by default, and only run if explicitly - * required via the <option>-p</option> command-line option or - * g_test_trap_subprocess(). + * required via the `-p` command-line option or g_test_trap_subprocess(). * * Since: 2.16 */ @@ -28762,8 +28315,7 @@ * * If @testpath includes the component "subprocess" anywhere in it, * the test will be skipped by default, and only run if explicitly - * required via the <option>-p</option> command-line option or - * g_test_trap_subprocess(). + * required via the `-p` command-line option or g_test_trap_subprocess(). * * Since: 2.16 */ @@ -28910,7 +28462,7 @@ * * For example: * - * |[ + * |[<!-- language="C" --> * /* g_main_context_push_thread_default() should fail if the * * context is already owned by another thread. * */ @@ -29047,88 +28599,38 @@ * @argv: Address of the @argv parameter of main(). * Any parameters understood by g_test_init() stripped before return. * @...: %NULL-terminated list of special options. Currently the only - * defined option is <literal>"no_g_set_prgname"</literal>, which + * defined option is `"no_g_set_prgname"`, which * will cause g_test_init() to not call g_set_prgname(). * * Initialize the GLib testing framework, e.g. by seeding the * test random number generator, the name for g_get_prgname() * and parsing test related command line args. + * * So far, the following arguments are understood: - * <variablelist> - * <varlistentry> - * <term><option>-l</option></term> - * <listitem><para> - * List test cases available in a test executable. - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term><option>--seed=<replaceable>RANDOMSEED</replaceable></option></term> - * <listitem><para> - * Provide a random seed to reproduce test runs using random numbers. - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term><option>--verbose</option></term> - * <listitem><para>Run tests verbosely.</para></listitem> - * </varlistentry> - * <varlistentry> - * <term><option>-q</option>, <option>--quiet</option></term> - * <listitem><para>Run tests quietly.</para></listitem> - * </varlistentry> - * <varlistentry> - * <term><option>-p <replaceable>TESTPATH</replaceable></option></term> - * <listitem><para> - * Execute all tests matching <replaceable>TESTPATH</replaceable>. - * This can also be used to force a test to run that would otherwise - * be skipped (ie, a test whose name contains "/subprocess"). - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term><option>-m {perf|slow|thorough|quick|undefined|no-undefined}</option></term> - * <listitem><para> - * Execute tests according to these test modes: - * <variablelist> - * <varlistentry> - * <term>perf</term> - * <listitem><para> - * Performance tests, may take long and report results. - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>slow, thorough</term> - * <listitem><para> - * Slow and thorough tests, may take quite long and - * maximize coverage. - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>quick</term> - * <listitem><para> - * Quick tests, should run really quickly and give good coverage. - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>undefined</term> - * <listitem><para> - * Tests for undefined behaviour, may provoke programming errors - * under g_test_trap_subprocess() or g_test_expect_messages() to check - * that appropriate assertions or warnings are given - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>no-undefined</term> - * <listitem><para> - * Avoid tests for undefined behaviour - * </para></listitem> - * </varlistentry> - * </variablelist> - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term><option>--debug-log</option></term> - * <listitem><para>Debug test logging output.</para></listitem> - * </varlistentry> - * </variablelist> + * + * - `-l`: List test cases available in a test executable. + * - `--seed=SEED`: Provide a random seed to reproduce test + * runs using random numbers. + * - `--verbose`: Run tests verbosely. + * - `-q`, `--quiet`: Run tests quietly. + * - `-p PATH`: Execute all tests matching the given path. + * This can also be used to force a test to run that would otherwise + * be skipped (ie, a test whose name contains "/subprocess"). + * - `-m {perf|slow|thorough|quick|undefined|no-undefined}`: Execute tests according to these test modes: + * + * `perf`: Performance tests, may take long and report results. + * + * `slow`, `thorough`: Slow and thorough tests, may take quite long and maximize coverage. + * + * `quick`: Quick tests, should run really quickly and give good coverage. + * + * `undefined`: Tests for undefined behaviour, may provoke programming errors + * under g_test_trap_subprocess() or g_test_expect_messages() to check + * that appropriate assertions or warnings are given + * + * `no-undefined`: Avoid tests for undefined behaviour + * + * - `--debug-log`: Debug test logging output. * * Since: 2.16 */ @@ -29387,15 +28889,13 @@ * * Runs all tests under the toplevel suite which can be retrieved * with g_test_get_root(). Similar to g_test_run_suite(), the test - * cases to be run are filtered according to - * test path arguments (-p <replaceable>testpath</replaceable>) as - * parsed by g_test_init(). - * g_test_run_suite() or g_test_run() may only be called once - * in a program. + * cases to be run are filtered according to test path arguments + * (`-p testpath`) as parsed by g_test_init(). g_test_run_suite() + * or g_test_run() may only be called once in a program. * * In general, the tests and sub-suites within each suite are run in * the order in which they are defined. However, note that prior to - * GLib 2.36, there was a bug in the <literal>g_test_add_*</literal> + * GLib 2.36, there was a bug in the `g_test_add_*` * functions which caused them to create multiple suites with the same * name, meaning that if you created tests "/foo/simple", * "/bar/simple", and "/foo/using-bar" in that order, they would get @@ -29427,9 +28927,9 @@ * * Execute the tests within @suite and all nested #GTestSuites. * The test suites to be executed are filtered according to - * test path arguments (-p <replaceable>testpath</replaceable>) - * as parsed by g_test_init(). See the g_test_run() documentation - * for more information on the order that tests are run in. + * test path arguments (`-p testpath`) as parsed by g_test_init(). + * See the g_test_run() documentation for more information on the + * order that tests are run in. * * g_test_run_suite() or g_test_run() may only be called once * in a program. @@ -29661,7 +29161,7 @@ * The forking parent process then asserts successful child program * termination and validates child program outputs. * - * |[ + * |[<!-- language="C" --> * static void * test_fork_patterns (void) * { @@ -29719,12 +29219,11 @@ * You can use g_test_subprocess() to determine whether the test is in * a subprocess or not. * - * @test_path can also be the name of the parent - * test, followed by "<literal>/subprocess/</literal>" and then a name - * for the specific subtest (or just ending with - * "<literal>/subprocess</literal>" if the test only has one child - * test); tests with names of this form will automatically be skipped - * in the parent process. + * @test_path can also be the name of the parent test, followed by + * "`/subprocess/`" and then a name for the specific subtest (or just + * ending with "`/subprocess`" if the test only has one child test); + * tests with names of this form will automatically be skipped in the + * parent process. * * If @usec_timeout is non-0, the test subprocess is aborted and * considered failing if its run time exceeds it. @@ -29739,15 +29238,15 @@ * cannot be used if @test_flags specifies that the child should * inherit the parent stdout/stderr.) * - * If your <literal>main ()</literal> needs to behave differently in + * If your `main ()` needs to behave differently in * the subprocess, you can call g_test_subprocess() (after calling * g_test_init()) to see whether you are in a subprocess. * * The following example tests that calling - * <literal>my_object_new(1000000)</literal> will abort with an error + * `my_object_new(1000000)` will abort with an error * message. * - * |[ + * |[<!-- language="C" --> * static void * test_create_large_object_subprocess (void) * { @@ -29809,15 +29308,13 @@ * waiting thread will be woken up and get @retval as the return value * of g_thread_join(). * - * Calling <literal>g_thread_exit (retval)</literal> is equivalent to + * Calling g_thread_exit() with a parameter @retval 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. */ @@ -30248,11 +29745,11 @@ * "YYYY-MM-DDTHH:MM:SSZ" or "YYYY-MM-DDTHH:MM:SS.fffffZ". * * This corresponds to the Internet date/time format defined by - * <ulink url="https://www.ietf.org/rfc/rfc3339.txt">RFC 3339</ulink>, and - * to either of the two most-precise formats defined by - * <ulink url="http://www.w3.org/TR/NOTE-datetime-19980827">the W3C Note - * "Date and Time Formats"</ulink>. Both of these documents are profiles of - * ISO 8601. + * [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt), + * and to either of the two most-precise formats defined by + * the W3C Note + * [Date and Time Formats](http://www.w3.org/TR/NOTE-datetime-19980827). + * Both of these documents are profiles of ISO 8601. * * Use g_date_time_format() or g_strdup_printf() if a different * variation of ISO 8601 format is required. @@ -30375,29 +29872,29 @@ * Creates a #GTimeZone corresponding to @identifier. * * @identifier can either be an RFC3339/ISO 8601 time offset or - * something that would pass as a valid value for the - * <varname>TZ</varname> environment variable (including %NULL). + * something that would pass as a valid value for the `TZ` environment + * variable (including %NULL). * * In Windows, @identifier can also be the unlocalized name of a time * zone for standard time, for example "Pacific Standard Time". * - * Valid RFC3339 time offsets are <literal>"Z"</literal> (for UTC) or - * <literal>"±hh:mm"</literal>. ISO 8601 additionally specifies - * <literal>"±hhmm"</literal> and <literal>"±hh"</literal>. Offsets are + * Valid RFC3339 time offsets are `"Z"` (for UTC) or + * `"±hh:mm"`. ISO 8601 additionally specifies + * `"±hhmm"` and `"±hh"`. Offsets are * time values to be added to Coordinated Universal Time (UTC) to get * the local time. * - * In Unix, the <varname>TZ</varname> environment variable typically - * corresponds to the name of a file in the zoneinfo database, or - * string in "std offset [dst [offset],start[/time],end[/time]]" - * (POSIX) format. There are no spaces in the specification. The - * name of standard and daylight savings time zone must be three or more - * alphabetic characters. Offsets are time values to be added to local - * time to get Coordinated Universal Time (UTC) and should be - * <literal>"[±]hh[[:]mm[:ss]]"</literal>. Dates are either - * <literal>"Jn"</literal> (Julian day with n between 1 and 365, leap - * years not counted), <literal>"n"</literal> (zero-based Julian day - * with n between 0 and 365) or <literal>"Mm.w.d"</literal> (day d + * In UNIX, the `TZ` environment variable typically corresponds + * to the name of a file in the zoneinfo database, or string in + * "std offset [dst [offset],start[/time],end[/time]]" (POSIX) format. + * There are no spaces in the specification. The name of standard + * and daylight savings time zone must be three or more alphabetic + * characters. Offsets are time values to be added to local time to + * get Coordinated Universal Time (UTC) and should be + * `"[±]hh[[:]mm[:ss]]"`. Dates are either + * `"Jn"` (Julian day with n between 1 and 365, leap + * years not counted), `"n"` (zero-based Julian day + * with n between 0 and 365) or `"Mm.w.d"` (day d * (0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day * 0 is a Sunday). Times are in local wall clock time, the default is * 02:00:00. @@ -30410,30 +29907,28 @@ * Coordinated Universal Time (UTC). * * g_time_zone_new_local() calls this function with the value of the - * <varname>TZ</varname> environment variable. This function itself is - * independent of the value of <varname>TZ</varname>, but if @identifier - * is %NULL then <filename>/etc/localtime</filename> will be consulted - * to discover the correct time zone on Unix and the registry will be - * consulted or GetTimeZoneInformation() will be used to get the local - * time zone on Windows. - * - * If intervals are not available, only time zone rules from - * <varname>TZ</varname> environment variable or other means, then they - * will be computed from year 1900 to 2037. If the maximum year for the - * rules is available and it is greater than 2037, then it will followed + * `TZ` environment variable. This function itself is independent of + * the value of `TZ`, but if @identifier is %NULL then `/etc/localtime` + * will be consulted to discover the correct time zone on UNIX and the + * registry will be consulted or GetTimeZoneInformation() will be used + * to get the local time zone on Windows. + * + * If intervals are not available, only time zone rules from `TZ` + * environment variable or other means, then they will be computed + * from year 1900 to 2037. If the maximum year for the rules is + * available and it is greater than 2037, then it will followed * instead. * - * See <ulink - * url='http://tools.ietf.org/html/rfc3339#section-5.6'>RFC3339 - * §5.6</ulink> for a precise definition of valid RFC3339 time offsets - * (the <varname>time-offset</varname> expansion) and ISO 8601 for the - * full list of valid time offsets. See <ulink - * url='http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html'>The - * GNU C Library manual</ulink> for an explanation of the possible - * values of the <varname>TZ</varname> environment variable. See <ulink - * url='http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx'> - * Microsoft Time Zone Index Values</ulink> for the list of time zones - * on Windows. + * See + * [RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6) + * for a precise definition of valid RFC3339 time offsets + * (the `time-offset` expansion) and ISO 8601 for the + * full list of valid time offsets. See + * [The GNU C Library manual](http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html) + * for an explanation of the possible + * values of the `TZ` environment variable. See + * [Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx) + * for the list of time zones on Windows. * * You should release the return value by calling g_time_zone_unref() * when you are done with it. @@ -30450,9 +29945,8 @@ * zone may change between invocations to this function; for example, * if the system administrator changes it. * - * This is equivalent to calling g_time_zone_new() with the value of the - * <varname>TZ</varname> environment variable (including the possibility - * of %NULL). + * This is equivalent to calling g_time_zone_new() with the value of + * the `TZ` environment variable (including the possibility of %NULL). * * You should release the return value by calling g_time_zone_unref() * when you are done with it. @@ -30878,7 +30372,7 @@ * is O(log n) (where n is the number of key/value pairs in the tree). * * Returns: the value corresponding to the key, or %NULL - * if the key was not found. + * if the key was not found */ @@ -31018,7 +30512,7 @@ * pairs that have a larger key. * * Returns: the value corresponding to the found key, or %NULL - * if the key was not found. + * if the key was not found */ @@ -31151,24 +30645,23 @@ * g_ucs4_to_utf16: * @str: a UCS-4 encoded string * @len: the maximum length (number of characters) of @str to use. - * If @len < 0, then the string is nul-terminated. - * @items_read: (allow-none): location to store number of bytes read, or %NULL. - * If an error occurs then the index of the invalid input - * is stored here. - * @items_written: (allow-none): location to store number of <type>gunichar2</type> - * written, or %NULL. The value stored here does not - * include the trailing 0. + * If @len < 0, then the string is nul-terminated. + * @items_read: (allow-none): location to store number of bytes read, + * or %NULL. If an error occurs then the index of the invalid input + * is stored here. + * @items_written: (allow-none): location to store number of #gunichar2 + * written, or %NULL. The value stored here does not include the + * trailing 0. * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError other than - * %G_CONVERT_ERROR_NO_CONVERSION may occur. + * errors. Any of the errors in #GConvertError other than + * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UCS-4 to UTF-16. A 0 character will be * added to the result after the converted text. * * Returns: a pointer to a newly allocated UTF-16 string. - * This value must be freed with g_free(). If an - * error occurs, %NULL will be returned and - * @error set. + * This value must be freed with g_free(). If an error occurs, + * %NULL will be returned and @error set. */ @@ -31176,11 +30669,12 @@ * g_ucs4_to_utf8: * @str: a UCS-4 encoded string * @len: the maximum length (number of characters) of @str to use. - * If @len < 0, then the string is nul-terminated. - * @items_read: (allow-none): location to store number of characters read, or %NULL. - * @items_written: (allow-none): location to store number of bytes written or %NULL. - * The value here stored does not include the trailing 0 - * byte. + * If @len < 0, then the string is nul-terminated. + * @items_read: (allow-none): location to store number of characters + * read, or %NULL. + * @items_written: (allow-none): location to store number of bytes + * written or %NULL. The value here stored does not include the + * trailing 0 byte. * @error: location to store the error occurring, or %NULL to ignore * errors. Any of the errors in #GConvertError other than * %G_CONVERT_ERROR_NO_CONVERSION may occur. @@ -31189,11 +30683,9 @@ * to UTF-8. The result will be terminated with a 0 byte. * * Returns: a pointer to a newly allocated UTF-8 string. - * This value must be freed with g_free(). If an - * error occurs, %NULL will be returned and - * @error set. In that case, @items_read will be - * set to the position of the first invalid input - * character. + * This value must be freed with g_free(). If an error occurs, + * %NULL will be returned and @error set. In that case, @items_read + * will be set to the position of the first invalid input character. */ @@ -31242,7 +30734,8 @@ * * If @a and @b do not compose a new character, @ch is set to zero. * - * See <ulink url="http://unicode.org/reports/tr15/">UAX#15</ulink> + * See + * [UAX#15](http://unicode.org/reports/tr15/) * for details. * * Returns: %TRUE if the characters could be composed @@ -31276,7 +30769,8 @@ * recursively call this function on @a. Or use * g_unichar_fully_decompose(). * - * See <ulink url="http://unicode.org/reports/tr15/">UAX#15</ulink> + * See + * [UAX#15](http://unicode.org/reports/tr15/) * for details. * * Returns: %TRUE if the character could be decomposed @@ -31319,7 +30813,8 @@ * decompositions, so that is the size recommended. This is provided * as %G_UNICHAR_MAX_DECOMPOSITION_LENGTH. * - * See <ulink url="http://unicode.org/reports/tr15/">UAX#15</ulink> + * See + * [UAX#15](http://unicode.org/reports/tr15/) * for details. * * Returns: the length of the full decomposition. @@ -31332,10 +30827,10 @@ * @ch: a Unicode character * @mirrored_ch: location to store the mirrored character * - * In Unicode, some characters are <firstterm>mirrored</firstterm>. This - * means that their images are mirrored horizontally in text that is laid - * out from right to left. For instance, "(" would become its mirror image, - * ")", in right-to-left text. + * In Unicode, some characters are "mirrored". This means that their + * images are mirrored horizontally in text that is laid out from right + * to left. For instance, "(" would become its mirror image, ")", in + * right-to-left text. * * If @ch has the Unicode mirrored property and there is another unicode * character that typically has a glyph that is the mirror image of @ch's @@ -31552,9 +31047,9 @@ * Determines if a character is typically rendered in a double-width * cell under legacy East Asian locales. If a character is wide according to * g_unichar_iswide(), then it is also reported wide with this function, but - * the converse is not necessarily true. See the - * <ulink url="http://www.unicode.org/reports/tr11/">Unicode Standard - * Annex #11</ulink> for details. + * the converse is not necessarily true. See the + * [Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/) + * for details. * * If a character passes the g_unichar_iswide() test then it will also pass * this test, but not the other way around. Note that some characters may @@ -31713,8 +31208,9 @@ * big-endian fashion. That is, the code expected for Arabic is * 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc). * - * See <ulink url="http://unicode.org/iso15924/codelists.html">Codes for the - * representation of names of scripts</ulink> for details. + * See + * [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) + * for details. * * Returns: the Unicode script for @iso15924, or * of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and @@ -31733,8 +31229,9 @@ * big-endian fashion. That is, the code returned for Arabic is * 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc). * - * See <ulink url="http://unicode.org/iso15924/codelists.html">Codes for the - * representation of names of scripts</ulink> for details. + * See + * [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) + * for details. * * Returns: the ISO 15924 code for @script, encoded as an integer, * of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or @@ -31808,19 +31305,17 @@ /** * 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). * Since: 2.30 @@ -31834,8 +31329,8 @@ * @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 * Since: 2.30 @@ -31880,17 +31375,15 @@ * @signum: A signal number * * Create a #GSource that will be dispatched upon delivery of the UNIX - * signal @signum. In GLib versions before 2.36, only - * <literal>SIGHUP</literal>, <literal>SIGINT</literal>, - * <literal>SIGTERM</literal> can be monitored. In GLib 2.36, - * <literal>SIGUSR1</literal> and <literal>SIGUSR2</literal> were - * added. + * signal @signum. In GLib versions before 2.36, only `SIGHUP`, `SIGINT`, + * `SIGTERM` can be monitored. In GLib 2.36, `SIGUSR1` and `SIGUSR2` + * were added. * * Note that unlike the UNIX default, all sources which have created a * watch will be dispatched, regardless of which underlying thread * invoked g_unix_signal_source_new(). * - * For example, an effective use of this function is to handle <literal>SIGTERM</literal> + * For example, an effective use of this function is to handle `SIGTERM` * cleanly; flushing any outstanding files, and then calling * g_main_loop_quit (). It is not safe to do any of this a regular * UNIX signal handler; your handler may be invoked while malloc() or @@ -31938,20 +31431,18 @@ * Note that on some systems, when variables are overwritten, the * memory used for the previous variables and its value isn't reclaimed. * - * <warning><para> - * Environment variable handling in UNIX is not thread-safe, and your - * program may crash if one thread calls g_unsetenv() while another - * thread is calling getenv(). (And note that many functions, such as - * gettext(), call getenv() internally.) This function is only safe - * to use at the very start of your program, before creating any other - * threads (or creating objects that create worker threads of their - * own). - * </para><para> + * You should be mindful of the fact that environment variable handling + * in UNIX is not thread-safe, and your program may crash if one thread + * calls g_unsetenv() while another thread is calling getenv(). (And note + * that many functions, such as gettext(), call getenv() internally.) This + * function is only safe to use at the very start of your program, before + * creating any other threads (or creating objects that create worker + * threads of their own). + * * If you need to set up the environment for a child process, you can * use g_get_environ() to get an environment array, modify that with * g_environ_setenv() and g_environ_unsetenv(), and then pass that * array directly to execvpe(), g_spawn_async(), or the like. - * </para></warning> * * Since: 2.4 */ @@ -31999,9 +31490,9 @@ * @uri: a valid URI. * * Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as: - * <programlisting> + * |[ * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] - * </programlisting> + * ]| * Common schemes include "file", "http", "svn+ssh", etc. * * Returns: The "Scheme" component of the URI, or %NULL on error. @@ -32068,46 +31559,42 @@ /** * g_utf16_to_ucs4: * @str: a UTF-16 encoded string - * @len: the maximum length (number of <type>gunichar2</type>) of @str to use. - * If @len < 0, then the string is nul-terminated. - * @items_read: (allow-none): location to store number of words read, or %NULL. - * If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be - * returned in case @str contains a trailing partial - * character. If an error occurs then the index of the - * invalid input is stored here. - * @items_written: (allow-none): location to store number of characters written, or %NULL. - * The value stored here does not include the trailing - * 0 character. + * @len: the maximum length (number of #gunichar2) of @str to use. + * If @len < 0, then the string is nul-terminated. + * @items_read: (allow-none): location to store number of words read, + * or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be + * returned in case @str contains a trailing partial character. If + * an error occurs then the index of the invalid input is stored here. + * @items_written: (allow-none): location to store number of characters + * written, or %NULL. The value stored here does not include the trailing + * 0 character. * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError other than - * %G_CONVERT_ERROR_NO_CONVERSION may occur. + * errors. Any of the errors in #GConvertError other than + * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UTF-16 to UCS-4. The result will be * nul-terminated. * * Returns: a pointer to a newly allocated UCS-4 string. - * This value must be freed with g_free(). If an - * error occurs, %NULL will be returned and - * @error set. + * This value must be freed with g_free(). If an error occurs, + * %NULL will be returned and @error set. */ /** * g_utf16_to_utf8: * @str: a UTF-16 encoded string - * @len: the maximum length (number of <type>gunichar2</type>) of @str to use. - * If @len < 0, then the string is nul-terminated. - * @items_read: (allow-none): location to store number of words read, or %NULL. - * If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be - * returned in case @str contains a trailing partial - * character. If an error occurs then the index of the - * invalid input is stored here. - * @items_written: (allow-none): location to store number of bytes written, or %NULL. - * The value stored here does not include the trailing - * 0 byte. + * @len: the maximum length (number of #gunichar2) of @str to use. + * If @len < 0, then the string is nul-terminated. + * @items_read: (allow-none): location to store number of words read, + * or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be + * returned in case @str contains a trailing partial character. If + * an error occurs then the index of the invalid input is stored here. + * @items_written: (allow-none): location to store number of bytes written, + * or %NULL. The value stored here does not include the trailing 0 byte. * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError other than - * %G_CONVERT_ERROR_NO_CONVERSION may occur. + * errors. Any of the errors in #GConvertError other than + * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UTF-16 to UTF-8. The result will be * terminated with a 0 byte. @@ -32124,9 +31611,8 @@ * things unpaired surrogates. * * Returns: a pointer to a newly allocated UTF-8 string. - * This value must be freed with g_free(). If an - * error occurs, %NULL will be returned and - * @error set. + * This value must be freed with g_free(). If an error occurs, + * %NULL will be returned and @error set. */ @@ -32218,7 +31704,7 @@ * g_utf8_find_next_char: * @p: a pointer to a position within a UTF-8 encoded string * @end: a pointer to the byte following the end of the string, - * or %NULL to indicate that the string is nul-terminated. + * or %NULL to indicate that the string is nul-terminated * * Finds the start of the next UTF-8 character in the string after @p. * @@ -32252,8 +31738,9 @@ * @p: a pointer to Unicode character encoded as UTF-8 * * Converts a sequence of bytes encoded as UTF-8 to a Unicode character. - * If @p does not point to a valid UTF-8 encoded character, results are - * undefined. If you are not sure that the bytes are complete + * + * If @p does not point to a valid UTF-8 encoded character, results + * are undefined. If you are not sure that the bytes are complete * valid Unicode characters, you should use g_utf8_get_char_validated() * instead. * @@ -32265,7 +31752,7 @@ * g_utf8_get_char_validated: * @p: a pointer to Unicode character encoded as UTF-8 * @max_len: the maximum number of bytes to read, or -1, for no maximum or - * if @p is nul-terminated + * if @p is nul-terminated * * Convert a sequence of bytes encoded as UTF-8 to a Unicode character. * This function checks for incomplete characters, for invalid characters @@ -32273,10 +31760,10 @@ * overlong encodings of valid characters. * * Returns: the resulting character. If @p points to a partial - * sequence at the end of a string that could begin a valid - * character (or if @max_len is zero), returns (gunichar)-2; - * otherwise, if @p does not point to a valid UTF-8 encoded - * Unicode character, returns (gunichar)-1. + * sequence at the end of a string that could begin a valid + * character (or if @max_len is zero), returns (gunichar)-2; + * otherwise, if @p does not point to a valid UTF-8 encoded + * Unicode character, returns (gunichar)-1. */ @@ -32331,14 +31818,11 @@ * instead of forwards if @offset is in the last fourth of the string, * since moving forward is about 3 times faster than moving backward. * - * <note><para> - * This function doesn't abort when reaching the end of @str. Therefore - * you should be sure that @offset is within string boundaries before - * calling that function. Call g_utf8_strlen() when unsure. - * + * Note that this function doesn't abort when reaching the end of @str. + * Therefore you should be sure that @offset is within string boundaries + * before calling that function. Call g_utf8_strlen() when unsure. * This limitation exists as this function is called frequently during * text rendering and therefore has to be as fast as possible. - * </para></note> * * Returns: the resulting pointer */ @@ -32370,7 +31854,7 @@ * it starts with an appropriate byte. If @p might be the first * character of the string, you must use g_utf8_find_prev_char() instead. * - * Returns: a pointer to the found character. + * Returns: a pointer to the found character */ @@ -32385,8 +31869,8 @@ * If @len is -1, allow unbounded search. * * Returns: %NULL if the string does not contain the character, - * otherwise, a pointer to the start of the leftmost occurrence of - * the character in the string. + * otherwise, a pointer to the start of the leftmost occurrence + * of the character in the string. */ @@ -32428,11 +31912,10 @@ * @src: UTF-8 encoded string * @n: character count * - * Like the standard C strncpy() function, but - * copies a given number of characters instead of a given number of - * bytes. The @src string must be valid UTF-8 encoded text. - * (Use g_utf8_validate() on all text before trying to use UTF-8 - * utility functions with it.) + * Like the standard C strncpy() function, but copies a given number + * of characters instead of a given number of bytes. The @src string + * must be valid UTF-8 encoded text. (Use g_utf8_validate() on all + * text before trying to use UTF-8 utility functions with it.) * * Returns: @dest */ @@ -32449,8 +31932,8 @@ * If @len is -1, allow unbounded search. * * Returns: %NULL if the string does not contain the character, - * otherwise, a pointer to the start of the rightmost occurrence of the - * character in the string. + * otherwise, a pointer to the start of the rightmost occurrence + * of the character in the string. */ @@ -32458,7 +31941,7 @@ * g_utf8_strreverse: * @str: a UTF-8 encoded string * @len: the maximum length of @str to use, in bytes. If @len < 0, - * then the string is nul-terminated. + * then the string is nul-terminated. * * Reverses a UTF-8 string. @str must be valid UTF-8 encoded text. * (Use g_utf8_validate() on all text before trying to use UTF-8 @@ -32474,7 +31957,7 @@ * newly-allocated memory, which should be freed with g_free() when * no longer needed. * - * Returns: a newly-allocated string which is the reverse of @str. + * Returns: a newly-allocated string which is the reverse of @str * Since: 2.2 */ @@ -32502,8 +31985,7 @@ * @end_pos: another character offset within @str * * Copies a substring out of a UTF-8 encoded string. - * The substring will contain @end_pos - @start_pos - * characters. + * The substring will contain @end_pos - @start_pos characters. * * Returns: a newly allocated copy of the requested * substring. Free with g_free() when no longer needed. @@ -32515,27 +31997,26 @@ * g_utf8_to_ucs4: * @str: a UTF-8 encoded string * @len: the maximum length of @str to use, in bytes. If @len < 0, - * then the string is nul-terminated. + * then the string is nul-terminated. * @items_read: (allow-none): location to store number of bytes read, or %NULL. - * If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be - * returned in case @str contains a trailing partial - * character. If an error occurs then the index of the - * invalid input is stored here. - * @items_written: (allow-none): location to store number of characters written or %NULL. - * The value here stored does not include the trailing 0 - * character. + * If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be + * returned in case @str contains a trailing partial + * character. If an error occurs then the index of the + * invalid input is stored here. + * @items_written: (allow-none): location to store number of characters + * written or %NULL. The value here stored does not include the + * trailing 0 character. * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError other than - * %G_CONVERT_ERROR_NO_CONVERSION may occur. + * errors. Any of the errors in #GConvertError other than + * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UTF-8 to a 32-bit fixed width * representation as UCS-4. A trailing 0 character will be added to the * string after the converted text. * * Returns: a pointer to a newly allocated UCS-4 string. - * This value must be freed with g_free(). If an - * error occurs, %NULL will be returned and - * @error set. + * This value must be freed with g_free(). If an error occurs, + * %NULL will be returned and @error set. */ @@ -32543,9 +32024,9 @@ * g_utf8_to_ucs4_fast: * @str: a UTF-8 encoded string * @len: the maximum length of @str to use, in bytes. If @len < 0, - * then the string is nul-terminated. - * @items_written: (allow-none): location to store the number of characters in the - * result, or %NULL. + * then the string is nul-terminated. + * @items_written: (allow-none): location to store the number of + * characters in the result, or %NULL. * * Convert a string from UTF-8 to a 32-bit fixed width * representation as UCS-4, assuming valid UTF-8 input. @@ -32554,7 +32035,7 @@ * will be added to the string after the converted text. * * Returns: a pointer to a newly allocated UCS-4 string. - * This value must be freed with g_free(). + * This value must be freed with g_free(). */ @@ -32562,26 +32043,24 @@ * g_utf8_to_utf16: * @str: a UTF-8 encoded string * @len: the maximum length (number of bytes) of @str to use. - * If @len < 0, then the string is nul-terminated. - * @items_read: (allow-none): location to store number of bytes read, or %NULL. - * If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be - * returned in case @str contains a trailing partial - * character. If an error occurs then the index of the - * invalid input is stored here. - * @items_written: (allow-none): location to store number of <type>gunichar2</type> written, - * or %NULL. - * The value stored here does not include the trailing 0. + * If @len < 0, then the string is nul-terminated. + * @items_read: (allow-none): location to store number of bytes read, + * or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be + * returned in case @str contains a trailing partial character. If + * an error occurs then the index of the invalid input is stored here. + * @items_written: (allow-none): location to store number of #gunichar2 + * written, or %NULL. The value stored here does not include the + * trailing 0. * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError other than - * %G_CONVERT_ERROR_NO_CONVERSION may occur. + * errors. Any of the errors in #GConvertError other than + * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UTF-8 to UTF-16. A 0 character will be * added to the result after the converted text. * * Returns: a pointer to a newly allocated UTF-16 string. - * This value must be freed with g_free(). If an - * error occurs, %NULL will be returned and - * @error set. + * This value must be freed with g_free(). If an error occurs, + * %NULL will be returned and @error set. */ @@ -32600,12 +32079,12 @@ * being validated otherwise). * * Note that g_utf8_validate() returns %FALSE if @max_len is - * positive and any of the @max_len bytes are NUL. + * positive and any of the @max_len bytes are nul. * * Returns %TRUE if all of @str was valid. Many GLib and GTK+ - * routines <emphasis>require</emphasis> valid UTF-8 as input; - * so data read from a file or the network should be checked - * with g_utf8_validate() before doing anything else with it. + * routines require valid UTF-8 as input; so data read from a file + * or the network should be checked with g_utf8_validate() before + * doing anything else with it. * * Returns: %TRUE if the text was valid UTF-8 */ @@ -32622,8 +32101,7 @@ * See your C library manual for more details about how utime() works * on your system. * - * Returns: 0 if the operation was successful, -1 if an error - * occurred + * Returns: 0 if the operation was successful, -1 if an error occurred * Since: 2.18 */ @@ -32639,9 +32117,13 @@ * This call is a convenience wrapper that is exactly equivalent to * calling g_variant_new() followed by g_variant_builder_add_value(). * + * Note that the arguments must be of the correct width for their types + * specified in @format_string. This can be achieved by casting them. See + * the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>. + * * This function might be used as follows: * - * |[ + * |[<!-- language="C" --> * GVariant * * make_pointless_dictionary (void) * { @@ -32677,9 +32159,13 @@ * calling g_variant_new_parsed() followed by * g_variant_builder_add_value(). * + * Note that the arguments must be of the correct width for their types + * specified in @format_string. This can be achieved by casting them. See + * the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>. + * * This function might be used as follows: * - * |[ + * |[<!-- language="C" --> * GVariant * * make_pointless_dictionary (void) * { @@ -32975,6 +32461,224 @@ /** + * g_variant_dict_clear: + * @dict: a #GVariantDict + * + * Releases all memory associated with a #GVariantDict without freeing + * the #GVariantDict structure itself. + * + * It typically only makes sense to do this on a stack-allocated + * #GVariantDict if you want to abort building the value part-way + * through. This function need not be called if you call + * g_variant_dict_end() and it also doesn't need to be called on dicts + * allocated with g_variant_dict_new (see g_variant_dict_unref() for + * that). + * + * It is valid to call this function on either an initialised + * #GVariantDict or one that was previously cleared by an earlier call + * to g_variant_dict_clear() but it is not valid to call this function + * on uninitialised memory. + * + * Since: 2.40 + */ + + +/** + * g_variant_dict_contains: + * @dict: a #GVariantDict + * @key: the key to lookup in the dictionary + * + * Checks if @key exists in @dict. + * + * Returns: %TRUE if @key is in @dict + * Since: 2.40 + */ + + +/** + * g_variant_dict_end: + * @dict: a #GVariantDict + * + * Returns the current value of @dict as a #GVariant of type + * %G_VARIANT_TYPE_VARDICT, clearing it in the process. + * + * It is not permissible to use @dict in any way after this call except + * for reference counting operations (in the case of a heap-allocated + * #GVariantDict) or by reinitialising it with g_variant_dict_init() (in + * the case of stack-allocated). + * + * Returns: (transfer none): a new, floating, #GVariant + * Since: 2.40 + */ + + +/** + * g_variant_dict_init: (skip) + * @dict: a #GVariantDict + * @from_asv: (allow-none): the initial value for @dict + * + * Initialises a #GVariantDict structure. + * + * If @from_asv is given, it is used to initialise the dictionary. + * + * This function completely ignores the previous contents of @dict. On + * one hand this means that it is valid to pass in completely + * uninitialised memory. On the other hand, this means that if you are + * initialising over top of an existing #GVariantDict you need to first + * call g_variant_dict_clear() in order to avoid leaking memory. + * + * You must not call g_variant_dict_ref() or g_variant_dict_unref() on a + * #GVariantDict that was initialised with this function. If you ever + * pass a reference to a #GVariantDict outside of the control of your + * own code then you should assume that the person receiving that + * reference may try to use reference counting; you should use + * g_variant_dict_new() instead of this function. + * + * Since: 2.40 + */ + + +/** + * g_variant_dict_insert: + * @dict: a #GVariantDict + * @key: the key to insert a value for + * @format_string: a #GVariant varargs format string + * @...: arguments, as per @format_string + * + * Inserts a value into a #GVariantDict. + * + * This call is a convenience wrapper that is exactly equivalent to + * calling g_variant_new() followed by g_variant_dict_insert_value(). + * + * Since: 2.40 + */ + + +/** + * g_variant_dict_insert_value: + * @dict: a #GVariantDict + * @key: the key to insert a value for + * @value: the value to insert + * + * Inserts (or replaces) a key in a #GVariantDict. + * + * @value is consumed if it is floating. + * + * Since: 2.40 + */ + + +/** + * g_variant_dict_lookup: + * @dict: a #GVariantDict + * @key: the key to lookup in the dictionary + * @format_string: a GVariant format string + * @...: the arguments to unpack the value into + * + * Looks up a value in a #GVariantDict. + * + * This function is a wrapper around g_variant_dict_lookup_value() and + * g_variant_get(). In the case that %NULL would have been returned, + * this function returns %FALSE. Otherwise, it unpacks the returned + * value and returns %TRUE. + * + * @format_string determines the C types that are used for unpacking + * the values and also determines if the values are copied or borrowed, + * see the section on + * <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>. + * + * Returns: %TRUE if a value was unpacked + * Since: 2.40 + */ + + +/** + * g_variant_dict_lookup_value: + * @dict: a #GVariantDict + * @key: the key to lookup in the dictionary + * @expected_type: (allow-none): a #GVariantType, or %NULL + * + * Looks up a value in a #GVariantDict. + * + * If @key is not found in @dictionary, %NULL is returned. + * + * The @expected_type string specifies what type of value is expected. + * If the value associated with @key has a different type then %NULL is + * returned. + * + * If the key is found and the value has the correct type, it is + * returned. If @expected_type was specified then any non-%NULL return + * value will have this type. + * + * Returns: (transfer full): the value of the dictionary key, or %NULL + * Since: 2.40 + */ + + +/** + * g_variant_dict_new: + * @from_asv: (allow-none): the #GVariant with which to initialise the + * dictionary + * + * Allocates and initialises a new #GVariantDict. + * + * You should call g_variant_dict_unref() on the return value when it + * is no longer needed. The memory will not be automatically freed by + * any other call. + * + * In some cases it may be easier to place a #GVariantDict directly on + * the stack of the calling function and initialise it with + * g_variant_dict_init(). This is particularly useful when you are + * using #GVariantDict to construct a #GVariant. + * + * Returns: (transfer full): a #GVariantDict + * Since: 2.40 + */ + + +/** + * g_variant_dict_ref: + * @dict: a heap-allocated #GVariantDict + * + * Increases the reference count on @dict. + * + * Don't call this on stack-allocated #GVariantDict instances or bad + * things will happen. + * + * Returns: (transfer full): a new reference to @dict + * Since: 2.40 + */ + + +/** + * g_variant_dict_remove: + * @dict: a #GVariantDict + * @key: the key to remove + * + * Removes a key and its associated value from a #GVariantDict. + * + * Returns: %TRUE if the key was found and removed + * Since: 2.40 + */ + + +/** + * g_variant_dict_unref: + * @dict: (transfer full): a heap-allocated #GVariantDict + * + * Decreases the reference count on @dict. + * + * In the event that there are no more references, releases all memory + * associated with the #GVariantDict. + * + * Don't call this on stack-allocated #GVariantDict instances or bad + * things will happen. + * + * Since: 2.40 + */ + + +/** * g_variant_dup_bytestring: * @value: an array-of-bytes #GVariant instance * @length: (out) (allow-none) (default NULL): a pointer to a #gsize, to store @@ -33313,8 +33017,8 @@ * Memory</link>. * * In particular, arrays of these fixed-sized types can be interpreted - * as an array of the given C type, with @element_size set to - * <code>sizeof</code> the appropriate type: + * as an array of the given C type, with @element_size set to the size + * the appropriate type: * * <informaltable> * <tgroup cols='2'> @@ -33331,16 +33035,16 @@ * </tgroup> * </informaltable> * - * For example, if calling this function for an array of 32 bit integers, - * you might say <code>sizeof (gint32)</code>. This value isn't used - * except for the purpose of a double-check that the form of the - * serialised data matches the caller's expectation. + * For example, if calling this function for an array of 32-bit integers, + * you might say sizeof(gint32). This value isn't used except for the purpose + * of a double-check that the form of the serialised data matches the caller's + * expectation. * * @n_elements, which must be non-%NULL is set equal to the number of * items in the array. * * Returns: (array length=n_elements) (transfer none): a pointer to - * the fixed array + * the fixed array * Since: 2.24 */ @@ -33844,13 +33548,9 @@ * you must free or unreference all the unpacked values as you would with * g_variant_get(). Failure to do so will cause a memory leak. * - * See the section on <link linkend='gvariant-format-strings'>GVariant - * Format Strings</link>. - * - * <example> - * <title>Memory management with g_variant_iter_loop()</title> - * <programlisting> - * /<!-- -->* Iterates a dictionary of type 'a{sv}' *<!-- -->/ + * Here is an example for memory management with g_variant_iter_loop(): + * |[<!-- language="C" --> + * /* Iterates a dictionary of type 'a{sv}' */ * void * iterate_dictionary (GVariant *dictionary) * { @@ -33864,12 +33564,12 @@ * g_print ("Item '%s' has type '%s'\n", key, * g_variant_get_type_string (value)); * - * /<!-- -->* no need to free 'key' and 'value' here *<!-- -->/ - * /<!-- -->* unless breaking out of this loop *<!-- -->/ + * /* no need to free 'key' and 'value' here + * * unless breaking out of this loop + * */ * } * } - * </programlisting> - * </example> + * ]| * * For most cases you should use g_variant_iter_next(). * @@ -33883,8 +33583,9 @@ * thereby avoiding the need to free anything as well). * * @format_string determines the C types that are used for unpacking - * the values and also determines if the values are copied or borrowed, - * see the section on + * the values and also determines if the values are copied or borrowed. + * + * See the section on * <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>. * * Returns: %TRUE if a value was unpacked, or %FALSE if there was no @@ -33942,13 +33643,9 @@ * responsibility of the caller to free all of the values returned by * the unpacking process. * - * See the section on <link linkend='gvariant-format-strings'>GVariant - * Format Strings</link>. - * - * <example> - * <title>Memory management with g_variant_iter_next()</title> - * <programlisting> - * /<!-- -->* Iterates a dictionary of type 'a{sv}' *<!-- -->/ + * Here is an example for memory management with g_variant_iter_next(): + * |[<!-- language="C" --> + * /* Iterates a dictionary of type 'a{sv}' */ * void * iterate_dictionary (GVariant *dictionary) * { @@ -33962,20 +33659,20 @@ * g_print ("Item '%s' has type '%s'\n", key, * g_variant_get_type_string (value)); * - * /<!-- -->* must free data for ourselves *<!-- -->/ + * /* must free data for ourselves */ * g_variant_unref (value); * g_free (key); * } * } - * </programlisting> - * </example> + * ]| * * For a solution that is likely to be more convenient to C programmers * when dealing with loops, see g_variant_iter_loop(). * * @format_string determines the C types that are used for unpacking - * the values and also determines if the values are copied or borrowed, - * see the section on + * the values and also determines if the values are copied or borrowed. + * + * See the section on * <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>. * * Returns: %TRUE if a value was unpacked, or %FALSE if there as no value @@ -33993,10 +33690,9 @@ * Use g_variant_unref() to drop your reference on the return value when * you no longer need it. * - * <example> - * <title>Iterating with g_variant_iter_next_value()</title> - * <programlisting> - * /<!-- -->* recursively iterate a container *<!-- -->/ + * Here is an example for iterating with g_variant_iter_next_value(): + * |[<!-- language="C" --> + * /* recursively iterate a container */ * void * iterate_container_recursive (GVariant *container) * { @@ -34014,8 +33710,7 @@ * g_variant_unref (child); * } * } - * </programlisting> - * </example> + * ]| * * Returns: (allow-none) (transfer full): a #GVariant, or %NULL * Since: 2.24 @@ -34041,6 +33736,9 @@ * see the section on * <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>. * + * This function is currently implemented with a linear scan. If you + * plan to do many lookups then #GVariantDict may be more efficient. + * * Returns: %TRUE if a value was unpacked * Since: 2.28 */ @@ -34054,26 +33752,26 @@ * * Looks up a value in a dictionary #GVariant. * - * This function works with dictionaries of the type - * <literal>a{s*}</literal> (and equally well with type - * <literal>a{o*}</literal>, but we only further discuss the string case + * This function works with dictionaries of the type a{s*} (and equally + * well with type a{o*}, but we only further discuss the string case * for sake of clarity). * - * In the event that @dictionary has the type <literal>a{sv}</literal>, - * the @expected_type string specifies what type of value is expected to - * be inside of the variant. If the value inside the variant has a - * different type then %NULL is returned. In the event that @dictionary - * has a value type other than <literal>v</literal> then @expected_type - * must directly match the key type and it is used to unpack the value - * directly or an error occurs. + * In the event that @dictionary has the type a{sv}, the @expected_type + * string specifies what type of value is expected to be inside of the + * variant. If the value inside the variant has a different type then + * %NULL is returned. In the event that @dictionary has a value type other + * than v then @expected_type must directly match the key type and it is + * used to unpack the value directly or an error occurs. * - * In either case, if @key is not found in @dictionary, %NULL is - * returned. + * In either case, if @key is not found in @dictionary, %NULL is returned. * * If the key is found and the value has the correct type, it is * returned. If @expected_type was specified then any non-%NULL return * value will have this type. * + * This function is currently implemented with a linear scan. If you + * plan to do many lookups then #GVariantDict may be more efficient. + * * Returns: (transfer full): the value of the dictionary key, or %NULL * Since: 2.28 */ @@ -34119,6 +33817,21 @@ * 'r'; in essence, a new #GVariant must always be constructed by this * function (and not merely passed through it unmodified). * + * Note that the arguments must be of the correct width for their types + * specified in @format_string. This can be achieved by casting them. See + * the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>. + * + * <programlisting> + * MyFlags some_flags = FLAG_ONE | FLAG_TWO; + * const gchar *some_strings[] = { "a", "b", "c", NULL }; + * GVariant *new_variant; + * + * new_variant = g_variant_new ("(t^as)", + * /<!-- -->* This cast is required. *<!-- -->/ + * (guint64) some_flags, + * some_strings); + * </programlisting> + * * Returns: a new floating #GVariant instance * Since: 2.24 */ @@ -34246,11 +33959,11 @@ * @value must be an array with fixed-sized elements. Numeric types are * fixed-size as are tuples containing only other fixed-sized types. * - * @element_size must be the size of a single element in the array. For - * example, if calling this function for an array of 32 bit integers, - * you might say <code>sizeof (gint32)</code>. This value isn't used - * except for the purpose of a double-check that the form of the - * serialised data matches the caller's expectation. + * @element_size must be the size of a single element in the array. + * For example, if calling this function for an array of 32-bit integers, + * you might say sizeof(gint32). This value isn't used except for the purpose + * of a double-check that the form of the serialised data matches the caller's + * expectation. * * @n_elements, which must be non-%NULL is set equal to the number of * items in the array. @@ -34429,15 +34142,21 @@ * that case, the same arguments are collected from the argument list as * g_variant_new() would have collected. * - * Consider this simple example: + * Note that the arguments must be of the correct width for their types + * specified in @format. This can be achieved by casting them. See + * the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>. * - * <informalexample><programlisting> + * Consider this simple example: + * |[<!-- language="C" --> * g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three"); - * </programlisting></informalexample> + * ]| * * In the example, the variable argument parameters are collected and * filled in as if they were part of the original string to produce the - * result of <code>[('one', 1), ('two', 2), ('three', 3)]</code>. + * result of + * |[<!-- language="C" --> + * [('one', 1), ('two', 2), ('three', 3)] + * ]| * * This function is intended only to be used with @format as a string * literal. Any parse error is fatal to the calling process. If you @@ -34468,6 +34187,10 @@ * #GVariant pointer will be returned unmodified, without adding any * additional references. * + * Note that the arguments in @app must be of the correct width for their types + * specified in @format when collected into the #va_list. See + * the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>. + * * In order to behave correctly in all cases it is necessary for the * calling function to g_variant_ref_sink() the return result before * returning control to the user that originally provided the pointer. @@ -34633,6 +34356,10 @@ * @format_string, are collected from this #va_list and the list is left * pointing to the argument following the last. * + * Note that the arguments in @app must be of the correct width for their types + * specified in @format_string when collected into the #va_list. See + * the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>. + * * These two generalisations allow mixing of multiple calls to * g_variant_new_va() and g_variant_get_va() within a single actual * varargs call by the user. @@ -34754,6 +34481,13 @@ /** + * g_variant_parser_get_error_quark: + * + * Deprecated: Use g_variant_parse_error_quark() instead. + */ + + +/** * g_variant_print: * @value: a #GVariant * @type_annotate: %TRUE if type information should be included in @@ -34804,7 +34538,7 @@ * @value: a #GVariant * * #GVariant uses a floating reference count system. All functions with - * names starting with <literal>g_variant_new_</literal> return floating + * names starting with `g_variant_new_` return floating * references. * * Calling g_variant_ref_sink() on a #GVariant with a floating reference @@ -35572,13 +35306,13 @@ * * A convenience function/macro to log a warning message. * - * You can make warnings fatal at runtime by setting the - * <envar>G_DEBUG</envar> environment variable (see - * <ulink url="glib-running.html">Running GLib Applications</ulink>). + * You can make warnings fatal at runtime by setting the `G_DEBUG` + * environment variable (see + * [Running GLib Applications](glib-running.html)). * - * If g_log_default_handler() is used as the log handler function, a new-line - * character will automatically be appended to @..., and need not be entered - * manually. + * If g_log_default_handler() is used as the log handler function, + * a newline character will automatically be appended to @..., and + * need not be entered manually. */ @@ -35651,10 +35385,10 @@ * * The original intended use of @package was for a short identifier of * the package, typically the same identifier as used for - * <literal>GETTEXT_PACKAGE</literal> in software configured using GNU + * `GETTEXT_PACKAGE` in software configured using GNU * autotools. The function first looks in the Windows Registry for the - * value <literal>#InstallationDirectory</literal> in the key - * <literal>#HKLM\Software\@package</literal>, and if that value + * value `#InstallationDirectory` in the key + * `#HKLM\Software\@package`, and if that value * exists and is a string, returns that. * * It is strongly recommended that packagers of GLib-using libraries @@ -35833,7 +35567,7 @@ /** * gchar: * - * Corresponds to the standard C <type>char</type> type. + * Corresponds to the standard C char type. */ @@ -35851,7 +35585,7 @@ /** * gdouble: * - * Corresponds to the standard C <type>double</type> type. + * Corresponds to the standard C double type. * Values of this type can range from -#G_MAXDOUBLE to #G_MAXDOUBLE. */ @@ -35859,7 +35593,7 @@ /** * gfloat: * - * Corresponds to the standard C <type>float</type> type. + * Corresponds to the standard C float type. * Values of this type can range from -#G_MAXFLOAT to #G_MAXFLOAT. */ @@ -35867,7 +35601,7 @@ /** * gint: * - * Corresponds to the standard C <type>int</type> type. + * Corresponds to the standard C int type. * Values of this type can range from #G_MININT to #G_MAXINT. */ @@ -35921,7 +35655,7 @@ /** * gintptr: * - * Corresponds to the C99 type <type>intptr_t</type>, + * Corresponds to the C99 type intptr_t, * a signed integer type that can hold any pointer. * * To print or scan values of this type, use @@ -35942,9 +35676,9 @@ /** * glib_check_version: - * @required_major: the required major version. - * @required_minor: the required minor version. - * @required_micro: the required micro version. + * @required_major: the required major version + * @required_minor: the required minor version + * @required_micro: the required micro version * * Checks that the GLib library in use is compatible with the * given version. Generally you would pass in the constants @@ -35962,9 +35696,9 @@ * (same major version.) * * Returns: %NULL if the GLib library is compatible with the - * given version, or a string describing the version mismatch. - * The returned string is owned by GLib and must not be modified - * or freed. + * given version, or a string describing the version mismatch. + * The returned string is owned by GLib and must not be modified + * or freed. * Since: 2.6 */ @@ -36011,7 +35745,7 @@ /** * glong: * - * Corresponds to the standard C <type>long</type> type. + * Corresponds to the standard C long type. * Values of this type can range from #G_MINLONG to #G_MAXLONG. */ @@ -36020,7 +35754,7 @@ * goffset: * * A signed integer type that is used for file offsets, - * corresponding to the C99 type <type>off64_t</type>. + * corresponding to the C99 type off64_t. * Values of this type can range from #G_MINOFFSET to * #G_MAXOFFSET. * @@ -36035,15 +35769,14 @@ * gpointer: * * An untyped pointer. - * #gpointer looks better and is easier to use - * than <type>void*</type>. + * #gpointer looks better and is easier to use than void*. */ /** * gshort: * - * Corresponds to the standard C <type>short</type> type. + * Corresponds to the standard C short type. * Values of this type can range from #G_MINSHORT to #G_MAXSHORT. */ @@ -36052,10 +35785,10 @@ * gsize: * * An unsigned integer type of the result of the sizeof operator, - * corresponding to the <type>size_t</type> type defined in C99. + * corresponding to the size_t type defined in C99. * This type is wide enough to hold the numeric value of a pointer, - * so it is usually 32bit wide on a 32bit platform and 64bit wide - * on a 64bit platform. Values of this type can range from 0 to + * so it is usually 32 bit wide on a 32-bit platform and 64 bit wide + * on a 64-bit platform. Values of this type can range from 0 to * #G_MAXSIZE. * * To print or scan values of this type, use @@ -36067,7 +35800,7 @@ * gssize: * * A signed variant of #gsize, corresponding to the - * <type>ssize_t</type> defined on most platforms. + * ssize_t defined on most platforms. * Values of this type can range from #G_MINSSIZE * to #G_MAXSSIZE. * @@ -36079,14 +35812,14 @@ /** * guchar: * - * Corresponds to the standard C <type>unsigned char</type> type. + * Corresponds to the standard C unsigned char type. */ /** * guint: * - * Corresponds to the standard C <type>unsigned int</type> type. + * Corresponds to the standard C unsigned int type. * Values of this type can range from 0 to #G_MAXUINT. */ @@ -36116,7 +35849,7 @@ /** * 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). * @@ -36136,7 +35869,7 @@ /** * guintptr: * - * Corresponds to the C99 type <type>uintptr_t</type>, + * Corresponds to the C99 type uintptr_t, * an unsigned integer type that can hold any pointer. * * To print or scan values of this type, use @@ -36149,7 +35882,7 @@ /** * gulong: * - * Corresponds to the standard C <type>unsigned long</type> type. + * Corresponds to the standard C unsigned long type. * Values of this type can range from 0 to #G_MAXULONG. */ @@ -36157,7 +35890,7 @@ /** * gushort: * - * Corresponds to the standard C <type>unsigned short</type> type. + * Corresponds to the standard C unsigned short type. * Values of this type can range from 0 to #G_MAXUSHORT. */ |