luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-05 02:36:19 +01:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Convert examples to |[ ]|

Browse Source
This commit is contained in:
Matthias Clasen 2014-01-31 21:56:33 -05:00
parent 4d12e0d66f
commit 17f51583a8
27 changed files with 346 additions and 442 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
gio/gactionmap.c
View File

@ -160,9 +160,7 @@ g_action_map_remove_action (GActionMap *action_map,
* *
* Each action is constructed as per one #GActionEntry. * Each action is constructed as per one #GActionEntry.
* *
* <example> * |[
* <title>Using g_action_map_add_action_entries()</title>
* <programlisting>
* static void * static void
* activate_quit (GSimpleAction *simple, * activate_quit (GSimpleAction *simple,
* GVariant *parameter, * GVariant *parameter,
@ -193,8 +191,7 @@ g_action_map_remove_action (GActionMap *action_map,
* *
* return G_ACTION_GROUP (group); * return G_ACTION_GROUP (group);
* } * }
* </programlisting> * ]|
* </example>
* *
* Since: 2.32 * Since: 2.32
*/ */

22
gio/gapplication.c
View File

@ -75,17 +75,17 @@
* On Linux, the D-Bus session bus is used for communication. * On Linux, the D-Bus session bus is used for communication.
* *
* The use of #GApplication differs from some other commonly-used * The use of #GApplication differs from some other commonly-used
* uniqueness libraries (such as libunique) in important ways. The * uniqueness libraries (such as libunique) in important ways. The
* application is not expected to manually register itself and check if * application is not expected to manually register itself and check
* it is the primary instance. Instead, the <code>main()</code> * if it is the primary instance. Instead, the main() function of a
* function of a #GApplication should do very little more than * #GApplication should do very little more than instantiating the
* instantiating the application instance, possibly connecting signal * application instance, possibly connecting signal handlers, then
* handlers, then calling g_application_run(). All checks for * calling g_application_run(). All checks for uniqueness are done
* uniqueness are done internally. If the application is the primary * internally. If the application is the primary instance then the
* instance then the startup signal is emitted and the mainloop runs. * startup signal is emitted and the mainloop runs. If the application
* If the application is not the primary instance then a signal is sent * is not the primary instance then a signal is sent to the primary
* to the primary instance and g_application_run() promptly returns. * instance and g_application_run() promptly returns. See the code
* See the code examples below. * examples below.
* *
* If used, the expected form of an application identifier is very close * If used, the expected form of an application identifier is very close
* to that of of a * to that of of a

7
gio/gcontenttype.c
View File

@ -789,11 +789,10 @@ enumerate_mimetypes_dir (const char *dir,
* *
* Gets a list of strings containing all the registered content types * Gets a list of strings containing all the registered content types
* known to the system. The list and its data should be freed using * known to the system. The list and its data should be freed using
* <programlisting> * g_list_free_full (list, g_free).
* g_list_free_full (list, g_free);
* </programlisting>
* *
* Returns: (element-type utf8) (transfer full): #GList of the registered content types * Returns: (element-type utf8) (transfer full): list of the registered
* content types
*/ */
GList * GList *
g_content_types_get_registered (void) g_content_types_get_registered (void)

16
gio/gdbuserror.c
View File

@ -55,8 +55,8 @@
* automatically map from D-Bus errors to #GError and back. This * automatically map from D-Bus errors to #GError and back. This
* is typically done in the function returning the #GQuark for the * is typically done in the function returning the #GQuark for the
* error domain: * error domain:
* <example id="error-registration"><title>Error Registration</title><programlisting> * |[
* /<!-- -->* foo-bar-error.h: *<!-- -->/ * /&ast; foo-bar-error.h: &ast;/
* *
* #define FOO_BAR_ERROR (foo_bar_error_quark ()) * #define FOO_BAR_ERROR (foo_bar_error_quark ())
* GQuark foo_bar_error_quark (void); * GQuark foo_bar_error_quark (void);
@ -66,10 +66,10 @@
* FOO_BAR_ERROR_FAILED, * FOO_BAR_ERROR_FAILED,
* FOO_BAR_ERROR_ANOTHER_ERROR, * FOO_BAR_ERROR_ANOTHER_ERROR,
* FOO_BAR_ERROR_SOME_THIRD_ERROR, * FOO_BAR_ERROR_SOME_THIRD_ERROR,
* FOO_BAR_N_ERRORS /<!-- -->*< skip >*<!-- -->/ * FOO_BAR_N_ERRORS /&ast;< skip >&ast;/
* } FooBarError; * } FooBarError;
* *
* /<!-- -->* foo-bar-error.c: *<!-- -->/ * /&ast; foo-bar-error.c: &ast;/
* *
* static const GDBusErrorEntry foo_bar_error_entries[] = * static const GDBusErrorEntry foo_bar_error_entries[] =
* { * {
@ -78,7 +78,7 @@
* {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"}, * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
* }; * };
* *
* /<!-- -->* Ensure that every error code has an associated D-Bus error name *<!-- -->/ * /&ast; Ensure that every error code has an associated D-Bus error name &ast;/
* G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS); * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS);
* *
* GQuark * GQuark
@ -91,15 +91,15 @@
* G_N_ELEMENTS (foo_bar_error_entries)); * G_N_ELEMENTS (foo_bar_error_entries));
* return (GQuark) quark_volatile; * return (GQuark) quark_volatile;
* } * }
* </programlisting></example> * ]|
* With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and * With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and
* other peers will see the D-Bus error name <literal>org.project.Foo.Bar.Error.AnotherError</literal>. * other peers will see the D-Bus error name org.project.Foo.Bar.Error.AnotherError.
* *
* If the other peer is using GDBus, and has registered the association with * If the other peer is using GDBus, and has registered the association with
* g_dbus_error_register_error_domain() in advance (e.g. by invoking the %FOO_BAR_ERROR quark * g_dbus_error_register_error_domain() in advance (e.g. by invoking the %FOO_BAR_ERROR quark
* generation itself in the previous example) the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead * generation itself in the previous example) the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead
* of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover * of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover
* <literal>org.project.Foo.Bar.Error.AnotherError</literal> using g_dbus_error_get_remote_error(). * org.project.Foo.Bar.Error.AnotherError using g_dbus_error_get_remote_error().
* *
* Note that errors in the %G_DBUS_ERROR error domain is intended only * Note that errors in the %G_DBUS_ERROR error domain is intended only
* for returning errors from a remote message bus process. Errors * for returning errors from a remote message bus process. Errors

8
gio/gdbusmessage.c
View File

