luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-26 22:16:16 +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.
*
* <example>
* <title>Using g_action_map_add_action_entries()</title>
* <programlisting>
* |[
* static void
* activate_quit (GSimpleAction *simple,
* GVariant *parameter,
@ -193,8 +191,7 @@ g_action_map_remove_action (GActionMap *action_map,
*
* return G_ACTION_GROUP (group);
* }
* </programlisting>
* </example>
* ]|
*
* Since: 2.32
*/

22
gio/gapplication.c
View File

@ -75,17 +75,17 @@
* On Linux, the D-Bus session bus is used for communication.
*
* The use of #GApplication differs from some other commonly-used
* uniqueness libraries (such as libunique) in important ways. The
* application is not expected to manually register itself and check if
* it is the primary instance. Instead, the <code>main()</code>
* function of a #GApplication should do very little more than
* instantiating the application instance, possibly connecting signal
* handlers, then calling g_application_run(). All checks for
* uniqueness are done internally. If the application is the primary
* instance then the startup signal is emitted and the mainloop runs.
* If the application is not the primary instance then a signal is sent
* to the primary instance and g_application_run() promptly returns.
* See the code examples below.
* uniqueness libraries (such as libunique) in important ways. The
* application is not expected to manually register itself and check
* if it is the primary instance. Instead, the main() function of a
* #GApplication should do very little more than instantiating the
* application instance, possibly connecting signal handlers, then
* calling g_application_run(). All checks for uniqueness are done
* internally. If the application is the primary instance then the
* startup signal is emitted and the mainloop runs. If the application
* is not the primary instance then a signal is sent to the primary
* instance and g_application_run() promptly returns. See the code
* examples below.
*
* If used, the expected form of an application identifier is very close
* 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
* known to the system. The list and its data should be freed using
* <programlisting>
* g_list_free_full (list, g_free);
* </programlisting>
* g_list_free_full (list, g_free).
*
* 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 *
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
* is typically done in the function returning the #GQuark for the
* 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 ())
* GQuark foo_bar_error_quark (void);
@ -66,10 +66,10 @@
* FOO_BAR_ERROR_FAILED,
* FOO_BAR_ERROR_ANOTHER_ERROR,
* FOO_BAR_ERROR_SOME_THIRD_ERROR,
* FOO_BAR_N_ERRORS /<!-- -->*< skip >*<!-- -->/
* FOO_BAR_N_ERRORS /&ast;< skip >&ast;/
* } FooBarError;
*
* /<!-- -->* foo-bar-error.c: *<!-- -->/
* /&ast; foo-bar-error.c: &ast;/
*
* static const GDBusErrorEntry foo_bar_error_entries[] =
* {
@ -78,7 +78,7 @@
* {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);
*
* GQuark
@ -91,15 +91,15 @@
* G_N_ELEMENTS (foo_bar_error_entries));
* return (GQuark) quark_volatile;
* }
* </programlisting></example>
* ]|
* 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
* 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
* 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
* 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
* and formatting is subject to change at any time. Typical output
* looks something like this:
* <programlisting>
* |[
* Type&colon; method-call
* Flags&colon; none
* Version&colon; 0
@ -3362,9 +3362,9 @@ _sort_keys_func (gconstpointer a,
* Body&colon; ()
* UNIX File Descriptors:
* (none)
* </programlisting>
* ]|
* or
* <programlisting>
* |[
* Type&colon; method-return
* Flags&colon; no-reply-expected
* Version&colon; 0
@ -3377,7 +3377,7 @@ _sort_keys_func (gconstpointer a,
* Body&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
* </programlisting>
* ]|
*
* 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.
* RFC 3986 decodes the scheme as:
* <programlisting>
* |[
* URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
* </programlisting>
* ]|
* Common schemes include "file", "http", "ftp", etc.
*
* 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 menus would then be added as submenus of the third. In XML
* format, this would look something like the following:
*
* <informalexample><programlisting><![CDATA[
* |[
* <menu id='edit-menu'>
* <section>
* <item label='Undo'/>
@ -1216,7 +1215,7 @@ g_menu_item_new_submenu (const gchar *label,
* <item label='Paste'/>
* </section>
* </menu>
* ]]></programlisting></informalexample>
* ]|
*
* The following example is exactly equivalent. It is more illustrative
* 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
* difficult to read (and therefore not recommended except for the
* purpose of understanding what is really going on).
*
* <informalexample><programlisting><![CDATA[
* |[
* <menu id='edit-menu'>
* <item>
* <link name='section'>
@ -1241,7 +1239,7 @@ g_menu_item_new_submenu (const gchar *label,
* </link>
* </item>
* </menu>
* ]]></programlisting></informalexample>
* ]|
*
* 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
* are combined into a binary resource bundle.
*
* <example id="resource-example"><title>Example resource description</title>
* <programlisting><![CDATA[
* An example resource description:
* |[
* <?xml version="1.0" encoding="UTF-8"?>
* <gresources>
* <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>
* </gresource>
* </gresources>
* ]]></programlisting></example>
* ]|
*
* This will create a resource bundle with the following files:
* <programlisting><![CDATA[
* |[
* /org/gtk/Example/data/splashscreen.png
* /org/gtk/Example/dialog.ui
* /org/gtk/Example/menumarkup.xml
* ]]></programlisting>
* ]|
*
* 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.

16
gio/gsettings.c
View File

@ -118,8 +118,8 @@
* access the numeric values corresponding to the string value of enum
* and flags keys.
*
* <example id="schema-default-values"><title>Default values</title>
* <programlisting><![CDATA[
* An example for default value:
* |[
* <schemalist>
* <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test">
*
@ -137,10 +137,10 @@
*
* </schema>
* </schemalist>
* ]]></programlisting></example>
* ]|
*
* <example id="schema-enumerated"><title>Ranges, choices and enumerated types</title>
* <programlisting><![CDATA[
* An example for ranges, choices and enumerated types:
* |[
* <schemalist>
*
* <enum id="org.gtk.Test.myenum">
@ -183,7 +183,7 @@
* </key>
* </schema>
* </schemalist>
* ]]></programlisting></example>
* ]|
*
* <refsect2>
* <title>Vendor overrides</title>
@ -197,11 +197,11 @@
* 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
* are expected in serialized GVariant form, as in the following example:
* <informalexample><programlisting>
* |[
* [org.gtk.Example]
* key1='string'
* key2=1.5
* </programlisting></informalexample>
* ]|
* </para>
* <para>
* 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
* 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
* default action is taken. If the state should change then you must
* to the requested value. If you connect a signal handler then no
* default action is taken. If the state should change then you must
* call g_simple_action_set_state() from the handler.
*
* <example>
* <title>Example 'change-state' handler</title>
* <programlisting>
* An example of a 'change-state' handler:
* |[
* static void
* change_volume_state (GSimpleAction *action,
* GVariant *value,
@ -410,15 +409,14 @@ g_simple_action_class_init (GSimpleActionClass *class)
*
* 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)
* g_simple_action_set_state (action, value);
* }
* </programlisting>
* </example>
* ]|
*
* The handler need not set the state to the requested value. It
* could set it to any value at all, or take some other action.
* The handler need not set the state to the requested value.
* It could set it to any value at all, or take some other action.
*
* Since: 2.30
*/
@ -434,7 +432,7 @@ g_simple_action_class_init (GSimpleActionClass *class)
/**
* 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.
*
* 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
* the return value.
* </para>
* <example id="gtask-async"><title>GTask as a GAsyncResult</title>
* <programlisting>
* Here is an example for using GTask as a GAsyncResult:
* |[
* typedef struct {
* CakeFrostingType frosting;
* char *message;
@ -144,8 +144,7 @@
*
* return g_task_propagate_pointer (G_TASK (result), error);
* }
* </programlisting>
* </example>
* ]|
* </refsect2>
* <refsect2>
* <title>Chained asynchronous operations</title>
@ -161,8 +160,9 @@
* source to fire (automatically using the correct #GMainContext
* and priority).
* </para>
* <example id="gtask-chained"><title>Chained asynchronous operations</title>
* <programlisting>
*
* Here is an example for chained asynchronous operations:
* |[
* typedef struct {
* Cake *cake;
* CakeFrostingType frosting;
@ -287,8 +287,7 @@
*
* return g_task_propagate_pointer (G_TASK (result), error);
* }
* </programlisting>
* </example>
* ]|
* </refsect2>
* <refsect2>
* <title>Asynchronous operations from synchronous ones</title>
@ -298,8 +297,9 @@
* which will then dispatch the result back to the caller's
* #GMainContext when it completes.
* </para>
* <example id="gtask-run-in-thread"><title>g_task_run_in_thread()</title>
* <programlisting>
*
* Running a task in a thread:
* |[
* typedef struct {
* guint radius;
* CakeFlavor flavor;
@ -366,8 +366,7 @@
*
* return g_task_propagate_pointer (G_TASK (result), error);
* }
* </programlisting>
* </example>
* ]|
* </refsect2>
* <refsect2>
* <title>Adding cancellability to uncancellable tasks</title>
@ -384,8 +383,9 @@
* to make "GLib-friendly" asynchronous and cancellable
* synchronous variants of blocking APIs.
* </para>
* <example id="gtask-cancellable"><title>g_task_set_return_on_cancel()</title>
* <programlisting>
*
* Cancelling a task:
* |[
* static void
* bake_cake_thread (GTask *task,
* gpointer source_object,
@ -474,8 +474,7 @@
* g_object_unref (task);
* return cake;
* }
* </programlisting>
* </example>
* ]|
* </refsect2>
* <refsect2>
* <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>
* in the services
* directory and have it processed by configure.
* <informalexample><programlisting>
* |[
* [D-BUS Service]
* Name=org.gtk.GDBus.Examples.ObjectManager
* Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server
* </programlisting></informalexample>
* ]|
* You will also need to indicate this service directory in your test
* fixtures, so you will need to pass the path while compiling your
* test cases. Typically this is done with autotools with an added
* preprocessor flag specified to compile your tests such as:
* <informalexample><programlisting>
* |[
* -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\"
* </programlisting></informalexample>
* ]|
* </para>
* <para>
* 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.
* <example id="gdbus-test-fixture">
* <title>Test Fixture for D-Bus services</title>
* <programlisting>
* <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
* by compiling the schemas locally as a step before running test cases, an autotools setup might
* do the following in the directory holding schemas:
* <informalexample><programlisting>
* |[
* all-am:
* $(GLIB_COMPILE_SCHEMAS) .
*
* CLEANFILES += gschemas.compiled
* </programlisting></informalexample>
* ]|
* </para>
* </refsect2>
*/

124
gio/gvolume.c
View File

@ -87,7 +87,7 @@ g_volume_default_init (GVolumeInterface *iface)
* GVolume::changed:
*
* Emitted when the volume has been changed.
**/
*/
g_signal_new (I_("changed"),
G_TYPE_VOLUME,
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
* the recipient is holding references to the object they should
* release them so the object can be finalized.
**/
*/
g_signal_new (I_("removed"),
G_TYPE_VOLUME,
G_SIGNAL_RUN_LAST,
@ -114,13 +114,13 @@ g_volume_default_init (GVolumeInterface *iface)
/**
* g_volume_get_name:
* @volume: a #GVolume.
* @volume: a #GVolume
*
* Gets the name of @volume.
*
* 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 *
g_volume_get_name (GVolume *volume)
{
@ -135,14 +135,14 @@ g_volume_get_name (GVolume *volume)
/**
* g_volume_get_icon:
* @volume: a #GVolume.
* @volume: a #GVolume
*
* Gets the icon for @volume.
*
* Returns: (transfer full): a #GIcon.
* The returned object should be unreffed with g_object_unref()
* when no longer needed.
**/
*/
GIcon *
g_volume_get_icon (GVolume *volume)
{
@ -157,7 +157,7 @@ g_volume_get_icon (GVolume *volume)
/**
* g_volume_get_symbolic_icon:
* @volume: a #GVolume.
* @volume: a #GVolume
*
* Gets the symbolic icon for @volume.
*
@ -166,7 +166,7 @@ g_volume_get_icon (GVolume *volume)
* when no longer needed.
*
* Since: 2.34
**/
*/
GIcon *
g_volume_get_symbolic_icon (GVolume *volume)
{
@ -188,7 +188,7 @@ g_volume_get_symbolic_icon (GVolume *volume)
/**
* g_volume_get_uuid:
* @volume: a #GVolume.
* @volume: a #GVolume
*
* Gets the UUID for the @volume. The reference is typically based on
* 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.
* The returned string should be freed with g_free()
* when no longer needed.
**/
*/
char *
g_volume_get_uuid (GVolume *volume)
{
@ -213,14 +213,14 @@ g_volume_get_uuid (GVolume *volume)
/**
* g_volume_get_drive:
* @volume: a #GVolume.
* @volume: a #GVolume
*
* Gets the drive for the @volume.
*
* Returns: (transfer full): a #GDrive or %NULL if @volume is not associated with a drive.
* The returned object should be unreffed with g_object_unref()
* when no longer needed.
**/
* Returns: (transfer full): a #GDrive or %NULL if @volume is not
* associated with a drive. The returned object should be unreffed
* with g_object_unref() when no longer needed.
*/
GDrive *
g_volume_get_drive (GVolume *volume)
{
@ -235,14 +235,14 @@ g_volume_get_drive (GVolume *volume)
/**
* g_volume_get_mount:
* @volume: a #GVolume.
* @volume: a #GVolume
*
* Gets the mount for the @volume.
*
* Returns: (transfer full): a #GMount or %NULL if @volume isn't mounted.
* The returned object should be unreffed with g_object_unref()
* when no longer needed.
**/
*/
GMount *
g_volume_get_mount (GVolume *volume)
{
@ -258,12 +258,12 @@ g_volume_get_mount (GVolume *volume)
/**
* g_volume_can_mount:
* @volume: a #GVolume.
* @volume: a #GVolume
*
* 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
g_volume_can_mount (GVolume *volume)
{
@ -281,12 +281,12 @@ g_volume_can_mount (GVolume *volume)
/**
* g_volume_can_eject:
* @volume: a #GVolume.
* @volume: a #GVolume
*
* 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
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: %TRUE if the volume should be automatically mounted.
* Returns: %TRUE if the volume should be automatically mounted
*/
gboolean
g_volume_should_automount (GVolume *volume)
@ -328,11 +328,11 @@ g_volume_should_automount (GVolume *volume)
/**
* g_volume_mount:
* @volume: a #GVolume.
* @volume: a #GVolume
* @flags: flags affecting the operation
* @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
* @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
* @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
* @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
* @user_data: user data that gets passed to @callback
*
* 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.
*
* Virtual: mount_fn
**/
*/
void
g_volume_mount (GVolume *volume,
GMountMountFlags flags,
@ -381,8 +381,8 @@ g_volume_mount (GVolume *volume,
* function; there's no need to listen for the 'mount-added' signal on
* #GVolumeMonitor.
*
* Returns: %TRUE, %FALSE if operation failed.
**/
* Returns: %TRUE, %FALSE if operation failed
*/
gboolean
g_volume_mount_finish (GVolume *volume,
GAsyncResult *result,
@ -404,10 +404,10 @@ g_volume_mount_finish (GVolume *volume,
/**
* g_volume_eject:
* @volume: a #GVolume.
* @volume: a #GVolume
* @flags: flags affecting the unmount if required for eject
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
* @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
* @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
* @user_data: user data that gets passed to @callback
*
* 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.
*
* Deprecated: 2.22: Use g_volume_eject_with_operation() instead.
**/
*/
void
g_volume_eject (GVolume *volume,
GMountUnmountFlags flags,
@ -443,14 +443,14 @@ g_volume_eject (GVolume *volume,
/**
* g_volume_eject_finish:
* @volume: pointer to a #GVolume.
* @result: a #GAsyncResult.
* @volume: pointer to a #GVolume
* @result: a #GAsyncResult
* @error: a #GError location to store an error, or %NULL to ignore
*
* Finishes ejecting a volume. If any errors occurred during the operation,
* @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.
**/
@ -475,13 +475,13 @@ g_volume_eject_finish (GVolume *volume,
/**
* g_volume_eject_with_operation:
* @volume: a #GVolume.
* @volume: a #GVolume
* @flags: flags affecting the unmount if required for eject
* @mount_operation: (allow-none): a #GMountOperation or %NULL to
* avoid user interaction.
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
* @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
* @user_data: user data passed to @callback.
* avoid user interaction
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
* @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
* @user_data: user data passed to @callback
*
* Ejects a volume. This is an asynchronous operation, and is
* 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:
* @volume: a #GVolume.
* @result: a #GAsyncResult.
* @error: a #GError location to store the error occurring, or %NULL to
* ignore.
* @volume: a #GVolume
* @result: a #GAsyncResult
* @error: a #GError location to store the error occurring, or %NULL
*
* Finishes ejecting a volume. If any errors occurred during the operation,
* @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
**/
@ -567,8 +566,8 @@ g_volume_eject_with_operation_finish (GVolume *volume,
* for more information about volume identifiers.
*
* Returns: a newly allocated string containing the
* requested identfier, or %NULL if the #GVolume
* doesn't have this kind of identifier
* requested identfier, or %NULL if the #GVolume
* doesn't have this kind of identifier
*/
char *
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
* other words, in code
*
* <programlisting>
* |[
* GMount *mount;
* GFile *mount_root
* GFile *volume_activation_root;
*
* mount = g_volume_get_mount (volume); /&ast; mounted, so never NULL &ast;/
* mount_root = g_mount_get_root (mount);
* volume_activation_root = g_volume_get_activation_root(volume); /&ast; assume not NULL &ast;/
* </programlisting>
*
* volume_activation_root = g_volume_get_activation_root (volume); /&ast; assume not NULL &ast;/
* ]|
* then the expression
*
* <programlisting>
* |[
* (g_file_has_prefix (volume_activation_root, mount_root) ||
g_file_equal (volume_activation_root, mount_root))
* </programlisting>
*
* ]|
* will always be %TRUE.
*
* Activation roots are typically used in #GVolumeMonitor
@ -647,10 +643,10 @@ g_volume_enumerate_identifiers (GVolume *volume)
* g_mount_is_shadowed() for more details.
*
* Returns: (transfer full): the activation root of @volume or %NULL. Use
* g_object_unref() to free.
* g_object_unref() to free.
*
* Since: 2.18
**/
*/
GFile *
g_volume_get_activation_root (GVolume *volume)
{
@ -667,16 +663,16 @@ g_volume_get_activation_root (GVolume *volume)
/**
* g_volume_get_sort_key:
* @volume: A #GVolume.
* @volume: a #GVolume
*
* 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
*/
const gchar *
g_volume_get_sort_key (GVolume *volume)
g_volume_get_sort_key (GVolume *volume)
{
const gchar *ret = NULL;
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.
*
* Here is a version of our give_me_next_number() example using
* a GStaticMutex.
*
* <example>
* <title>
* Using <structname>GStaticMutex</structname>
* to simplify thread-safe programming
* </title>
* <programlisting>
* a GStaticMutex:
* |[
* int
* give_me_next_number (void)
* {
@ -416,14 +410,13 @@ g_once_init_enter_impl (volatile gsize *location)
* int ret_val;
* 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);
* g_static_mutex_unlock (&amp;mutex);
* g_static_mutex_unlock (&mutex);
*
* return ret_val;
* }
* </programlisting>
* </example>
* ]|
*
* 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
@ -438,16 +431,15 @@ g_once_init_enter_impl (volatile gsize *location)
* the following functions, as it is defined differently on different
* platforms.
*
* All of the <function>g_static_mutex_*</function> functions apart
* from <function>g_static_mutex_get_mutex</function> can also be used
* even if g_thread_init() has not yet been called. Then they do
* nothing, apart from <function>g_static_mutex_trylock</function>,
* which does nothing but returning %TRUE.
* All of the g_static_mutex_* functions apart from
* g_static_mutex_get_mutex() can also be used even if g_thread_init()
* has not yet been called. Then they do nothing, apart from
* g_static_mutex_trylock() which does nothing but returning %TRUE.
*
* <note><para>All of the <function>g_static_mutex_*</function>
* functions are actually macros. Apart from taking their addresses, you
* can however use them as if they were functions.</para></note>
**/
* All of the g_static_mutex_* functions are actually macros. Apart from
* taking their addresses, you can however use them as if they were
* functions.
*/
/**
* 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
* freed, you should also free the #GStaticMutex.
*
* <note><para>Calling g_static_mutex_free() on a locked mutex may
* result in undefined behaviour.</para></note>
* Calling g_static_mutex_free() on a locked mutex may result in
* undefined behaviour.
*
* 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
* read from, while others also write. In such situations it is
* 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
* example:
* only one writer may write at a time.
*
* <example>
* <title>An array with access functions</title>
* <programlisting>
* Take a look at the following example:
* |[
* GStaticRWLock rwlock = G_STATIC_RW_LOCK_INIT;
* GPtrArray *array;
*
@ -879,10 +869,10 @@ g_static_rec_mutex_free (GStaticRecMutex *mutex)
* if (!array)
* return NULL;
*
* g_static_rw_lock_reader_lock (&amp;rwlock);
* if (index &lt; array->len)
* g_static_rw_lock_reader_lock (&rwlock);
* if (index < array->len)
* retval = g_ptr_array_index (array, index);
* g_static_rw_lock_reader_unlock (&amp;rwlock);
* g_static_rw_lock_reader_unlock (&rwlock);
*
* return retval;
* }
@ -890,27 +880,25 @@ g_static_rec_mutex_free (GStaticRecMutex *mutex)
* void
* my_array_set (guint index, gpointer data)
* {
* g_static_rw_lock_writer_lock (&amp;rwlock);
* g_static_rw_lock_writer_lock (&rwlock);
*
* 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_set_size (array, index + 1);
* 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
* (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.
* (the my_array_get() function) simultaneously, whereas the writers
* (the my_array_set() 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.
*
* Most of the time, writers should have precedence over readers. That
* 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
* with the following functions.
*
* All of the <function>g_static_rw_lock_*</function> functions can be
* used even if g_thread_init() has not been called. Then they do
* nothing, apart from <function>g_static_rw_lock_*_trylock</function>,
* which does nothing but returning %TRUE.
* All of the g_static_rw_lock_* functions can be used even if
* g_thread_init() has not been called. Then they do nothing, apart
* from g_static_rw_lock_*_trylock, which does nothing but returning %TRUE.
*
* <note><para>A read-write lock has a higher overhead than a mutex. For
* example, both g_static_rw_lock_reader_lock() and
* g_static_rw_lock_reader_unlock() have to lock and unlock a
* #GStaticMutex, so it takes at least twice the time to lock and unlock
* a #GStaticRWLock that it does to lock and unlock a #GStaticMutex. So
* only data structures that are accessed by multiple readers, and which
* keep the lock for a considerable time justify a #GStaticRWLock. The
* above example most probably would fare better with a
* #GStaticMutex.</para></note>
* A read-write lock has a higher overhead than a mutex. For example, both
* g_static_rw_lock_reader_lock() and g_static_rw_lock_reader_unlock() have
* to lock and unlock a #GStaticMutex, so it takes at least twice the time
* to lock and unlock a #GStaticRWLock that it does to lock and unlock a
* #GStaticMutex. So only data structures that are accessed by multiple
* readers, and which keep the lock for a considerable time justify a
* #GStaticRWLock. The above example most probably would fare better with a
* #GStaticMutex.
*
* 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:
* @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
* 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
* 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
*/
@ -1061,7 +1047,7 @@ g_static_rw_lock_reader_trylock (GStaticRWLock* lock)
/**
* 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
* 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:
* @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
* 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:
* @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
* either reading or writing) by another thread, it immediately returns
* %FALSE. Otherwise it locks @lock for writing and returns %TRUE. This
* 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
*/
@ -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
* significant advantage. It doesn't need to be created at run-time
* like a #GPrivate, but can be defined at compile-time. This is
* similar to the difference between #GMutex and #GStaticMutex. Now
* look at our <function>give_me_next_number()</function> example with
* #GStaticPrivate:
* similar to the difference between #GMutex and #GStaticMutex.
*
* <example>
* <title>Using GStaticPrivate for per-thread data</title>
* <programlisting>
* Now look at our give_me_next_number() example with #GStaticPrivate:
* |[
* int
* give_me_next_number (<!-- -->)
* give_me_next_number ()
* {
* 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)
* {
* current_number = g_new (int,1);
* current_number = g_new (int, 1);
* *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);
*
* 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
* g_thread_init().
*
* <note><para>@notify is used quite differently from @destructor in
* g_private_new().</para></note>
* @notify is used quite differently from @destructor in g_private_new().
*/
void
g_static_private_set (GStaticPrivate *private_key,
@ -1561,6 +1542,7 @@ g_cond_free (GCond *cond)
* and g_time_val_add() can be used.
*
* Returns: %TRUE if @cond was signalled, or %FALSE on timeout
*
* Deprecated:2.32: Use g_cond_wait_until() instead.
*/
gboolean

54
glib/garray.c
View File

@ -67,13 +67,13 @@
*
* 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:
* |[
* 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. *<!-- -->/
* /&ast; We create a new array to store gint values.
* &ast; We don't want it zero-terminated or cleared to 0's.
* &ast;/
* garray = g_array_new (FALSE, FALSE, sizeof (gint));
* for (i = 0; i &lt; 10000; i++)
* g_array_append_val (garray, i);
@ -82,8 +82,7 @@
* g_print ("ERROR: got &percnt;d instead of &percnt;d\n",
* g_array_index (garray, gint, i), i);
* g_array_free (garray, TRUE);
* </programlisting>
* </example>
* ]|
*/
#define MIN_ARRAY_SIZE 16
@ -120,15 +119,14 @@ struct _GRealArray
* 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:
* |[
* EDayViewEvent *event;
* /<!-- -->* This gets a pointer to the 4th element
* in the array of EDayViewEvent structs. *<!-- -->/
* /&ast; This gets a pointer to the 4th element
* &ast; in the array of EDayViewEvent structs.
* &ast;/
* event = &amp;g_array_index (events, EDayViewEvent, 3);
* </programlisting>
* </example>
* ]|
*
* 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().
*
* <example>
* <title>Using a #GPtrArray</title>
* <programlisting>
* An example using a #GPtrArray:
* |[
* GPtrArray *gparray;
* 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) string2);
* g_ptr_array_add (gparray, (gpointer) string3);
*
* 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_free (gparray, TRUE);
* </programlisting>
* </example>
**/
* ]|
*/
typedef struct _GRealPtrArray GRealPtrArray;
@ -1517,17 +1513,16 @@ g_ptr_array_foreach (GPtrArray *array,
*
* To free a #GByteArray, use g_byte_array_free().
*
* <example>
* <title>Using a #GByteArray</title>
* <programlisting>
* An example for using a #GByteArray:
* |[
* GByteArray *gbarray;
* gint i;
*
* gbarray = g_byte_array_new (<!-- -->);
* for (i = 0; i &lt; 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 &lt; 10000; i++)
* for (i = 0; i < 10000; i++)
* {
* g_assert (gbarray->data[4*i] == 'a');
* g_assert (gbarray->data[4*i+1] == 'b');
@ -1536,8 +1531,7 @@ g_ptr_array_foreach (GPtrArray *array,
* }
*
* g_byte_array_free (gbarray, TRUE);
* </programlisting>
* </example>
* ]|
*
* See #GBytes if you are interested in an immutable object representing a
* sequence of bytes.

2
glib/gconvert.c
View File

@ -72,7 +72,7 @@
* <refsect2 id="file-name-encodings">
* <title>File Name Encodings</title>
* <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
* separators in it ("/"). However, displaying file names may
* 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
* #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:
* |[
* 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+:
* |[
* 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 all messages from GLib</title>
* <programlisting>
* This example adds a log handler for all messages from GLib:
* |[
* 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
*/

5
glib/goption.c
View File

@ -91,8 +91,7 @@
*
* Here is a complete example of setting up GOption to parse the example
* commandline above and produce the example help output.
*
* <informalexample><programlisting>
* |[
* static gint repeats = 2;
* static gint max_size = 8;
* static gboolean verbose = FALSE;
@ -127,7 +126,7 @@
* /&ast; ... &ast;/
*
* }
* </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

25
glib/gslice.c
View File

@ -89,32 +89,29 @@
* 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:
* |[
* gchar *mem[10000];
* gint i;
*
* /&ast; Allocate 10000 blocks. &ast;/
* for (i = 0; i &lt; 10000; i++)
* for (i = 0; i < 10000; i++)
* {
* mem[i] = g_slice_alloc (50);
*
* /&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;
* }
*
* /&ast; Now free all of the blocks. &ast;/
* for (i = 0; i &lt; 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:
* |[
* GRealArray *array;
*
* /&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;/
* g_slice_free (GRealArray, array);
* </programlisting></example>
* ]|
*/
/* 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.
*
* 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):
*
* |[
@ -820,12 +820,12 @@ g_cond_broadcast (GCond *cond)
* while (!current_data)
* if (!g_cond_wait_until (&data_cond, &data_mutex, end_time))
* {
* // timeout has passed.
* /&ast; timeout has passed. &ast;/
* g_mutex_unlock (&data_mutex);
* return NULL;
* }
*
* // there is data for us
* /&ast; there is data for us &ast;/
* data = current_data;
* current_data = NULL;
*
@ -920,7 +920,7 @@ g_cond_wait_until (GCond *cond,
* |[
* 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 *
* 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
* 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
* 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:
* |[
* G_LOCK_DEFINE (current_number);
*
* int
@ -182,8 +180,7 @@
*
* return ret_val;
* }
* </programlisting>
* </example>
* ]|
*/
/**
@ -234,33 +231,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:
* |[
* 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
* *<!-- -->/
* /&ast; now do a very complicated calculation to calculate the new
* &ast; number, this might for example be a random number generator
* &ast;/
* 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>
* |[
* int
* give_me_next_number (void)
* {
@ -274,9 +265,7 @@
*
* 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.
@ -325,9 +314,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:
* |[
* GRWLock lock;
* GPtrArray *array;
*
@ -340,7 +328,7 @@
* return NULL;
*
* g_rw_lock_reader_lock (&amp;lock);
* if (index &lt; array->len)
* if (index < array->len)
* retval = g_ptr_array_index (array, index);
* g_rw_lock_reader_unlock (&amp;lock);
*
@ -350,35 +338,30 @@
* void
* my_array_set (guint index, gpointer data)
* {
* g_rw_lock_writer_lock (&amp;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 (&amp;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
*/
@ -399,11 +382,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:
* |[
* gpointer current_data = NULL;
* GMutex data_mutex;
* GCond data_cond;
@ -431,21 +412,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
@ -453,11 +432,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.
*/
/* 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.
*
* 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.

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.
*
* Consider this simple example:
*
* <informalexample><programlisting>
* |[
* 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

67
glib/gvariant.c
View File

@ -1103,8 +1103,8 @@ g_variant_lookup_value (GVariant *dictionary,
* 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'>
@ -1121,16 +1121,16 @@ g_variant_lookup_value (GVariant *dictionary,
* </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
**/
@ -3070,10 +3070,9 @@ g_variant_iter_free (GVariantIter *iter)
* 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():
* |[
* /&ast; recursively iterate a container &ast;/
* void
* iterate_container_recursive (GVariant *container)
* {
@ -3091,8 +3090,7 @@ g_variant_iter_free (GVariantIter *iter)
* g_variant_unref (child);
* }
* }
* </programlisting>
* </example>
* ]|
*
* 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
* 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():
* |[
* /&ast; Iterates a dictionary of type 'a{sv}' &ast;/
* void
* iterate_dictionary (GVariant *dictionary)
* {
@ -5005,20 +4999,20 @@ g_variant_get_child (GVariant *value,
* g_print ("Item '%s' has type '%s'\n", key,
* g_variant_get_type_string (value));
*
* /<!-- -->* must free data for ourselves *<!-- -->/
* /&ast; must free data for ourselves &ast;/
* 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
@ -5081,13 +5075,9 @@ g_variant_iter_next (GVariantIter *iter,
* 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():
* |[
* /&ast; Iterates a dictionary of type 'a{sv}' &ast;/
* void
* iterate_dictionary (GVariant *dictionary)
* {
@ -5101,12 +5091,12 @@ g_variant_iter_next (GVariantIter *iter,
* 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 *<!-- -->/
* /&ast; no need to free 'key' and 'value' here
* &ast; unless breaking out of this loop
* &ast;/
* }
* }
* </programlisting>
* </example>
* ]|
*
* 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).
*
* @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

24
glib/gversion.c
View File

@ -85,17 +85,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.
@ -109,9 +99,9 @@ const guint glib_binary_age = GLIB_BINARY_AGE;
/**
* 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
@ -129,9 +119,9 @@ const guint glib_binary_age = GLIB_BINARY_AGE;
* (same major version.)
*
* Return value: %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
*/

34
gobject/gobject.c
View File

@ -57,11 +57,11 @@
* container = create_container ();
* container_add_child (container, create_child());
* ]|
* If <function>container_add_child()</function> will g_object_ref_sink() the
* passed in child, no reference of the newly created child is leaked.
* Without floating references, <function>container_add_child()</function>
* can only g_object_ref() the new child, so to implement this code without
* reference leaks, it would have to be written as:
* If container_add_child() calls g_object_ref_sink() on the passed-in child,
* no reference of the newly created child is leaked. Without floating
* references, container_add_child() can only g_object_ref() the new child,
* so to implement this code without reference leaks, it would have to be
* written as:
* |[
* Child *child;
* container = create_container ();
@ -69,11 +69,11 @@
* container_add_child (container, child);
* g_object_unref (child);
* ]|
* The floating reference can be converted into
* an ordinary reference by calling g_object_ref_sink().
* For already sunken objects (objects that don't have a floating reference
* anymore), g_object_ref_sink() is equivalent to g_object_ref() and returns
* a new reference.
* The floating reference can be converted into an ordinary reference by
* calling g_object_ref_sink(). For already sunken objects (objects that
* don't have a floating reference anymore), g_object_ref_sink() is equivalent
* to g_object_ref() and returns a new reference.
*
* Since floating references are useful almost exclusively for C convenience,
* language bindings that provide automated reference and memory ownership
* 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
* the type, for instance by calling g_free() or g_object_unref().
*
* <example>
* <title>Using g_object_get(<!-- -->)</title>
* 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>
* Here is an example of using g_object_get() to get the contents
* of three properties: an integer, a string and an object:
* |[
* gint intval;
* gchar *strval;
* GObject *objval;
@ -2243,12 +2240,11 @@ g_object_set (gpointer _object,
* "obj-property", &objval,
* NULL);
*
* // Do something with intval, strval, objval
* /&ast; Do something with intval, strval, objval &ast;/
*
* g_free (strval);
* g_object_unref (objval);
* </programlisting>
* </example>
* ]|
*/
void
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
* class passed in. Since derived classes hold a reference count on
* their parent classes as long as they are instantiated, the returned
* class will always exist. This function is essentially equivalent
* to:
* class will always exist.
*
* <programlisting>
* g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class)));
* </programlisting>
* This function is essentially equivalent to:
* g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class)))
*
* Returns: (type GObject.TypeClass) (transfer none): the parent class
* of @g_class