[glib] Docs: Convert examples to |[ ]|
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glib] Docs: Convert examples to |[ ]|
- Date: Sat, 1 Feb 2014 03:14:13 +0000 (UTC)
commit 17f51583a8733c312f5ac53478b36c5f3972ab45
Author: Matthias Clasen <mclasen redhat com>
Date: Fri Jan 31 21:56:33 2014 -0500
Docs: Convert examples to |[ ]|
gio/gactionmap.c | 7 +-
gio/gapplication.c | 22 +++---
gio/gcontenttype.c | 7 +-
gio/gdbuserror.c | 16 ++--
gio/gdbusmessage.c | 8 +-
gio/gfile.c | 4 +-
gio/gmenu.c | 10 +--
gio/gresource.c | 10 +-
gio/gsettings.c | 16 ++--
gio/gsimpleaction.c | 20 ++---
gio/gtask.c | 31 ++++----
gio/gtestdbus.c | 13 ++--
gio/gvolume.c | 124 +++++++++++++++----------------
glib/deprecated/gthread-deprecated.c | 134 +++++++++++++++-------------------
glib/garray.c | 54 ++++++--------
glib/gconvert.c | 2 +-
glib/gmessages.c | 26 +++----
glib/goption.c | 5 +-
glib/gslice.c | 25 +++----
glib/gthread-posix.c | 10 +-
glib/gthread.c | 102 ++++++++++----------------
glib/gurifuncs.c | 4 +-
glib/gvariant-parser.c | 5 +-
glib/gvariant.c | 67 +++++++----------
glib/gversion.c | 24 ++----
gobject/gobject.c | 34 ++++-----
gobject/gtype.c | 8 +-
27 files changed, 346 insertions(+), 442 deletions(-)
---
diff --git a/gio/gactionmap.c b/gio/gactionmap.c
index 866f98a..be4fe4d 100644
--- a/gio/gactionmap.c
+++ b/gio/gactionmap.c
@@ -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
*/
diff --git a/gio/gapplication.c b/gio/gapplication.c
index db9e165..fd703dd 100644
--- a/gio/gapplication.c
+++ b/gio/gapplication.c
@@ -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
diff --git a/gio/gcontenttype.c b/gio/gcontenttype.c
index 49bd196..a3b6dde 100644
--- a/gio/gcontenttype.c
+++ b/gio/gcontenttype.c
@@ -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)
diff --git a/gio/gdbuserror.c b/gio/gdbuserror.c
index 369559c..a358cbe 100644
--- a/gio/gdbuserror.c
+++ b/gio/gdbuserror.c
@@ -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: *<!-- -->/
+ * |[
+ * /* foo-bar-error.h: */
*
* #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 /*< skip >*/
* } FooBarError;
*
- * /<!-- -->* foo-bar-error.c: *<!-- -->/
+ * /* foo-bar-error.c: */
*
* 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 *<!-- -->/
+ * /* Ensure that every error code has an associated D-Bus error name */
* 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
diff --git a/gio/gdbusmessage.c b/gio/gdbusmessage.c
index f3bf064..dff5acf 100644
--- a/gio/gdbusmessage.c
+++ b/gio/gdbusmessage.c
@@ -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: method-call
* Flags: none
* Version: 0
@@ -3362,9 +3362,9 @@ _sort_keys_func (gconstpointer a,
* Body: ()
* UNIX File Descriptors:
* (none)
- * </programlisting>
+ * ]|
* or
- * <programlisting>
+ * |[
* Type: method-return
* Flags: no-reply-expected
* Version: 0
@@ -3377,7 +3377,7 @@ _sort_keys_func (gconstpointer a,
* Body: ()
* UNIX File Descriptors:
* 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().
*
diff --git a/gio/gfile.c b/gio/gfile.c
index d438d1f..9dab65b 100644
--- a/gio/gfile.c
+++ b/gio/gfile.c
@@ -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.
diff --git a/gio/gmenu.c b/gio/gmenu.c
index e785db6..fe82ba7 100644
--- a/gio/gmenu.c
+++ b/gio/gmenu.c
@@ -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
*
diff --git a/gio/gresource.c b/gio/gresource.c
index 04b34c2..3af0348 100644
--- a/gio/gresource.c
+++ b/gio/gresource.c
@@ -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.
diff --git a/gio/gsettings.c b/gio/gsettings.c
index 789870c..c166791 100644
--- a/gio/gsettings.c
+++ b/gio/gsettings.c
@@ -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
diff --git a/gio/gsimpleaction.c b/gio/gsimpleaction.c
index dff8c90..7c1a43b 100644
--- a/gio/gsimpleaction.c
+++ b/gio/gsimpleaction.c
@@ -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
+ * /* Volume only goes from 0 to 10 */
* 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
diff --git a/gio/gtask.c b/gio/gtask.c
index f56532d..fa7b47c 100644
--- a/gio/gtask.c
+++ b/gio/gtask.c
@@ -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>
diff --git a/gio/gtestdbus.c b/gio/gtestdbus.c
index 7cb24f2..e059a72 100644
--- a/gio/gtestdbus.c
+++ b/gio/gtestdbus.c
@@ -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>
*/
diff --git a/gio/gvolume.c b/gio/gvolume.c
index 9f06701..3998dbe 100644
--- a/gio/gvolume.c
+++ b/gio/gvolume.c
@@ -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); /* mounted, so never NULL */
* mount_root = g_mount_get_root (mount);
- * volume_activation_root = g_volume_get_activation_root(volume); /* assume not NULL */
- * </programlisting>
- *
+ * volume_activation_root = g_volume_get_activation_root (volume); /* assume not NULL */
+ * ]|
* 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;
diff --git a/glib/deprecated/gthread-deprecated.c b/glib/deprecated/gthread-deprecated.c
index 02153ad..6c38ee5 100644
--- a/glib/deprecated/gthread-deprecated.c
+++ b/glib/deprecated/gthread-deprecated.c
@@ -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 (&mutex);
+ * g_static_mutex_lock (&mutex);
* ret_val = current_number = calc_next_number (current_number);
- * g_static_mutex_unlock (&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 (&rwlock);
- * if (index < 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 (&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 (&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 (&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 (&current_number_key);
+ * int *current_number = g_static_private_get (¤t_number_key);
*
* if (!current_number)
* {
- * current_number = g_new (int,1);
+ * current_number = g_new (int, 1);
* *current_number = 0;
- * g_static_private_set (&current_number_key, current_number, g_free);
+ * g_static_private_set (¤t_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
diff --git a/glib/garray.c b/glib/garray.c
index 7c2ad13..3895853 100644
--- a/glib/garray.c
+++ b/glib/garray.c
@@ -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. *<!-- -->/
+ * /* We create a new array to store gint values.
+ * * We don't want it zero-terminated or cleared to 0's.
+ * */
* garray = g_array_new (FALSE, FALSE, sizeof (gint));
* for (i = 0; i < 10000; i++)
* g_array_append_val (garray, i);
@@ -82,8 +82,7 @@
* g_print ("ERROR: got %d instead of %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. *<!-- -->/
+ * /* This gets a pointer to the 4th element
+ * * in the array of EDayViewEvent structs.
+ * */
* event = &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 %p instead of %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 < 10000; i++)
+ * gbarray = g_byte_array_new ();
+ * for (i = 0; i < 10000; i++)
* g_byte_array_append (gbarray, (guint8*) "abcd", 4);
*
- * for (i = 0; i < 10000; i++)
+ * for (i = 0; i < 10000; i++)
* {
* g_assert (gbarray->data[4*i] == 'a');
* g_assert (gbarray->data[4*i+1] == 'b');
@@ -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.
diff --git a/glib/gconvert.c b/glib/gconvert.c
index df69bb2..53b9b1a 100644
--- a/glib/gconvert.c
+++ b/glib/gconvert.c
@@ -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
diff --git a/glib/gmessages.c b/glib/gmessages.c
index 2509f7b..8b43b97 100644
--- a/glib/gmessages.c
+++ b/glib/gmessages.c
@@ -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
*/
diff --git a/glib/goption.c b/glib/goption.c
index 64e170a..10db7ae 100644
--- a/glib/goption.c
+++ b/glib/goption.c
@@ -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 @@
* /* ... */
*
* }
- * </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
diff --git a/glib/gslice.c b/glib/gslice.c
index 9da316a..9b04c1d 100644
--- a/glib/gslice.c
+++ b/glib/gslice.c
@@ -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;
*
* /* Allocate 10000 blocks. */
- * for (i = 0; i < 10000; i++)
+ * for (i = 0; i < 10000; i++)
* {
* mem[i] = g_slice_alloc (50);
*
* /* Fill in the memory with some junk. */
- * for (j = 0; j < 50; j++)
+ * for (j = 0; j < 50; j++)
* mem[i][j] = i * j;
* }
*
* /* Now free all of the blocks. */
- * for (i = 0; i < 10000; i++)
- * {
- * g_slice_free1 (50, mem[i]);
- * }
- * </programlisting></example>
+ * for (i = 0; i < 10000; i++)
+ * g_slice_free1 (50, mem[i]);
+ * ]|
*
- * <example>
- * <title>Using the slice allocator with data structures</title>
- * <programlisting>
+ * And here is an example for using the using the slice allocator
+ * with data structures:
+ * |[
* GRealArray *array;
*
* /* Allocate one block, using the g_slice_new() macro. */
@@ -130,7 +127,7 @@
*
* /* We can free the block, so it can be reused. */
* g_slice_free (GRealArray, array);
- * </programlisting></example>
+ * ]|
*/
/* the GSlice allocator is split up into 4 layers, roughly modelled after the slab
diff --git a/glib/gthread-posix.c b/glib/gthread-posix.c
index 79afd32..5c559fd 100644
--- a/glib/gthread-posix.c
+++ b/glib/gthread-posix.c
@@ -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.
+ * /* timeout has passed. */
* g_mutex_unlock (&data_mutex);
* return NULL;
* }
*
- * // there is data for us
+ * /* there is data for us */
* data = current_data;
* current_data = NULL;
*
@@ -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
+ * /* return value should not be freed */
* 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; /* no free function */
*
* gint
* get_local_count (void)
diff --git a/glib/gthread.c b/glib/gthread.c
index ffac638..8b828a2 100644
--- a/glib/gthread.c
+++ b/glib/gthread.c
@@ -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
- * *<!-- -->/
+ * /* now do a very complicated calculation to calculate the new
+ * * number, this might for example be a random number generator
+ * */
* current_number = calc_next_number (current_number);
*
* return current_number;
* }
- * </programlisting>
- * </example>
- *
+ * ]|
* It is easy to see that this won't work in a multi-threaded
* application. There current_number must be protected against shared
* access. A #GMutex can be used as a solution to this problem:
- *
- * <example>
- * <title>Using GMutex to protected a shared variable</title>
- * <programlisting>
+ * |[
* 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 (&lock);
- * if (index < array->len)
+ * if (index < array->len)
* retval = g_ptr_array_index (array, index);
* g_rw_lock_reader_unlock (&lock);
*
@@ -350,35 +338,30 @@
* void
* my_array_set (guint index, gpointer data)
* {
- * g_rw_lock_writer_lock (&lock);
+ * g_rw_lock_writer_lock (&lock);
*
* if (!array)
- * array = g_ptr_array_new (<!-- -->);
+ * array = g_ptr_array_new ();
*
* if (index >= array->len)
* g_ptr_array_set_size (array, index+1);
* g_ptr_array_index (array, index) = data;
*
- * g_rw_lock_writer_unlock (&lock);
+ * g_rw_lock_writer_unlock (&lock);
* }
- * </programlisting>
- * <para>
- * This example shows an array which can be accessed by many readers
- * (the <function>my_array_get()</function> function) simultaneously,
- * whereas the writers (the <function>my_array_set()</function>
- * function) will only be allowed once at a time and only if no readers
- * currently access the array. This is because of the potentially
- * dangerous resizing of the array. Using these functions is fully
- * multi-thread safe now.
- * </para>
- * </example>
+ * ]|
+ * This example shows an array which can be accessed by many readers
+ * (the my_array_get() function) simultaneously, whereas the writers
+ * (the my_array_set() function) will only be allowed one at a time
+ * and only if no readers currently access the array. This is because
+ * of the potentially dangerous resizing of the array. Using these
+ * functions is fully multi-thread safe now.
*
* If a #GRWLock is allocated in static storage then it can be used
* without initialisation. Otherwise, you should call
* g_rw_lock_init() on it and g_rw_lock_clear() when done.
*
- * A GRWLock should only be accessed with the
- * <function>g_rw_lock_</function> functions.
+ * A GRWLock should only be accessed with the g_rw_lock_ functions.
*
* Since: 2.32
*/
@@ -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 ---------------------------------------- */
diff --git a/glib/gurifuncs.c b/glib/gurifuncs.c
index 54f9a0f..33d9eca 100644
--- a/glib/gurifuncs.c
+++ b/glib/gurifuncs.c
@@ -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.
diff --git a/glib/gvariant-parser.c b/glib/gvariant-parser.c
index e4a551e..bcc37b7 100644
--- a/glib/gvariant-parser.c
+++ b/glib/gvariant-parser.c
@@ -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
diff --git a/glib/gvariant.c b/glib/gvariant.c
index 591dcf3..79849f0 100644
--- a/glib/gvariant.c
+++ b/glib/gvariant.c
@@ -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():
+ * |[
+ * /* recursively iterate a container */
* 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():
+ * |[
+ * /* Iterates a dictionary of type 'a{sv}' */
* 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 *<!-- -->/
+ * /* must free data for ourselves */
* g_variant_unref (value);
* g_free (key);
* }
* }
- * </programlisting>
- * </example>
+ * ]|
*
* For a solution that is likely to be more convenient to C programmers
* when dealing with loops, see g_variant_iter_loop().
*
* @format_string determines the C types that are used for unpacking
- * the values and also determines if the values are copied or borrowed,
- * see the section on
+ * the values and also determines if the values are copied or borrowed.
+ *
+ * See the section on
* <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
*
* Returns: %TRUE if a value was unpacked, or %FALSE if there as no value
@@ -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():
+ * |[
+ * /* Iterates a dictionary of type 'a{sv}' */
* 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 *<!-- -->/
+ * /* no need to free 'key' and 'value' here
+ * * unless breaking out of this loop
+ * */
* }
* }
- * </programlisting>
- * </example>
+ * ]|
*
* For most cases you should use g_variant_iter_next().
*
@@ -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
diff --git a/glib/gversion.c b/glib/gversion.c
index e8d71b8..d1c30bf 100644
--- a/glib/gversion.c
+++ b/glib/gversion.c
@@ -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
*/
diff --git a/gobject/gobject.c b/gobject/gobject.c
index a18fcfb..258f996 100644
--- a/gobject/gobject.c
+++ b/gobject/gobject.c
@@ -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
+ * /* Do something with intval, strval, objval */
*
* g_free (strval);
* g_object_unref (objval);
- * </programlisting>
- * </example>
+ * ]|
*/
void
g_object_get (gpointer _object,
diff --git a/gobject/gtype.c b/gobject/gtype.c
index d729da6..1df9cc5 100644
--- a/gobject/gtype.c
+++ b/gobject/gtype.c
@@ -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
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