@ -3349,7 +3349,7 @@ _sort_keys_func (gconstpointer a,
* The contents of the description has no ABI guarantees, the contents * The contents of the description has no ABI guarantees, the contents
* and formatting is subject to change at any time. Typical output * and formatting is subject to change at any time. Typical output
* looks something like this: * looks something like this:
* <programlisting> * |[
* Type&colon; method-call * Type&colon; method-call
* Flags&colon; none * Flags&colon; none
* Version&colon; 0 * Version&colon; 0
@ -3362,9 +3362,9 @@ _sort_keys_func (gconstpointer a,
* Body&colon; () * Body&colon; ()
* UNIX File Descriptors: * UNIX File Descriptors:
* (none) * (none)
* </programlisting> * ]|
* or * or
* <programlisting> * |[
* Type&colon; method-return * Type&colon; method-return
* Flags&colon; no-reply-expected * Flags&colon; no-reply-expected
* Version&colon; 0 * Version&colon; 0
@ -3377,7 +3377,7 @@ _sort_keys_func (gconstpointer a,
* Body&colon; () * Body&colon; ()
* UNIX File Descriptors&colon; * UNIX File Descriptors&colon;
* fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635 * fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
* </programlisting> * ]|
* *
* Returns: A string that should be freed with g_free(). * Returns: A string that should be freed with g_free().
* *

4
gio/gfile.c
View File

@ -447,9 +447,9 @@ g_file_has_uri_scheme (GFile *file,
* *
* Gets the URI scheme for a #GFile. * Gets the URI scheme for a #GFile.
* RFC 3986 decodes the scheme as: * RFC 3986 decodes the scheme as:
* <programlisting> * |[
* URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
* </programlisting> * ]|
* Common schemes include "file", "http", "ftp", etc. * Common schemes include "file", "http", "ftp", etc.
* *
* This call does no blocking I/O. * This call does no blocking I/O.

10
gio/gmenu.c
View File

@ -1203,8 +1203,7 @@ g_menu_item_new_submenu (const gchar *label,
* second with the "Cut", "Copy" and "Paste" items. The first and * second with the "Cut", "Copy" and "Paste" items. The first and
* second menus would then be added as submenus of the third. In XML * second menus would then be added as submenus of the third. In XML
* format, this would look something like the following: * format, this would look something like the following:
* * |[
* <informalexample><programlisting><![CDATA[
* <menu id='edit-menu'> * <menu id='edit-menu'>
* <section> * <section>
* <item label='Undo'/> * <item label='Undo'/>
@ -1216,7 +1215,7 @@ g_menu_item_new_submenu (const gchar *label,
* <item label='Paste'/> * <item label='Paste'/>
* </section> * </section>
* </menu> * </menu>
* ]]></programlisting></informalexample> * ]|
* *
* The following example is exactly equivalent. It is more illustrative * The following example is exactly equivalent. It is more illustrative
* of the exact relationship between the menus and items (keeping in * of the exact relationship between the menus and items (keeping in
@ -1224,8 +1223,7 @@ g_menu_item_new_submenu (const gchar *label,
* containing one). The style of the second example is more verbose and * containing one). The style of the second example is more verbose and
* difficult to read (and therefore not recommended except for the * difficult to read (and therefore not recommended except for the
* purpose of understanding what is really going on). * purpose of understanding what is really going on).
* * |[
* <informalexample><programlisting><![CDATA[
* <menu id='edit-menu'> * <menu id='edit-menu'>
* <item> * <item>
* <link name='section'> * <link name='section'>
@ -1241,7 +1239,7 @@ g_menu_item_new_submenu (const gchar *label,
* </link> * </link>
* </item> * </item>
* </menu> * </menu>
* ]]></programlisting></informalexample> * ]|
* *
* Returns: a new #GMenuItem * Returns: a new #GMenuItem
* *

10
gio/gresource.c
View File

@ -82,8 +82,8 @@ G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref)
* which takes an xml file that describes the bundle, and a set of files that the xml references. These * which takes an xml file that describes the bundle, and a set of files that the xml references. These
* are combined into a binary resource bundle. * are combined into a binary resource bundle.
* *
* <example id="resource-example"><title>Example resource description</title> * An example resource description:
* <programlisting><![CDATA[ * |[
* <?xml version="1.0" encoding="UTF-8"?> * <?xml version="1.0" encoding="UTF-8"?>
* <gresources> * <gresources>
* <gresource prefix="/org/gtk/Example"> * <gresource prefix="/org/gtk/Example">
@ -92,14 +92,14 @@ G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref)
* <file preprocess="xml-stripblanks">menumarkup.xml</file> * <file preprocess="xml-stripblanks">menumarkup.xml</file>
* </gresource> * </gresource>
* </gresources> * </gresources>
* ]]></programlisting></example> * ]|
* *
* This will create a resource bundle with the following files: * This will create a resource bundle with the following files:
* <programlisting><![CDATA[ * |[
* /org/gtk/Example/data/splashscreen.png * /org/gtk/Example/data/splashscreen.png
* /org/gtk/Example/dialog.ui * /org/gtk/Example/dialog.ui
* /org/gtk/Example/menumarkup.xml * /org/gtk/Example/menumarkup.xml
* ]]></programlisting> * ]|
* *
* Note that all resources in the process share the same namespace, so use java-style * Note that all resources in the process share the same namespace, so use java-style
* path prefixes (like in the above example) to avoid conflicts. * path prefixes (like in the above example) to avoid conflicts.

16
gio/gsettings.c
View File

@ -118,8 +118,8 @@
* access the numeric values corresponding to the string value of enum * access the numeric values corresponding to the string value of enum
* and flags keys. * and flags keys.
* *
* <example id="schema-default-values"><title>Default values</title> * An example for default value:
* <programlisting><![CDATA[ * |[
* <schemalist> * <schemalist>
* <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test"> * <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test">
* *
@ -137,10 +137,10 @@
* *
* </schema> * </schema>
* </schemalist> * </schemalist>
* ]]></programlisting></example> * ]|
* *
* <example id="schema-enumerated"><title>Ranges, choices and enumerated types</title> * An example for ranges, choices and enumerated types:
* <programlisting><![CDATA[ * |[
* <schemalist> * <schemalist>
* *
* <enum id="org.gtk.Test.myenum"> * <enum id="org.gtk.Test.myenum">
@ -183,7 +183,7 @@
* </key> * </key>
* </schema> * </schema>
* </schemalist> * </schemalist>
* ]]></programlisting></example> * ]|
* *
* <refsect2> * <refsect2>
* <title>Vendor overrides</title> * <title>Vendor overrides</title>
@ -197,11 +197,11 @@
* directory as the XML schema sources which can override default values. * directory as the XML schema sources which can override default values.
* The schema id serves as the group name in the key file, and the values * The schema id serves as the group name in the key file, and the values
* are expected in serialized GVariant form, as in the following example: * are expected in serialized GVariant form, as in the following example:
* <informalexample><programlisting> * |[
* [org.gtk.Example] * [org.gtk.Example]
* key1='string' * key1='string'
* key2=1.5 * key2=1.5
* </programlisting></informalexample> * ]|
* </para> * </para>
* <para> * <para>
* glib-compile-schemas expects schema files to have the extension * glib-compile-schemas expects schema files to have the extension

20
gio/gsimpleaction.c
View File

@ -394,13 +394,12 @@ g_simple_action_class_init (GSimpleActionClass *class)
* *
* If no handler is connected to this signal then the default * If no handler is connected to this signal then the default
* behaviour is to call g_simple_action_set_state() to set the state * behaviour is to call g_simple_action_set_state() to set the state
* to the requested value. If you connect a signal handler then no * to the requested value. If you connect a signal handler then no
* default action is taken. If the state should change then you must * default action is taken. If the state should change then you must
* call g_simple_action_set_state() from the handler. * call g_simple_action_set_state() from the handler.
* *
* <example> * An example of a 'change-state' handler:
* <title>Example 'change-state' handler</title> * |[
* <programlisting>
* static void * static void
* change_volume_state (GSimpleAction *action, * change_volume_state (GSimpleAction *action,
* GVariant *value, * GVariant *value,
@ -410,15 +409,14 @@ g_simple_action_class_init (GSimpleActionClass *class)
* *
* requested = g_variant_get_int32 (value); * requested = g_variant_get_int32 (value);
* *
* // Volume only goes from 0 to 10 * /&ast; Volume only goes from 0 to 10 &ast;/
* if (0 <= requested && requested <= 10) * if (0 <= requested && requested <= 10)
* g_simple_action_set_state (action, value); * g_simple_action_set_state (action, value);
* } * }
* </programlisting> * ]|
* </example>
* *
* The handler need not set the state to the requested value. It * The handler need not set the state to the requested value.
* could set it to any value at all, or take some other action. * It could set it to any value at all, or take some other action.
* *
* Since: 2.30 * Since: 2.30
*/ */
@ -434,7 +432,7 @@ g_simple_action_class_init (GSimpleActionClass *class)
/** /**
* GSimpleAction:name: * GSimpleAction:name:
* *
* The name of the action. This is mostly meaningful for identifying * The name of the action. This is mostly meaningful for identifying
* the action once it has been added to a #GSimpleActionGroup. * the action once it has been added to a #GSimpleActionGroup.
* *
* Since: 2.28 * Since: 2.28

31
gio/gtask.c
View File

@ -51,8 +51,8 @@
* you can use g_task_propagate_pointer() or the like to extract * you can use g_task_propagate_pointer() or the like to extract
* the return value. * the return value.
* </para> * </para>
* <example id="gtask-async"><title>GTask as a GAsyncResult</title> * Here is an example for using GTask as a GAsyncResult:
* <programlisting> * |[
* typedef struct { * typedef struct {
* CakeFrostingType frosting; * CakeFrostingType frosting;
* char *message; * char *message;
@ -144,8 +144,7 @@
* *
* return g_task_propagate_pointer (G_TASK (result), error); * return g_task_propagate_pointer (G_TASK (result), error);
* } * }
* </programlisting> * ]|
* </example>
* </refsect2> * </refsect2>
* <refsect2> * <refsect2>
* <title>Chained asynchronous operations</title> * <title>Chained asynchronous operations</title>
@ -161,8 +160,9 @@
* source to fire (automatically using the correct #GMainContext * source to fire (automatically using the correct #GMainContext
* and priority). * and priority).
* </para> * </para>
* <example id="gtask-chained"><title>Chained asynchronous operations</title> *
* <programlisting> * Here is an example for chained asynchronous operations:
* |[
* typedef struct { * typedef struct {
* Cake *cake; * Cake *cake;
* CakeFrostingType frosting; * CakeFrostingType frosting;
@ -287,8 +287,7 @@
* *
* return g_task_propagate_pointer (G_TASK (result), error); * return g_task_propagate_pointer (G_TASK (result), error);
* } * }
* </programlisting> * ]|
* </example>
* </refsect2> * </refsect2>
* <refsect2> * <refsect2>
* <title>Asynchronous operations from synchronous ones</title> * <title>Asynchronous operations from synchronous ones</title>
@ -298,8 +297,9 @@
* which will then dispatch the result back to the caller's * which will then dispatch the result back to the caller's
* #GMainContext when it completes. * #GMainContext when it completes.
* </para> * </para>
* <example id="gtask-run-in-thread"><title>g_task_run_in_thread()</title> *
* <programlisting> * Running a task in a thread:
* |[
* typedef struct { * typedef struct {
* guint radius; * guint radius;
* CakeFlavor flavor; * CakeFlavor flavor;
@ -366,8 +366,7 @@
* *
* return g_task_propagate_pointer (G_TASK (result), error); * return g_task_propagate_pointer (G_TASK (result), error);
* } * }
* </programlisting> * ]|
* </example>
* </refsect2> * </refsect2>
* <refsect2> * <refsect2>
* <title>Adding cancellability to uncancellable tasks</title> * <title>Adding cancellability to uncancellable tasks</title>
@ -384,8 +383,9 @@
* to make "GLib-friendly" asynchronous and cancellable * to make "GLib-friendly" asynchronous and cancellable
* synchronous variants of blocking APIs. * synchronous variants of blocking APIs.
* </para> * </para>
* <example id="gtask-cancellable"><title>g_task_set_return_on_cancel()</title> *
* <programlisting> * Cancelling a task:
* |[
* static void * static void
* bake_cake_thread (GTask *task, * bake_cake_thread (GTask *task,
* gpointer source_object, * gpointer source_object,
@ -474,8 +474,7 @@
* g_object_unref (task); * g_object_unref (task);
* return cake; * return cake;
* } * }
* </programlisting> * ]|
* </example>
* </refsect2> * </refsect2>
* <refsect2> * <refsect2>
* <title>Porting from <literal>GSimpleAsyncResult</literal></title> * <title>Porting from <literal>GSimpleAsyncResult</literal></title>

13
gio/gtestdbus.c
View File

@ -349,23 +349,22 @@ _g_test_watcher_remove_pid (GPid pid)
* achieve this by adding a file such as <filename>my-server.service.in</filename> * achieve this by adding a file such as <filename>my-server.service.in</filename>
* in the services * in the services
* directory and have it processed by configure. * directory and have it processed by configure.
* <informalexample><programlisting> * |[
* [D-BUS Service] * [D-BUS Service]
* Name=org.gtk.GDBus.Examples.ObjectManager * Name=org.gtk.GDBus.Examples.ObjectManager
* Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server * Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server
* </programlisting></informalexample> * ]|
* You will also need to indicate this service directory in your test * You will also need to indicate this service directory in your test
* fixtures, so you will need to pass the path while compiling your * fixtures, so you will need to pass the path while compiling your
* test cases. Typically this is done with autotools with an added * test cases. Typically this is done with autotools with an added
* preprocessor flag specified to compile your tests such as: * preprocessor flag specified to compile your tests such as:
* <informalexample><programlisting> * |[
* -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\" * -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\"
* </programlisting></informalexample> * ]|
* </para> * </para>
* <para> * <para>
* Once you have a service definition file which is local to your source tree, * Once you have a service definition file which is local to your source tree,
* you can proceed to set up a GTest fixture using the #GTestDBus scaffolding. * you can proceed to set up a GTest fixture using the #GTestDBus scaffolding.
* <example id="gdbus-test-fixture">
* <title>Test Fixture for D-Bus services</title> * <title>Test Fixture for D-Bus services</title>
* <programlisting> * <programlisting>
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-test-fixture.c"> * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-test-fixture.c">
@ -395,12 +394,12 @@ _g_test_watcher_remove_pid (GPid pid)
* The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved * The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved
* by compiling the schemas locally as a step before running test cases, an autotools setup might * by compiling the schemas locally as a step before running test cases, an autotools setup might
* do the following in the directory holding schemas: * do the following in the directory holding schemas:
* <informalexample><programlisting> * |[
* all-am: * all-am:
* $(GLIB_COMPILE_SCHEMAS) . * $(GLIB_COMPILE_SCHEMAS) .
* *
* CLEANFILES += gschemas.compiled * CLEANFILES += gschemas.compiled
* </programlisting></informalexample> * ]|
* </para> * </para>
* </refsect2> * </refsect2>
*/ */

124
gio/gvolume.c
View File

@ -87,7 +87,7 @@ g_volume_default_init (GVolumeInterface *iface)
* GVolume::changed: * GVolume::changed:
* *
* Emitted when the volume has been changed. * Emitted when the volume has been changed.
**/ */
g_signal_new (I_("changed"), g_signal_new (I_("changed"),
G_TYPE_VOLUME, G_TYPE_VOLUME,
G_SIGNAL_RUN_LAST, G_SIGNAL_RUN_LAST,
@ -102,7 +102,7 @@ g_volume_default_init (GVolumeInterface *iface)
* This signal is emitted when the #GVolume have been removed. If * This signal is emitted when the #GVolume have been removed. If
* the recipient is holding references to the object they should * the recipient is holding references to the object they should
* release them so the object can be finalized. * release them so the object can be finalized.
**/ */
g_signal_new (I_("removed"), g_signal_new (I_("removed"),
G_TYPE_VOLUME, G_TYPE_VOLUME,
G_SIGNAL_RUN_LAST, G_SIGNAL_RUN_LAST,
@ -114,13 +114,13 @@ g_volume_default_init (GVolumeInterface *iface)
/** /**
* g_volume_get_name: * g_volume_get_name:
* @volume: a #GVolume. * @volume: a #GVolume
* *
* Gets the name of @volume. * Gets the name of @volume.
* *
* Returns: the name for the given @volume. The returned string should * Returns: the name for the given @volume. The returned string should
* be freed with g_free() when no longer needed. * be freed with g_free() when no longer needed.
**/ */
char * char *
g_volume_get_name (GVolume *volume) g_volume_get_name (GVolume *volume)
{ {
@ -135,14 +135,14 @@ g_volume_get_name (GVolume *volume)
/** /**
* g_volume_get_icon: * g_volume_get_icon:
* @volume: a #GVolume. * @volume: a #GVolume
* *
* Gets the icon for @volume. * Gets the icon for @volume.
* *
* Returns: (transfer full): a #GIcon. * Returns: (transfer full): a #GIcon.
* The returned object should be unreffed with g_object_unref() * The returned object should be unreffed with g_object_unref()
* when no longer needed. * when no longer needed.
**/ */
GIcon * GIcon *
g_volume_get_icon (GVolume *volume) g_volume_get_icon (GVolume *volume)
{ {
@ -157,7 +157,7 @@ g_volume_get_icon (GVolume *volume)
/** /**
* g_volume_get_symbolic_icon: * g_volume_get_symbolic_icon:
* @volume: a #GVolume. * @volume: a #GVolume
* *
* Gets the symbolic icon for @volume. * Gets the symbolic icon for @volume.
* *
@ -166,7 +166,7 @@ g_volume_get_icon (GVolume *volume)
* when no longer needed. * when no longer needed.
* *
* Since: 2.34 * Since: 2.34
**/ */
GIcon * GIcon *
g_volume_get_symbolic_icon (GVolume *volume) g_volume_get_symbolic_icon (GVolume *volume)
{ {
@ -188,7 +188,7 @@ g_volume_get_symbolic_icon (GVolume *volume)
/** /**
* g_volume_get_uuid: * g_volume_get_uuid:
* @volume: a #GVolume. * @volume: a #GVolume
* *
* Gets the UUID for the @volume. The reference is typically based on * Gets the UUID for the @volume. The reference is typically based on
* the file system UUID for the volume in question and should be * the file system UUID for the volume in question and should be
@ -198,7 +198,7 @@ g_volume_get_symbolic_icon (GVolume *volume)
* Returns: the UUID for @volume or %NULL if no UUID can be computed. * Returns: the UUID for @volume or %NULL if no UUID can be computed.
* The returned string should be freed with g_free() * The returned string should be freed with g_free()
* when no longer needed. * when no longer needed.
**/ */
char * char *
g_volume_get_uuid (GVolume *volume) g_volume_get_uuid (GVolume *volume)
{ {
@ -213,14 +213,14 @@ g_volume_get_uuid (GVolume *volume)
/** /**
* g_volume_get_drive: * g_volume_get_drive:
* @volume: a #GVolume. * @volume: a #GVolume
* *
* Gets the drive for the @volume. * Gets the drive for the @volume.
* *
* Returns: (transfer full): a #GDrive or %NULL if @volume is not associated with a drive. * Returns: (transfer full): a #GDrive or %NULL if @volume is not
* The returned object should be unreffed with g_object_unref() * associated with a drive. The returned object should be unreffed
* when no longer needed. * with g_object_unref() when no longer needed.
**/ */
GDrive * GDrive *
g_volume_get_drive (GVolume *volume) g_volume_get_drive (GVolume *volume)
{ {
@ -235,14 +235,14 @@ g_volume_get_drive (GVolume *volume)
/** /**
* g_volume_get_mount: * g_volume_get_mount:
* @volume: a #GVolume. * @volume: a #GVolume
* *
* Gets the mount for the @volume. * Gets the mount for the @volume.
* *
* Returns: (transfer full): a #GMount or %NULL if @volume isn't mounted. * Returns: (transfer full): a #GMount or %NULL if @volume isn't mounted.
* The returned object should be unreffed with g_object_unref() * The returned object should be unreffed with g_object_unref()
* when no longer needed. * when no longer needed.
**/ */
GMount * GMount *
g_volume_get_mount (GVolume *volume) g_volume_get_mount (GVolume *volume)
{ {
@ -258,12 +258,12 @@ g_volume_get_mount (GVolume *volume)
/** /**
* g_volume_can_mount: * g_volume_can_mount:
* @volume: a #GVolume. * @volume: a #GVolume
* *
* Checks if a volume can be mounted. * Checks if a volume can be mounted.
* *
* Returns: %TRUE if the @volume can be mounted. %FALSE otherwise. * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise
**/ */
gboolean gboolean
g_volume_can_mount (GVolume *volume) g_volume_can_mount (GVolume *volume)
{ {
@ -281,12 +281,12 @@ g_volume_can_mount (GVolume *volume)
/** /**
* g_volume_can_eject: * g_volume_can_eject:
* @volume: a #GVolume. * @volume: a #GVolume
* *
* Checks if a volume can be ejected. * Checks if a volume can be ejected.
* *
* Returns: %TRUE if the @volume can be ejected. %FALSE otherwise. * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise
**/ */
gboolean gboolean
g_volume_can_eject (GVolume *volume) g_volume_can_eject (GVolume *volume)
{ {
@ -308,7 +308,7 @@ g_volume_can_eject (GVolume *volume)
* *
* Returns whether the volume should be automatically mounted. * Returns whether the volume should be automatically mounted.
* *
* Returns: %TRUE if the volume should be automatically mounted. * Returns: %TRUE if the volume should be automatically mounted
*/ */
gboolean gboolean
g_volume_should_automount (GVolume *volume) g_volume_should_automount (GVolume *volume)
@ -328,11 +328,11 @@ g_volume_should_automount (GVolume *volume)
/** /**
* g_volume_mount: * g_volume_mount:
* @volume: a #GVolume. * @volume: a #GVolume
* @flags: flags affecting the operation * @flags: flags affecting the operation
* @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
* @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
* @user_data: user data that gets passed to @callback * @user_data: user data that gets passed to @callback
* *
* Mounts a volume. This is an asynchronous operation, and is * Mounts a volume. This is an asynchronous operation, and is
@ -340,7 +340,7 @@ g_volume_should_automount (GVolume *volume)
* and #GAsyncResult returned in the @callback. * and #GAsyncResult returned in the @callback.
* *
* Virtual: mount_fn * Virtual: mount_fn
**/ */
void void
g_volume_mount (GVolume *volume, g_volume_mount (GVolume *volume,
GMountMountFlags flags, GMountMountFlags flags,
@ -381,8 +381,8 @@ g_volume_mount (GVolume *volume,
* function; there's no need to listen for the 'mount-added' signal on * function; there's no need to listen for the 'mount-added' signal on
* #GVolumeMonitor. * #GVolumeMonitor.
* *
* Returns: %TRUE, %FALSE if operation failed. * Returns: %TRUE, %FALSE if operation failed
**/ */
gboolean gboolean
g_volume_mount_finish (GVolume *volume, g_volume_mount_finish (GVolume *volume,
GAsyncResult *result, GAsyncResult *result,
@ -404,10 +404,10 @@ g_volume_mount_finish (GVolume *volume,
/** /**
* g_volume_eject: * g_volume_eject:
* @volume: a #GVolume. * @volume: a #GVolume
* @flags: flags affecting the unmount if required for eject * @flags: flags affecting the unmount if required for eject
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
* @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
* @user_data: user data that gets passed to @callback * @user_data: user data that gets passed to @callback
* *
* Ejects a volume. This is an asynchronous operation, and is * Ejects a volume. This is an asynchronous operation, and is
@ -415,7 +415,7 @@ g_volume_mount_finish (GVolume *volume,
* and #GAsyncResult returned in the @callback. * and #GAsyncResult returned in the @callback.
* *
* Deprecated: 2.22: Use g_volume_eject_with_operation() instead. * Deprecated: 2.22: Use g_volume_eject_with_operation() instead.
**/ */
void void
g_volume_eject (GVolume *volume, g_volume_eject (GVolume *volume,
GMountUnmountFlags flags, GMountUnmountFlags flags,
@ -443,14 +443,14 @@ g_volume_eject (GVolume *volume,
/** /**
* g_volume_eject_finish: * g_volume_eject_finish:
* @volume: pointer to a #GVolume. * @volume: pointer to a #GVolume
* @result: a #GAsyncResult. * @result: a #GAsyncResult
* @error: a #GError location to store an error, or %NULL to ignore * @error: a #GError location to store an error, or %NULL to ignore
* *
* Finishes ejecting a volume. If any errors occurred during the operation, * Finishes ejecting a volume. If any errors occurred during the operation,
* @error will be set to contain the errors and %FALSE will be returned. * @error will be set to contain the errors and %FALSE will be returned.
* *
* Returns: %TRUE, %FALSE if operation failed. * Returns: %TRUE, %FALSE if operation failed
* *
* Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead. * Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead.
**/ **/
@ -475,13 +475,13 @@ g_volume_eject_finish (GVolume *volume,
/** /**
* g_volume_eject_with_operation: * g_volume_eject_with_operation:
* @volume: a #GVolume. * @volume: a #GVolume
* @flags: flags affecting the unmount if required for eject * @flags: flags affecting the unmount if required for eject
* @mount_operation: (allow-none): a #GMountOperation or %NULL to * @mount_operation: (allow-none): a #GMountOperation or %NULL to
* avoid user interaction. * avoid user interaction
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
* @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
* @user_data: user data passed to @callback. * @user_data: user data passed to @callback
* *
* Ejects a volume. This is an asynchronous operation, and is * Ejects a volume. This is an asynchronous operation, and is
* finished by calling g_volume_eject_with_operation_finish() with the @volume * finished by calling g_volume_eject_with_operation_finish() with the @volume
@ -523,15 +523,14 @@ g_volume_eject_with_operation (GVolume *volume,
/** /**
* g_volume_eject_with_operation_finish: * g_volume_eject_with_operation_finish:
* @volume: a #GVolume. * @volume: a #GVolume
* @result: a #GAsyncResult. * @result: a #GAsyncResult
* @error: a #GError location to store the error occurring, or %NULL to * @error: a #GError location to store the error occurring, or %NULL
* ignore.
* *
* Finishes ejecting a volume. If any errors occurred during the operation, * Finishes ejecting a volume. If any errors occurred during the operation,
* @error will be set to contain the errors and %FALSE will be returned. * @error will be set to contain the errors and %FALSE will be returned.
* *
* Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise. * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise
* *
* Since: 2.22 * Since: 2.22
**/ **/
@ -567,8 +566,8 @@ g_volume_eject_with_operation_finish (GVolume *volume,
* for more information about volume identifiers. * for more information about volume identifiers.
* *
* Returns: a newly allocated string containing the * Returns: a newly allocated string containing the
* requested identfier, or %NULL if the #GVolume * requested identfier, or %NULL if the #GVolume
* doesn't have this kind of identifier * doesn't have this kind of identifier
*/ */
char * char *
g_volume_get_identifier (GVolume *volume, g_volume_get_identifier (GVolume *volume,
@ -623,23 +622,20 @@ g_volume_enumerate_identifiers (GVolume *volume)
* either be equal or a prefix of what this function returns. In * either be equal or a prefix of what this function returns. In
* other words, in code * other words, in code
* *
* <programlisting> * |[
* GMount *mount; * GMount *mount;
* GFile *mount_root * GFile *mount_root
* GFile *volume_activation_root; * GFile *volume_activation_root;
* *
* mount = g_volume_get_mount (volume); /&ast; mounted, so never NULL &ast;/ * mount = g_volume_get_mount (volume); /&ast; mounted, so never NULL &ast;/
* mount_root = g_mount_get_root (mount); * mount_root = g_mount_get_root (mount);
* volume_activation_root = g_volume_get_activation_root(volume); /&ast; assume not NULL &ast;/ * volume_activation_root = g_volume_get_activation_root (volume); /&ast; assume not NULL &ast;/
* </programlisting> * ]|
*
* then the expression * then the expression
* * |[
* <programlisting>
* (g_file_has_prefix (volume_activation_root, mount_root) || * (g_file_has_prefix (volume_activation_root, mount_root) ||
g_file_equal (volume_activation_root, mount_root)) g_file_equal (volume_activation_root, mount_root))
* </programlisting> * ]|
*
* will always be %TRUE. * will always be %TRUE.
* *
* Activation roots are typically used in #GVolumeMonitor * Activation roots are typically used in #GVolumeMonitor
@ -647,10 +643,10 @@ g_volume_enumerate_identifiers (GVolume *volume)
* g_mount_is_shadowed() for more details. * g_mount_is_shadowed() for more details.
* *
* Returns: (transfer full): the activation root of @volume or %NULL. Use * Returns: (transfer full): the activation root of @volume or %NULL. Use
* g_object_unref() to free. * g_object_unref() to free.
* *
* Since: 2.18 * Since: 2.18
**/ */
GFile * GFile *
g_volume_get_activation_root (GVolume *volume) g_volume_get_activation_root (GVolume *volume)
{ {
@ -667,16 +663,16 @@ g_volume_get_activation_root (GVolume *volume)
/** /**
* g_volume_get_sort_key: * g_volume_get_sort_key:
* @volume: A #GVolume. * @volume: a #GVolume
* *
* Gets the sort key for @volume, if any. * Gets the sort key for @volume, if any.
* *
* Returns: Sorting key for @volume or %NULL if no such key is available. * Returns: Sorting key for @volume or %NULL if no such key is available
* *
* Since: 2.32 * Since: 2.32
*/ */
const gchar * const gchar *
g_volume_get_sort_key (GVolume *volume) g_volume_get_sort_key (GVolume *volume)
{ {
const gchar *ret = NULL; const gchar *ret = NULL;
GVolumeIface *iface; GVolumeIface *iface;

134
glib/deprecated/gthread-deprecated.c
View File

@ -401,14 +401,8 @@ g_once_init_enter_impl (volatile gsize *location)
* as well, and GStaticMutex has been deprecated. * as well, and GStaticMutex has been deprecated.
* *
* Here is a version of our give_me_next_number() example using * Here is a version of our give_me_next_number() example using
* a GStaticMutex. * a GStaticMutex:
* * |[
* <example>
* <title>
* Using <structname>GStaticMutex</structname>
* to simplify thread-safe programming
* </title>
* <programlisting>
* int * int
* give_me_next_number (void) * give_me_next_number (void)
* { * {
@ -416,14 +410,13 @@ g_once_init_enter_impl (volatile gsize *location)
* int ret_val; * int ret_val;
* static GStaticMutex mutex = G_STATIC_MUTEX_INIT; * static GStaticMutex mutex = G_STATIC_MUTEX_INIT;
* *
* g_static_mutex_lock (&amp;mutex); * g_static_mutex_lock (&mutex);
* ret_val = current_number = calc_next_number (current_number); * ret_val = current_number = calc_next_number (current_number);
* g_static_mutex_unlock (&amp;mutex); * g_static_mutex_unlock (&mutex);
* *
* return ret_val; * return ret_val;
* } * }
* </programlisting> * ]|
* </example>
* *
* Sometimes you would like to dynamically create a mutex. If you don't * Sometimes you would like to dynamically create a mutex. If you don't
* want to require prior calling to g_thread_init(), because your code * want to require prior calling to g_thread_init(), because your code
@ -438,16 +431,15 @@ g_once_init_enter_impl (volatile gsize *location)
* the following functions, as it is defined differently on different * the following functions, as it is defined differently on different
* platforms. * platforms.
* *
* All of the <function>g_static_mutex_*</function> functions apart * All of the g_static_mutex_* functions apart from
* from <function>g_static_mutex_get_mutex</function> can also be used * g_static_mutex_get_mutex() can also be used even if g_thread_init()
* even if g_thread_init() has not yet been called. Then they do * has not yet been called. Then they do nothing, apart from
* nothing, apart from <function>g_static_mutex_trylock</function>, * g_static_mutex_trylock() which does nothing but returning %TRUE.
* which does nothing but returning %TRUE.
* *
* <note><para>All of the <function>g_static_mutex_*</function> * All of the g_static_mutex_* functions are actually macros. Apart from
* functions are actually macros. Apart from taking their addresses, you * taking their addresses, you can however use them as if they were
* can however use them as if they were functions.</para></note> * functions.
**/ */
/** /**
* G_STATIC_MUTEX_INIT: * G_STATIC_MUTEX_INIT:
@ -585,8 +577,8 @@ g_static_mutex_get_mutex_impl (GStaticMutex* mutex)
* a #GStaticMutex as a member of a structure and the structure is * a #GStaticMutex as a member of a structure and the structure is
* freed, you should also free the #GStaticMutex. * freed, you should also free the #GStaticMutex.
* *
* <note><para>Calling g_static_mutex_free() on a locked mutex may * Calling g_static_mutex_free() on a locked mutex may result in
* result in undefined behaviour.</para></note> * undefined behaviour.
* *
* Deprecated: 2.32: Use g_mutex_clear() * Deprecated: 2.32: Use g_mutex_clear()
*/ */
@ -862,12 +854,10 @@ g_static_rec_mutex_free (GStaticRecMutex *mutex)
* lock can be used for protecting data that some portions of code only * lock can be used for protecting data that some portions of code only
* read from, while others also write. In such situations it is * read from, while others also write. In such situations it is
* desirable that several readers can read at once, whereas of course * desirable that several readers can read at once, whereas of course
* only one writer may write at a time. Take a look at the following * only one writer may write at a time.
* example:
* *
* <example> * Take a look at the following example:
* <title>An array with access functions</title> * |[
* <programlisting>
* GStaticRWLock rwlock = G_STATIC_RW_LOCK_INIT; * GStaticRWLock rwlock = G_STATIC_RW_LOCK_INIT;
* GPtrArray *array; * GPtrArray *array;
* *
@ -879,10 +869,10 @@ g_static_rec_mutex_free (GStaticRecMutex *mutex)
* if (!array) * if (!array)
* return NULL; * return NULL;
* *
* g_static_rw_lock_reader_lock (&amp;rwlock); * g_static_rw_lock_reader_lock (&rwlock);
* if (index &lt; array->len) * if (index < array->len)
* retval = g_ptr_array_index (array, index); * retval = g_ptr_array_index (array, index);
* g_static_rw_lock_reader_unlock (&amp;rwlock); * g_static_rw_lock_reader_unlock (&rwlock);
* *
* return retval; * return retval;
* } * }
@ -890,27 +880,25 @@ g_static_rec_mutex_free (GStaticRecMutex *mutex)
* void * void
* my_array_set (guint index, gpointer data) * my_array_set (guint index, gpointer data)
* { * {
* g_static_rw_lock_writer_lock (&amp;rwlock); * g_static_rw_lock_writer_lock (&rwlock);
* *
* if (!array) * if (!array)
* array = g_ptr_array_new (<!-- -->); * array = g_ptr_array_new ();
* *
* if (index >= array->len) * if (index >= array->len)
* g_ptr_array_set_size (array, index+1); * g_ptr_array_set_size (array, index + 1);
* g_ptr_array_index (array, index) = data; * g_ptr_array_index (array, index) = data;
* *
* g_static_rw_lock_writer_unlock (&amp;rwlock); * g_static_rw_lock_writer_unlock (&rwlock);
* } * }
* </programlisting> * ]|
* </example>
* *
* This example shows an array which can be accessed by many readers * This example shows an array which can be accessed by many readers
* (the <function>my_array_get()</function> function) simultaneously, * (the my_array_get() function) simultaneously, whereas the writers
* whereas the writers (the <function>my_array_set()</function> * (the my_array_set() function) will only be allowed once at a time
* function) will only be allowed once at a time and only if no readers * and only if no readers currently access the array. This is because
* currently access the array. This is because of the potentially * of the potentially dangerous resizing of the array. Using these
* dangerous resizing of the array. Using these functions is fully * functions is fully multi-thread safe now.
* multi-thread safe now.
* *
* Most of the time, writers should have precedence over readers. That * Most of the time, writers should have precedence over readers. That
* means, for this implementation, that as soon as a writer wants to * means, for this implementation, that as soon as a writer wants to
@ -922,20 +910,18 @@ g_static_rec_mutex_free (GStaticRecMutex *mutex)
* Even though #GStaticRWLock is not opaque, it should only be used * Even though #GStaticRWLock is not opaque, it should only be used
* with the following functions. * with the following functions.
* *
* All of the <function>g_static_rw_lock_*</function> functions can be * All of the g_static_rw_lock_* functions can be used even if
* used even if g_thread_init() has not been called. Then they do * g_thread_init() has not been called. Then they do nothing, apart
* nothing, apart from <function>g_static_rw_lock_*_trylock</function>, * from g_static_rw_lock_*_trylock, which does nothing but returning %TRUE.
* which does nothing but returning %TRUE.
* *
* <note><para>A read-write lock has a higher overhead than a mutex. For * A read-write lock has a higher overhead than a mutex. For example, both
* example, both g_static_rw_lock_reader_lock() and * g_static_rw_lock_reader_lock() and g_static_rw_lock_reader_unlock() have
* g_static_rw_lock_reader_unlock() have to lock and unlock a * to lock and unlock a #GStaticMutex, so it takes at least twice the time
* #GStaticMutex, so it takes at least twice the time to lock and unlock * to lock and unlock a #GStaticRWLock that it does to lock and unlock a
* a #GStaticRWLock that it does to lock and unlock a #GStaticMutex. So * #GStaticMutex. So only data structures that are accessed by multiple
* only data structures that are accessed by multiple readers, and which * readers, and which keep the lock for a considerable time justify a
* keep the lock for a considerable time justify a #GStaticRWLock. The * #GStaticRWLock. The above example most probably would fare better with a
* above example most probably would fare better with a * #GStaticMutex.
* #GStaticMutex.</para></note>
* *
* Deprecated: 2.32: Use a #GRWLock instead * Deprecated: 2.32: Use a #GRWLock instead
**/ **/
@ -1027,7 +1013,7 @@ g_static_rw_lock_reader_lock (GStaticRWLock* lock)
/** /**
* g_static_rw_lock_reader_trylock: * g_static_rw_lock_reader_trylock:
* @lock: a #GStaticRWLock to lock for reading. * @lock: a #GStaticRWLock to lock for reading
* *
* Tries to lock @lock for reading. If @lock is already locked for * Tries to lock @lock for reading. If @lock is already locked for
* writing by another thread or if another thread is already waiting to * writing by another thread or if another thread is already waiting to
@ -1035,7 +1021,7 @@ g_static_rw_lock_reader_lock (GStaticRWLock* lock)
* @lock for reading and returns %TRUE. This lock has to be unlocked by * @lock for reading and returns %TRUE. This lock has to be unlocked by
* g_static_rw_lock_reader_unlock(). * g_static_rw_lock_reader_unlock().
* *
* Returns: %TRUE, if @lock could be locked for reading. * Returns: %TRUE, if @lock could be locked for reading
* *
* Deprectated: 2.32: Use g_rw_lock_reader_trylock() instead * Deprectated: 2.32: Use g_rw_lock_reader_trylock() instead
*/ */
@ -1061,7 +1047,7 @@ g_static_rw_lock_reader_trylock (GStaticRWLock* lock)
/** /**
* g_static_rw_lock_reader_unlock: * g_static_rw_lock_reader_unlock:
* @lock: a #GStaticRWLock to unlock after reading. * @lock: a #GStaticRWLock to unlock after reading
* *
* Unlocks @lock. If a thread waits to lock @lock for writing and all * Unlocks @lock. If a thread waits to lock @lock for writing and all
* locks for reading have been unlocked, the waiting thread is woken up * locks for reading have been unlocked, the waiting thread is woken up
@ -1086,7 +1072,7 @@ g_static_rw_lock_reader_unlock (GStaticRWLock* lock)
/** /**
* g_static_rw_lock_writer_lock: * g_static_rw_lock_writer_lock:
* @lock: a #GStaticRWLock to lock for writing. * @lock: a #GStaticRWLock to lock for writing
* *
* Locks @lock for writing. If @lock is already locked for writing or * Locks @lock for writing. If @lock is already locked for writing or
* reading by other threads, this function will block until @lock is * reading by other threads, this function will block until @lock is
@ -1117,14 +1103,14 @@ g_static_rw_lock_writer_lock (GStaticRWLock* lock)
/** /**
* g_static_rw_lock_writer_trylock: * g_static_rw_lock_writer_trylock:
* @lock: a #GStaticRWLock to lock for writing. * @lock: a #GStaticRWLock to lock for writing
* *
* Tries to lock @lock for writing. If @lock is already locked (for * Tries to lock @lock for writing. If @lock is already locked (for
* either reading or writing) by another thread, it immediately returns * either reading or writing) by another thread, it immediately returns
* %FALSE. Otherwise it locks @lock for writing and returns %TRUE. This * %FALSE. Otherwise it locks @lock for writing and returns %TRUE. This
* lock has to be unlocked by g_static_rw_lock_writer_unlock(). * lock has to be unlocked by g_static_rw_lock_writer_unlock().
* *
* Returns: %TRUE, if @lock could be locked for writing. * Returns: %TRUE, if @lock could be locked for writing
* *
* Deprectated: 2.32: Use g_rw_lock_writer_trylock() instead * Deprectated: 2.32: Use g_rw_lock_writer_trylock() instead
*/ */
@ -1265,32 +1251,28 @@ GPrivate static_private_private = G_PRIVATE_INIT (g_static_private_cleanup);
* A #GStaticPrivate works almost like a #GPrivate, but it has one * A #GStaticPrivate works almost like a #GPrivate, but it has one
* significant advantage. It doesn't need to be created at run-time * significant advantage. It doesn't need to be created at run-time
* like a #GPrivate, but can be defined at compile-time. This is * like a #GPrivate, but can be defined at compile-time. This is
* similar to the difference between #GMutex and #GStaticMutex. Now * similar to the difference between #GMutex and #GStaticMutex.
* look at our <function>give_me_next_number()</function> example with
* #GStaticPrivate:
* *
* <example> * Now look at our give_me_next_number() example with #GStaticPrivate:
* <title>Using GStaticPrivate for per-thread data</title> * |[
* <programlisting>
* int * int
* give_me_next_number (<!-- -->) * give_me_next_number ()
* { * {
* static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT; * static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT;
* int *current_number = g_static_private_get (&amp;current_number_key); * int *current_number = g_static_private_get (&current_number_key);
* *
* if (!current_number) * if (!current_number)
* { * {
* current_number = g_new (int,1); * current_number = g_new (int, 1);
* *current_number = 0; * *current_number = 0;
* g_static_private_set (&amp;current_number_key, current_number, g_free); * g_static_private_set (&current_number_key, current_number, g_free);
* } * }
* *
* *current_number = calc_next_number (*current_number); * *current_number = calc_next_number (*current_number);
* *
* return *current_number; * return *current_number;
* } * }
* </programlisting> * ]|
* </example>
*/ */
/** /**
@ -1377,8 +1359,7 @@ g_static_private_get (GStaticPrivate *private_key)
* will be inherited only by the main thread, i.e. the one that called * will be inherited only by the main thread, i.e. the one that called
* g_thread_init(). * g_thread_init().
* *
* <note><para>@notify is used quite differently from @destructor in * @notify is used quite differently from @destructor in g_private_new().
* g_private_new().</para></note>
*/ */
void void
g_static_private_set (GStaticPrivate *private_key, g_static_private_set (GStaticPrivate *private_key,
@ -1561,6 +1542,7 @@ g_cond_free (GCond *cond)
* and g_time_val_add() can be used. * and g_time_val_add() can be used.
* *
* Returns: %TRUE if @cond was signalled, or %FALSE on timeout * Returns: %TRUE if @cond was signalled, or %FALSE on timeout
*
* Deprecated:2.32: Use g_cond_wait_until() instead. * Deprecated:2.32: Use g_cond_wait_until() instead.
*/ */
gboolean gboolean

54
glib/garray.c
View File

@ -67,13 +67,13 @@
* *
* To free an array, use g_array_free(). * To free an array, use g_array_free().
* *
* <example> * Here is an example that stores integers in a #GArray:
* <title>Using a #GArray to store #gint values</title> * |[
* <programlisting>
* GArray *garray; * GArray *garray;
* gint i; * gint i;
* /<!-- -->* We create a new array to store gint values. * /&ast; We create a new array to store gint values.
* We don't want it zero-terminated or cleared to 0's. *<!-- -->/ * &ast; We don't want it zero-terminated or cleared to 0's.
* &ast;/
* garray = g_array_new (FALSE, FALSE, sizeof (gint)); * garray = g_array_new (FALSE, FALSE, sizeof (gint));
* for (i = 0; i &lt; 10000; i++) * for (i = 0; i &lt; 10000; i++)
* g_array_append_val (garray, i); * g_array_append_val (garray, i);
@ -82,8 +82,7 @@
* g_print ("ERROR: got &percnt;d instead of &percnt;d\n", * g_print ("ERROR: got &percnt;d instead of &percnt;d\n",
* g_array_index (garray, gint, i), i); * g_array_index (garray, gint, i), i);
* g_array_free (garray, TRUE); * g_array_free (garray, TRUE);
* </programlisting> * ]|
* </example>
*/ */
#define MIN_ARRAY_SIZE 16 #define MIN_ARRAY_SIZE 16
@ -120,15 +119,14 @@ struct _GRealArray
* Returns the element of a #GArray at the given index. The return * Returns the element of a #GArray at the given index. The return
* value is cast to the given type. * value is cast to the given type.
* *
* <example> * This example gets a pointer to an element in a #GArray:
* <title>Getting a pointer to an element in a #GArray</title> * |[
* <programlisting>
* EDayViewEvent *event; * EDayViewEvent *event;
* /<!-- -->* This gets a pointer to the 4th element * /&ast; This gets a pointer to the 4th element
* in the array of EDayViewEvent structs. *<!-- -->/ * &ast; in the array of EDayViewEvent structs.
* &ast;/
* event = &amp;g_array_index (events, EDayViewEvent, 3); * event = &amp;g_array_index (events, EDayViewEvent, 3);
* </programlisting> * ]|
* </example>
* *
* Returns: the element of the #GArray at the index given by @i * Returns: the element of the #GArray at the index given by @i
*/ */
@ -817,25 +815,23 @@ g_array_maybe_expand (GRealArray *array,
* *
* To free a pointer array, use g_ptr_array_free(). * To free a pointer array, use g_ptr_array_free().
* *
* <example> * An example using a #GPtrArray:
* <title>Using a #GPtrArray</title> * |[
* <programlisting>
* GPtrArray *gparray; * GPtrArray *gparray;
* gchar *string1 = "one", *string2 = "two", *string3 = "three"; * gchar *string1 = "one", *string2 = "two", *string3 = "three";
* *
* gparray = g_ptr_array_new (<!-- -->); * gparray = g_ptr_array_new ();
* g_ptr_array_add (gparray, (gpointer) string1); * g_ptr_array_add (gparray, (gpointer) string1);
* g_ptr_array_add (gparray, (gpointer) string2); * g_ptr_array_add (gparray, (gpointer) string2);
* g_ptr_array_add (gparray, (gpointer) string3); * g_ptr_array_add (gparray, (gpointer) string3);
* *
* if (g_ptr_array_index (gparray, 0) != (gpointer) string1) * if (g_ptr_array_index (gparray, 0) != (gpointer) string1)
* g_print ("ERROR: got &percnt;p instead of &percnt;p\n", * g_print ("ERROR: got %p instead of %p\n",
* g_ptr_array_index (gparray, 0), string1); * g_ptr_array_index (gparray, 0), string1);
* *
* g_ptr_array_free (gparray, TRUE); * g_ptr_array_free (gparray, TRUE);
* </programlisting> * ]|
* </example> */
**/
typedef struct _GRealPtrArray GRealPtrArray; typedef struct _GRealPtrArray GRealPtrArray;
@ -1517,17 +1513,16 @@ g_ptr_array_foreach (GPtrArray *array,
* *
* To free a #GByteArray, use g_byte_array_free(). * To free a #GByteArray, use g_byte_array_free().
* *
* <example> * An example for using a #GByteArray:
* <title>Using a #GByteArray</title> * |[
* <programlisting>
* GByteArray *gbarray; * GByteArray *gbarray;
* gint i; * gint i;
* *
* gbarray = g_byte_array_new (<!-- -->); * gbarray = g_byte_array_new ();
* for (i = 0; i &lt; 10000; i++) * for (i = 0; i < 10000; i++)
* g_byte_array_append (gbarray, (guint8*) "abcd", 4); * g_byte_array_append (gbarray, (guint8*) "abcd", 4);
* *
* for (i = 0; i &lt; 10000; i++) * for (i = 0; i < 10000; i++)
* { * {
* g_assert (gbarray->data[4*i] == 'a'); * g_assert (gbarray->data[4*i] == 'a');
* g_assert (gbarray->data[4*i+1] == 'b'); * g_assert (gbarray->data[4*i+1] == 'b');
@ -1536,8 +1531,7 @@ g_ptr_array_foreach (GPtrArray *array,
* } * }
* *
* g_byte_array_free (gbarray, TRUE); * g_byte_array_free (gbarray, TRUE);
* </programlisting> * ]|
* </example>
* *
* See #GBytes if you are interested in an immutable object representing a * See #GBytes if you are interested in an immutable object representing a
* sequence of bytes. * sequence of bytes.

2
glib/gconvert.c
View File

@ -72,7 +72,7 @@
* <refsect2 id="file-name-encodings"> * <refsect2 id="file-name-encodings">
* <title>File Name Encodings</title> * <title>File Name Encodings</title>
* <para> * <para>
* Historically, Unix has not had a defined encoding for file * Historically, UNIX has not had a defined encoding for file
* names: a file name is valid as long as it does not have path * names: a file name is valid as long as it does not have path
* separators in it ("/"). However, displaying file names may * separators in it ("/"). However, displaying file names may
* require conversion: from the character set in which they were * require conversion: from the character set in which they were

26
glib/gmessages.c
View File

@ -535,30 +535,24 @@ g_log_set_fatal_mask (const gchar *log_domain,
* you want to set a handler for this log level you must combine it with * you want to set a handler for this log level you must combine it with
* #G_LOG_FLAG_FATAL. * #G_LOG_FLAG_FATAL.
* *
* <example> * Here is an example for adding a log handler for all warning messages
* <title>Adding a log handler for all warning messages in the default * in the default domain:
* (application) domain</title> * |[
* <programlisting>
* g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL * g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
* | G_LOG_FLAG_RECURSION, my_log_handler, NULL); * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
* </programlisting> * ]|
* </example>
* *
* <example> * This example adds a log handler for all critical messages from GTK+:
* <title>Adding a log handler for all critical messages from GTK+</title> * |[
* <programlisting>
* g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL * g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
* | G_LOG_FLAG_RECURSION, my_log_handler, NULL); * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
* </programlisting> * ]|
* </example>
* *
* <example> * This example adds a log handler for all messages from GLib:
* <title>Adding a log handler for all messages from GLib</title> * |[
* <programlisting>
* g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL * g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
* | G_LOG_FLAG_RECURSION, my_log_handler, NULL); * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
* </programlisting> * ]|
* </example>
* *
* Returns: the id of the new handler * Returns: the id of the new handler
*/ */

5
glib/goption.c
View File

@ -91,8 +91,7 @@
* *
* Here is a complete example of setting up GOption to parse the example * Here is a complete example of setting up GOption to parse the example
* commandline above and produce the example help output. * commandline above and produce the example help output.
* * |[
* <informalexample><programlisting>
* static gint repeats = 2; * static gint repeats = 2;
* static gint max_size = 8; * static gint max_size = 8;
* static gboolean verbose = FALSE; * static gboolean verbose = FALSE;
@ -127,7 +126,7 @@
* /&ast; ... &ast;/ * /&ast; ... &ast;/
* *
* } * }
* </programlisting></informalexample> * ]|
* *
* On UNIX systems, the argv that is passed to main() has no particular * 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 * encoding, even to the extent that different parts of it may have

25
glib/gslice.c
View File

@ -89,32 +89,29 @@
* friends, as long as objects are not resized during their lifetime and the * friends, as long as objects are not resized during their lifetime and the
* object size used at allocation time is still available when freeing. * object size used at allocation time is still available when freeing.
* *
* <example> * Here is an example for using the slice allocator:
* <title>Using the slice allocator</title> * |[
* <programlisting>
* gchar *mem[10000]; * gchar *mem[10000];
* gint i; * gint i;
* *
* /&ast; Allocate 10000 blocks. &ast;/ * /&ast; Allocate 10000 blocks. &ast;/
* for (i = 0; i &lt; 10000; i++) * for (i = 0; i < 10000; i++)
* { * {
* mem[i] = g_slice_alloc (50); * mem[i] = g_slice_alloc (50);
* *
* /&ast; Fill in the memory with some junk. &ast;/ * /&ast; Fill in the memory with some junk. &ast;/
* for (j = 0; j &lt; 50; j++) * for (j = 0; j < 50; j++)
* mem[i][j] = i * j; * mem[i][j] = i * j;
* } * }
* *
* /&ast; Now free all of the blocks. &ast;/ * /&ast; Now free all of the blocks. &ast;/
* for (i = 0; i &lt; 10000; i++) * for (i = 0; i < 10000; i++)
* { * g_slice_free1 (50, mem[i]);
* g_slice_free1 (50, mem[i]); * ]|
* }
* </programlisting></example>
* *
* <example> * And here is an example for using the using the slice allocator
* <title>Using the slice allocator with data structures</title> * with data structures:
* <programlisting> * |[
* GRealArray *array; * GRealArray *array;
* *
* /&ast; Allocate one block, using the g_slice_new() macro. &ast;/ * /&ast; Allocate one block, using the g_slice_new() macro. &ast;/
@ -130,7 +127,7 @@
* *
* /&ast; We can free the block, so it can be reused. &ast;/ * /&ast; We can free the block, so it can be reused. &ast;/
* g_slice_free (GRealArray, array); * g_slice_free (GRealArray, array);
* </programlisting></example> * ]|
*/ */
/* the GSlice allocator is split up into 4 layers, roughly modelled after the slab /* the GSlice allocator is split up into 4 layers, roughly modelled after the slab

10
glib/gthread-posix.c
View File

@ -804,7 +804,7 @@ g_cond_broadcast (GCond *cond)
* passed. * passed.
* *
* The following code shows how to correctly perform a timed wait on a * 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): * documentation for #GCond):
* *
* |[ * |[
@ -820,12 +820,12 @@ g_cond_broadcast (GCond *cond)
* while (!current_data) * while (!current_data)
* if (!g_cond_wait_until (&data_cond, &data_mutex, end_time)) * if (!g_cond_wait_until (&data_cond, &data_mutex, end_time))
* { * {
* // timeout has passed. * /&ast; timeout has passed. &ast;/
* g_mutex_unlock (&data_mutex); * g_mutex_unlock (&data_mutex);
* return NULL; * return NULL;
* } * }
* *
* // there is data for us * /&ast; there is data for us &ast;/
* data = current_data; * data = current_data;
* current_data = NULL; * current_data = NULL;
* *
@ -920,7 +920,7 @@ g_cond_wait_until (GCond *cond,
* |[ * |[
* static GPrivate name_key = G_PRIVATE_INIT (g_free); * static GPrivate name_key = G_PRIVATE_INIT (g_free);
* *
* // return value should not be freed * /&ast; return value should not be freed &ast;/
* const gchar * * const gchar *
* get_local_name (void) * get_local_name (void)
* { * {
@ -934,7 +934,7 @@ g_cond_wait_until (GCond *cond,
* } * }
* *
* *
* static GPrivate count_key; // no free function * static GPrivate count_key; /&ast; no free function &ast;/
* *
* gint * gint
* get_local_count (void) * get_local_count (void)

102
glib/gthread.c
View File

@ -162,12 +162,10 @@
* mangled to get the name of the #GMutex. This means that you * 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 * 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 * of the variable you intend to protect with the lock. Look at our
* <function>give_me_next_number()</function> example using the * give_me_next_number() example using the #G_LOCK macros:
* <literal>G_LOCK_*</literal> macros:
* *
* <example> * Here is an example for using the #G_LOCK convenience macros:
* <title>Using the <literal>G_LOCK_*</literal> convenience macros</title> * |[
* <programlisting>
* G_LOCK_DEFINE (current_number); * G_LOCK_DEFINE (current_number);
* *
* int * int
@ -182,8 +180,7 @@
* *
* return ret_val; * return ret_val;
* } * }
* </programlisting> * ]|
* </example>
*/ */
/** /**
@ -234,33 +231,27 @@
* *
* The #GMutex struct is an opaque data structure to represent a mutex * The #GMutex struct is an opaque data structure to represent a mutex
* (mutual exclusion). It can be used to protect data against shared * (mutual exclusion). It can be used to protect data against shared
* access. Take for example the following function: * access.
* *
* <example> * Take for example the following function:
* <title>A function which will not work in a threaded environment</title> * |[
* <programlisting>
* int * int
* give_me_next_number (void) * give_me_next_number (void)
* { * {
* static int current_number = 0; * static int current_number = 0;
* *
* /<!-- -->* now do a very complicated calculation to calculate the new * /&ast; now do a very complicated calculation to calculate the new
* * number, this might for example be a random number generator * &ast; number, this might for example be a random number generator
* *<!-- -->/ * &ast;/
* current_number = calc_next_number (current_number); * current_number = calc_next_number (current_number);
* *
* return current_number; * return current_number;
* } * }
* </programlisting> * ]|
* </example>
*
* It is easy to see that this won't work in a multi-threaded * It is easy to see that this won't work in a multi-threaded
* application. There current_number must be protected against shared * application. There current_number must be protected against shared
* access. A #GMutex can be used as a solution to this problem: * access. A #GMutex can be used as a solution to this problem:
* * |[
* <example>
* <title>Using GMutex to protected a shared variable</title>
* <programlisting>
* int * int
* give_me_next_number (void) * give_me_next_number (void)
* { * {
@ -274,9 +265,7 @@
* *
* return ret_val; * return ret_val;
* } * }
* </programlisting> * ]|
* </example>
*
* Notice that the #GMutex is not initialised to any particular value. * Notice that the #GMutex is not initialised to any particular value.
* Its placement in static storage ensures that it will be initialised * Its placement in static storage ensures that it will be initialised
* to all-zeros, which is appropriate. * to all-zeros, which is appropriate.
@ -325,9 +314,8 @@
* simultaneous read-only access (by holding the 'reader' lock via * simultaneous read-only access (by holding the 'reader' lock via
* g_rw_lock_reader_lock()). * g_rw_lock_reader_lock()).
* *
* <example> * Here is an example for an array with access functions:
* <title>An array with access functions</title> * |[
* <programlisting>
* GRWLock lock; * GRWLock lock;
* GPtrArray *array; * GPtrArray *array;
* *
@ -340,7 +328,7 @@
* return NULL; * return NULL;
* *
* g_rw_lock_reader_lock (&amp;lock); * g_rw_lock_reader_lock (&amp;lock);
* if (index &lt; array->len) * if (index < array->len)
* retval = g_ptr_array_index (array, index); * retval = g_ptr_array_index (array, index);
* g_rw_lock_reader_unlock (&amp;lock); * g_rw_lock_reader_unlock (&amp;lock);
* *
@ -350,35 +338,30 @@
* void * void
* my_array_set (guint index, gpointer data) * my_array_set (guint index, gpointer data)
* { * {
* g_rw_lock_writer_lock (&amp;lock); * g_rw_lock_writer_lock (&lock);
* *
* if (!array) * if (!array)
* array = g_ptr_array_new (<!-- -->); * array = g_ptr_array_new ();
* *
* if (index >= array->len) * if (index >= array->len)
* g_ptr_array_set_size (array, index+1); * g_ptr_array_set_size (array, index+1);
* g_ptr_array_index (array, index) = data; * g_ptr_array_index (array, index) = data;
* *
* g_rw_lock_writer_unlock (&amp;lock); * g_rw_lock_writer_unlock (&lock);
* } * }
* </programlisting> * ]|
* <para> * This example shows an array which can be accessed by many readers
* This example shows an array which can be accessed by many readers * (the my_array_get() function) simultaneously, whereas the writers
* (the <function>my_array_get()</function> function) simultaneously, * (the my_array_set() function) will only be allowed one at a time
* whereas the writers (the <function>my_array_set()</function> * and only if no readers currently access the array. This is because
* function) will only be allowed once at a time and only if no readers * of the potentially dangerous resizing of the array. Using these
* currently access the array. This is because of the potentially * functions is fully multi-thread safe now.
* dangerous resizing of the array. Using these functions is fully
* multi-thread safe now.
* </para>
* </example>
* *
* If a #GRWLock is allocated in static storage then it can be used * If a #GRWLock is allocated in static storage then it can be used
* without initialisation. Otherwise, you should call * without initialisation. Otherwise, you should call
* g_rw_lock_init() on it and g_rw_lock_clear() when done. * g_rw_lock_init() on it and g_rw_lock_clear() when done.
* *
* A GRWLock should only be accessed with the * A GRWLock should only be accessed with the g_rw_lock_ functions.
* <function>g_rw_lock_</function> functions.
* *
* Since: 2.32 * Since: 2.32
*/ */
@ -399,11 +382,9 @@
* another thread publishes the data, it can signal one of the waiting * another thread publishes the data, it can signal one of the waiting
* threads to wake up to collect the data. * threads to wake up to collect the data.
* *
* <example> * Here is an example for using GCond to block a thread until a condition
* <title> * is satisfied:
* Using GCond to block a thread until a condition is satisfied * |[
* </title>
* <programlisting>
* gpointer current_data = NULL; * gpointer current_data = NULL;
* GMutex data_mutex; * GMutex data_mutex;
* GCond data_cond; * GCond data_cond;
@ -431,21 +412,19 @@
* *
* return data; * return data;
* } * }
* </programlisting> * ]|
* </example>
*
* Whenever a thread calls pop_data() now, it will wait until * Whenever a thread calls pop_data() now, it will wait until
* current_data is non-%NULL, i.e. until some other thread * current_data is non-%NULL, i.e. until some other thread
* has called push_data(). * has called push_data().
* *
* The example shows that use of a condition variable must always be * 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 * 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 * race between the check of @current_data by the while loop in
* while loop in <function>pop_data</function> and waiting. * pop_data() and waiting. Specifically, another thread could set
* Specifically, another thread could set <varname>pop_data</varname> * @current_data after the check, and signal the cond (with nobody
* after the check, and signal the cond (with nobody waiting on it) * waiting on it) before the first thread goes to sleep. #GCond is
* before the first thread goes to sleep. #GCond is specifically useful * specifically useful for its ability to release the mutex and go
* for its ability to release the mutex and go to sleep atomically. * to sleep atomically.
* *
* It is also important to use the g_cond_wait() and g_cond_wait_until() * 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 * functions only inside a loop which checks for the condition to be
@ -453,11 +432,10 @@
* not be true even after it returns. * not be true even after it returns.
* *
* If a #GCond is allocated in static storage then it can be used * If a #GCond is allocated in static storage then it can be used
* without initialisation. Otherwise, you should call g_cond_init() on * without initialisation. Otherwise, you should call g_cond_init()
* it and g_cond_clear() when done. * on it and g_cond_clear() when done.
* *
* A #GCond should only be accessed via the <function>g_cond_</function> * A #GCond should only be accessed via the g_cond_ functions.
* functions.
*/ */
/* GThread Documentation {{{1 ---------------------------------------- */ /* GThread Documentation {{{1 ---------------------------------------- */

4
glib/gurifuncs.c
View File

@ -165,9 +165,9 @@ g_uri_unescape_string (const char *escaped_string,
* @uri: a valid URI. * @uri: a valid URI.
* *
* Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as: * Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as:
* <programlisting> * |[
* URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
* </programlisting> * ]|
* Common schemes include "file", "http", "svn+ssh", etc. * Common schemes include "file", "http", "svn+ssh", etc.
* *
* Returns: The "Scheme" component of the URI, or %NULL on error. * Returns: The "Scheme" component of the URI, or %NULL on error.

5
glib/gvariant-parser.c
View File

@ -2480,10 +2480,9 @@ g_variant_new_parsed_va (const gchar *format,
* g_variant_new() would have collected. * g_variant_new() would have collected.
* *
* Consider this simple example: * Consider this simple example:
* * |[
* <informalexample><programlisting>
* g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three"); * g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three");
* </programlisting></informalexample> * ]|
* *
* In the example, the variable argument parameters are collected and * In the example, the variable argument parameters are collected and
* filled in as if they were part of the original string to produce the * filled in as if they were part of the original string to produce the

67
glib/gvariant.c
View File

@ -1103,8 +1103,8 @@ g_variant_lookup_value (GVariant *dictionary,
* Memory</link>. * Memory</link>.
* *
* In particular, arrays of these fixed-sized types can be interpreted * In particular, arrays of these fixed-sized types can be interpreted
* as an array of the given C type, with @element_size set to * as an array of the given C type, with @element_size set to the size
* <code>sizeof</code> the appropriate type: * the appropriate type:
* *
* <informaltable> * <informaltable>
* <tgroup cols='2'> * <tgroup cols='2'>
@ -1121,16 +1121,16 @@ g_variant_lookup_value (GVariant *dictionary,
* </tgroup> * </tgroup>
* </informaltable> * </informaltable>
* *
* For example, if calling this function for an array of 32 bit integers, * 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 * you might say sizeof(gint32). This value isn't used except for the purpose
* except for the purpose of a double-check that the form of the * of a double-check that the form of the serialised data matches the caller's
* serialised data matches the caller's expectation. * expectation.
* *
* @n_elements, which must be non-%NULL is set equal to the number of * @n_elements, which must be non-%NULL is set equal to the number of
* items in the array. * items in the array.
* *
* Returns: (array length=n_elements) (transfer none): a pointer to * Returns: (array length=n_elements) (transfer none): a pointer to
* the fixed array * the fixed array
* *
* Since: 2.24 * Since: 2.24
**/ **/
@ -3070,10 +3070,9 @@ g_variant_iter_free (GVariantIter *iter)
* Use g_variant_unref() to drop your reference on the return value when * Use g_variant_unref() to drop your reference on the return value when
* you no longer need it. * you no longer need it.
* *
* <example> * Here is an example for iterating with g_variant_iter_next_value():
* <title>Iterating with g_variant_iter_next_value()</title> * |[
* <programlisting> * /&ast; recursively iterate a container &ast;/
* /<!-- -->* recursively iterate a container *<!-- -->/
* void * void
* iterate_container_recursive (GVariant *container) * iterate_container_recursive (GVariant *container)
* { * {
@ -3091,8 +3090,7 @@ g_variant_iter_free (GVariantIter *iter)
* g_variant_unref (child); * g_variant_unref (child);
* } * }
* } * }
* </programlisting> * ]|
* </example>
* *
* Returns: (allow-none) (transfer full): a #GVariant, or %NULL * Returns: (allow-none) (transfer full): a #GVariant, or %NULL
* *
@ -4985,13 +4983,9 @@ g_variant_get_child (GVariant *value,
* responsibility of the caller to free all of the values returned by * responsibility of the caller to free all of the values returned by
* the unpacking process. * the unpacking process.
* *
* See the section on <link linkend='gvariant-format-strings'>GVariant * Here is an example for memory management with g_variant_iter_next():
* Format Strings</link>. * |[
* * /&ast; Iterates a dictionary of type 'a{sv}' &ast;/
* <example>
* <title>Memory management with g_variant_iter_next()</title>
* <programlisting>
* /<!-- -->* Iterates a dictionary of type 'a{sv}' *<!-- -->/
* void * void
* iterate_dictionary (GVariant *dictionary) * iterate_dictionary (GVariant *dictionary)
* { * {
@ -5005,20 +4999,20 @@ g_variant_get_child (GVariant *value,
* g_print ("Item '%s' has type '%s'\n", key, * g_print ("Item '%s' has type '%s'\n", key,
* g_variant_get_type_string (value)); * g_variant_get_type_string (value));
* *
* /<!-- -->* must free data for ourselves *<!-- -->/ * /&ast; must free data for ourselves &ast;/
* g_variant_unref (value); * g_variant_unref (value);
* g_free (key); * g_free (key);
* } * }
* } * }
* </programlisting> * ]|
* </example>
* *
* For a solution that is likely to be more convenient to C programmers * For a solution that is likely to be more convenient to C programmers
* when dealing with loops, see g_variant_iter_loop(). * when dealing with loops, see g_variant_iter_loop().
* *
* @format_string determines the C types that are used for unpacking * @format_string determines the C types that are used for unpacking
* the values and also determines if the values are copied or borrowed, * the values and also determines if the values are copied or borrowed.
* see the section on *
* See the section on
* <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>. * <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
* *
* Returns: %TRUE if a value was unpacked, or %FALSE if there as no value * Returns: %TRUE if a value was unpacked, or %FALSE if there as no value
@ -5081,13 +5075,9 @@ g_variant_iter_next (GVariantIter *iter,
* you must free or unreference all the unpacked values as you would with * 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. * g_variant_get(). Failure to do so will cause a memory leak.
* *
* See the section on <link linkend='gvariant-format-strings'>GVariant * Here is an example for memory management with g_variant_iter_loop():
* Format Strings</link>. * |[
* * /&ast; Iterates a dictionary of type 'a{sv}' &ast;/
* <example>
* <title>Memory management with g_variant_iter_loop()</title>
* <programlisting>
* /<!-- -->* Iterates a dictionary of type 'a{sv}' *<!-- -->/
* void * void
* iterate_dictionary (GVariant *dictionary) * iterate_dictionary (GVariant *dictionary)
* { * {
@ -5101,12 +5091,12 @@ g_variant_iter_next (GVariantIter *iter,
* g_print ("Item '%s' has type '%s'\n", key, * g_print ("Item '%s' has type '%s'\n", key,
* g_variant_get_type_string (value)); * g_variant_get_type_string (value));
* *
* /<!-- -->* no need to free 'key' and 'value' here *<!-- -->/ * /&ast; no need to free 'key' and 'value' here
* /<!-- -->* unless breaking out of this loop *<!-- -->/ * &ast; unless breaking out of this loop
* &ast;/
* } * }
* } * }
* </programlisting> * ]|
* </example>
* *
* For most cases you should use g_variant_iter_next(). * For most cases you should use g_variant_iter_next().
* *
@ -5120,8 +5110,9 @@ g_variant_iter_next (GVariantIter *iter,
* thereby avoiding the need to free anything as well). * thereby avoiding the need to free anything as well).
* *
* @format_string determines the C types that are used for unpacking * @format_string determines the C types that are used for unpacking
* the values and also determines if the values are copied or borrowed, * the values and also determines if the values are copied or borrowed.
* see the section on *
* See the section on
* <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>. * <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
* *
* Returns: %TRUE if a value was unpacked, or %FALSE if there was no * Returns: %TRUE if a value was unpacked, or %FALSE if there was no

24
glib/gversion.c
View File

@ -85,17 +85,7 @@
* @micro: the micro version to check for * @micro: the micro version to check for
* *
* Checks the version of the GLib library that is being compiled * Checks the version of the GLib library that is being compiled
* against. * against. See glib_check_version() for a runtime check.
*
* <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.
* *
* Returns: %TRUE if the version of the GLib header files * Returns: %TRUE if the version of the GLib header files
* is the same as or newer than the passed-in version. * is the same as or newer than the passed-in version.
@ -109,9 +99,9 @@ const guint glib_binary_age = GLIB_BINARY_AGE;
/** /**
* glib_check_version: * glib_check_version:
* @required_major: the required major version. * @required_major: the required major version
* @required_minor: the required minor version. * @required_minor: the required minor version
* @required_micro: the required micro version. * @required_micro: the required micro version
* *
* Checks that the GLib library in use is compatible with the * Checks that the GLib library in use is compatible with the
* given version. Generally you would pass in the constants * given version. Generally you would pass in the constants
@ -129,9 +119,9 @@ const guint glib_binary_age = GLIB_BINARY_AGE;
* (same major version.) * (same major version.)
* *
* Return value: %NULL if the GLib library is compatible with the * Return value: %NULL if the GLib library is compatible with the
* given version, or a string describing the version mismatch. * given version, or a string describing the version mismatch.
* The returned string is owned by GLib and must not be modified * The returned string is owned by GLib and must not be modified
* or freed. * or freed.
* *
* Since: 2.6 * Since: 2.6
*/ */

34
gobject/gobject.c
View File

@ -57,11 +57,11 @@
* container = create_container (); * container = create_container ();
* container_add_child (container, create_child()); * container_add_child (container, create_child());
* ]| * ]|
* If <function>container_add_child()</function> will g_object_ref_sink() the * If container_add_child() calls g_object_ref_sink() on the passed-in child,
* passed in child, no reference of the newly created child is leaked. * no reference of the newly created child is leaked. Without floating
* Without floating references, <function>container_add_child()</function> * references, container_add_child() can only g_object_ref() the new child,
* can only g_object_ref() the new child, so to implement this code without * so to implement this code without reference leaks, it would have to be
* reference leaks, it would have to be written as: * written as:
* |[ * |[
* Child *child; * Child *child;
* container = create_container (); * container = create_container ();
@ -69,11 +69,11 @@
* container_add_child (container, child); * container_add_child (container, child);
* g_object_unref (child); * g_object_unref (child);
* ]| * ]|
* The floating reference can be converted into * The floating reference can be converted into an ordinary reference by
* an ordinary reference by calling g_object_ref_sink(). * calling g_object_ref_sink(). For already sunken objects (objects that
* For already sunken objects (objects that don't have a floating reference * don't have a floating reference anymore), g_object_ref_sink() is equivalent
* anymore), g_object_ref_sink() is equivalent to g_object_ref() and returns * to g_object_ref() and returns a new reference.
* a new reference. *
* Since floating references are useful almost exclusively for C convenience, * Since floating references are useful almost exclusively for C convenience,
* language bindings that provide automated reference and memory ownership * language bindings that provide automated reference and memory ownership
* maintenance (such as smart pointers or garbage collection) should not * maintenance (such as smart pointers or garbage collection) should not
@ -2227,12 +2227,9 @@ g_object_set (gpointer _object,
* is responsible for freeing the memory in the appropriate manner for * is responsible for freeing the memory in the appropriate manner for
* the type, for instance by calling g_free() or g_object_unref(). * the type, for instance by calling g_free() or g_object_unref().
* *
* <example> * Here is an example of using g_object_get() to get the contents
* <title>Using g_object_get(<!-- -->)</title> * of three properties: an integer, a string and an object:
* An example of using g_object_get() to get the contents * |[
* of three properties - one of type #G_TYPE_INT,
* one of type #G_TYPE_STRING, and one of type #G_TYPE_OBJECT:
* <programlisting>
* gint intval; * gint intval;
* gchar *strval; * gchar *strval;
* GObject *objval; * GObject *objval;
@ -2243,12 +2240,11 @@ g_object_set (gpointer _object,
* "obj-property", &objval, * "obj-property", &objval,
* NULL); * NULL);
* *
* // Do something with intval, strval, objval * /&ast; Do something with intval, strval, objval &ast;/
* *
* g_free (strval); * g_free (strval);
* g_object_unref (objval); * g_object_unref (objval);
* </programlisting> * ]|
* </example>
*/ */
void void
g_object_get (gpointer _object, g_object_get (gpointer _object,

8
gobject/gtype.c
View File

@ -3065,12 +3065,10 @@ g_type_class_peek_static (GType type)
* It returns the class structure of the immediate parent type of the * It returns the class structure of the immediate parent type of the
* class passed in. Since derived classes hold a reference count on * class passed in. Since derived classes hold a reference count on
* their parent classes as long as they are instantiated, the returned * their parent classes as long as they are instantiated, the returned
* class will always exist. This function is essentially equivalent * class will always exist.
* to:
* *
* <programlisting> * This function is essentially equivalent to:
* g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))); * g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class)))
* </programlisting>
* *
* Returns: (type GObject.TypeClass) (transfer none): the parent class * Returns: (type GObject.TypeClass) (transfer none): the parent class
* of @g_class * of @g_class