Commit 17f51583 authored by Matthias Clasen's avatar Matthias Clasen

Docs: Convert examples to |[ ]|

parent 4d12e0d6
......@@ -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
*/
......
......@@ -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
......
......@@ -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)
......
......@@ -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
......
......@@ -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().
*
......
......@@ -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.
......
......@@ -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
*
......
......@@ -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.
......
......@@ -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
......
......@@ -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
......
......@@ -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>
......
......@@ -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>
*/
......
......@@ -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;