diff --git a/gio/gactionmap.c b/gio/gactionmap.c index 866f98a5b..be4fe4d6d 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. * - * - * Using g_action_map_add_action_entries() - * + * |[ * 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); * } - * - * + * ]| * * Since: 2.32 */ diff --git a/gio/gapplication.c b/gio/gapplication.c index db9e165f3..fd703dd76 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 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. + * 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 49bd19694..a3b6dde99 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 - * - * g_list_free_full (list, g_free); - * + * 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 369559c7d..a358cbeda 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: - * Error Registration - * /* 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; * } - * + * ]| * 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 org.project.Foo.Bar.Error.AnotherError. + * 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 - * org.project.Foo.Bar.Error.AnotherError 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 f3bf06424..dff5acfb6 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: - * + * |[ * Type: method-call * Flags: none * Version: 0 @@ -3362,9 +3362,9 @@ _sort_keys_func (gconstpointer a, * Body: () * UNIX File Descriptors: * (none) - * + * ]| * or - * + * |[ * 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 - * + * ]| * * Returns: A string that should be freed with g_free(). * diff --git a/gio/gfile.c b/gio/gfile.c index d438d1f77..9dab65bba 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: - * + * |[ * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] - * + * ]| * 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 e785db610..fe82ba7a0 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: - * - * *
* @@ -1216,7 +1215,7 @@ g_menu_item_new_submenu (const gchar *label, * *
* - * ]]> + * ]| * * 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). - * - * * * @@ -1241,7 +1239,7 @@ g_menu_item_new_submenu (const gchar *label, * * * - * ]]> + * ]| * * Returns: a new #GMenuItem * diff --git a/gio/gresource.c b/gio/gresource.c index 04b34c2c9..3af03485e 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 resource description - * * * @@ -92,14 +92,14 @@ G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref) * menumarkup.xml * * - * ]]> + * ]| * * This will create a resource bundle with the following files: - * + * ]| * * 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 789870c89..c16679118 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. * - * Default values - * * * @@ -137,10 +137,10 @@ * * * - * ]]> + * ]| * - * Ranges, choices and enumerated types - * * * @@ -183,7 +183,7 @@ * * * - * ]]> + * ]| * * * Vendor overrides @@ -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: - * + * |[ * [org.gtk.Example] * key1='string' * key2=1.5 - * + * ]| * * * glib-compile-schemas expects schema files to have the extension diff --git a/gio/gsimpleaction.c b/gio/gsimpleaction.c index dff8c908c..7c1a43b8c 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 'change-state' handler - * + * 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); * } - * - * + * ]| * - * 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 f56532d04..fa7b47ccb 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. * - * GTask as a GAsyncResult - * + * 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); * } - * - * + * ]| * * * Chained asynchronous operations @@ -161,8 +160,9 @@ * source to fire (automatically using the correct #GMainContext * and priority). * - * Chained asynchronous operations - * + * + * 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); * } - * - * + * ]| * * * Asynchronous operations from synchronous ones @@ -298,8 +297,9 @@ * which will then dispatch the result back to the caller's * #GMainContext when it completes. * - * g_task_run_in_thread() - * + * + * 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); * } - * - * + * ]| * * * Adding cancellability to uncancellable tasks @@ -384,8 +383,9 @@ * to make "GLib-friendly" asynchronous and cancellable * synchronous variants of blocking APIs. * - * g_task_set_return_on_cancel() - * + * + * Cancelling a task: + * |[ * static void * bake_cake_thread (GTask *task, * gpointer source_object, @@ -474,8 +474,7 @@ * g_object_unref (task); * return cake; * } - * - * + * ]| * * * Porting from <literal>GSimpleAsyncResult</literal> diff --git a/gio/gtestdbus.c b/gio/gtestdbus.c index 7cb24f266..e059a724f 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 my-server.service.in * in the services * directory and have it processed by configure. - * + * |[ * [D-BUS Service] * Name=org.gtk.GDBus.Examples.ObjectManager * Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server - * + * ]| * 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: - * + * |[ * -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\" - * + * ]| * * * 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. - * * Test Fixture for D-Bus services * * @@ -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: - * + * |[ * all-am: * $(GLIB_COMPILE_SCHEMAS) . * * CLEANFILES += gschemas.compiled - * + * ]| * * */ diff --git a/gio/gvolume.c b/gio/gvolume.c index 9f0670174..3998dbe5b 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 * - * + * |[ * 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 */ - * - * + * volume_activation_root = g_volume_get_activation_root (volume); /* assume not NULL */ + * ]| * then the expression - * - * + * |[ * (g_file_has_prefix (volume_activation_root, mount_root) || g_file_equal (volume_activation_root, mount_root)) - * - * + * ]| * 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 02153ada6..6c38ee5f8 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. - * - * - * - * Using <structname>GStaticMutex</structname> - * to simplify thread-safe programming - * - * + * 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; * } - * - * + * ]| * * 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 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. + * 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. * - * 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. - **/ + * 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. * - * Calling g_static_mutex_free() on a locked mutex may - * result in undefined behaviour. + * 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. * - * - * An array with access functions - * + * 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); * } - * - * + * ]| * * 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 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 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. + * 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. * - * 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. + * 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 give_me_next_number() example with - * #GStaticPrivate: + * similar to the difference between #GMutex and #GStaticMutex. * - * - * Using GStaticPrivate for per-thread data - * + * 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; * } - * - * + * ]| */ /** @@ -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(). * - * @notify is used quite differently from @destructor in - * g_private_new(). + * @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 7c2ad136b..389585391 100644 --- a/glib/garray.c +++ b/glib/garray.c @@ -67,13 +67,13 @@ * * To free an array, use g_array_free(). * - * - * Using a #GArray to store #gint values - * + * 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); - * - * + * ]| */ #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. * - * - * Getting a pointer to an element in a #GArray - * + * 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); - * - * + * ]| * * 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(). * - * - * Using a #GPtrArray - * + * 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); - * - * - **/ + * ]| + */ typedef struct _GRealPtrArray GRealPtrArray; @@ -1517,17 +1513,16 @@ g_ptr_array_foreach (GPtrArray *array, * * To free a #GByteArray, use g_byte_array_free(). * - * - * Using a #GByteArray - * + * 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); - * - * + * ]| * * 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 df69bb243..53b9b1a77 100644 --- a/glib/gconvert.c +++ b/glib/gconvert.c @@ -72,7 +72,7 @@ * * File Name Encodings * - * 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 2509f7b27..8b43b971e 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. * - * - * Adding a log handler for all warning messages in the default - * (application) domain - * + * 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); - * - * + * ]| * - * - * Adding a log handler for all critical messages from GTK+ - * + * 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); - * - * + * ]| * - * - * Adding a log handler for all messages from GLib - * + * 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); - * - * + * ]| * * Returns: the id of the new handler */ diff --git a/glib/goption.c b/glib/goption.c index 64e170a80..10db7ae57 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. - * - * + * |[ * static gint repeats = 2; * static gint max_size = 8; * static gboolean verbose = FALSE; @@ -127,7 +126,7 @@ * /* ... */ * * } - * + * ]| * * 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 9da316a85..9b04c1d40 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. * - * - * Using the slice allocator - * + * 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]); - * } - * + * for (i = 0; i < 10000; i++) + * g_slice_free1 (50, mem[i]); + * ]| * - * - * Using the slice allocator with data structures - * + * 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); - * + * ]| */ /* 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 79afd3292..5c559fdfa 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 ffac638a1..8b828a2e7 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 - * give_me_next_number() example using the - * G_LOCK_* macros: + * give_me_next_number() example using the #G_LOCK macros: * - * - * Using the <literal>G_LOCK_*</literal> convenience macros - * + * Here is an example for using the #G_LOCK convenience macros: + * |[ * G_LOCK_DEFINE (current_number); * * int @@ -182,8 +180,7 @@ * * return ret_val; * } - * - * + * ]| */ /** @@ -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. * - * - * A function which will not work in a threaded environment - * + * 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; * } - * - * - * + * ]| * 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: - * - * - * Using GMutex to protected a shared variable - * + * |[ * int * give_me_next_number (void) * { @@ -274,9 +265,7 @@ * * return ret_val; * } - * - * - * + * ]| * 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()). * - * - * An array with access functions - * + * 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); * } - * - * - * 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 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. - * - * + * ]| + * 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 - * g_rw_lock_ 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. * - * - * - * Using GCond to block a thread until a condition is satisfied - * - * + * 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; * } - * - * - * + * ]| * 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 current_data by the - * while loop in pop_data and waiting. - * Specifically, another thread could set pop_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. + * 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 g_cond_ - * 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 54f9a0f2a..33d9eca44 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: - * + * |[ * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] - * + * ]| * 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 e4a551e72..bcc37b786 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: - * - * + * |[ * g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three"); - * + * ]| * * 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 591dcf396..79849f0f3 100644 --- a/glib/gvariant.c +++ b/glib/gvariant.c @@ -1103,8 +1103,8 @@ g_variant_lookup_value (GVariant *dictionary, * Memory. * * In particular, arrays of these fixed-sized types can be interpreted - * as an array of the given C type, with @element_size set to - * sizeof the appropriate type: + * as an array of the given C type, with @element_size set to the size + * the appropriate type: * * * @@ -1121,16 +1121,16 @@ g_variant_lookup_value (GVariant *dictionary, * * * - * 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. + * 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. * - * - * Iterating with g_variant_iter_next_value() - * - * /* 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); * } * } - * - * + * ]| * * 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 GVariant - * Format Strings. - * - * - * Memory management with g_variant_iter_next() - * - * /* 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); * } * } - * - * + * ]| * * 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 * GVariant Format Strings. * * 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 GVariant - * Format Strings. - * - * - * Memory management with g_variant_iter_loop() - * - * /* 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 + * */ * } * } - * - * + * ]| * * 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 * GVariant Format Strings. * * Returns: %TRUE if a value was unpacked, or %FALSE if there was no diff --git a/glib/gversion.c b/glib/gversion.c index e8d71b89d..d1c30bf62 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. - * - * - * Checking the version of the GLib library - * - * if (!GLIB_CHECK_VERSION (1, 2, 0)) - * g_error ("GLib version 1.2.0 or above is needed"); - * - * - * - * 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 a18fcfb12..258f996e0 100644 --- a/gobject/gobject.c +++ b/gobject/gobject.c @@ -57,11 +57,11 @@ * container = create_container (); * container_add_child (container, create_child()); * ]| - * If container_add_child() will g_object_ref_sink() 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: + * 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(). * - * - * Using g_object_get(<!-- -->) - * 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: - * + * 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); - * - * + * ]| */ void g_object_get (gpointer _object, diff --git a/gobject/gtype.c b/gobject/gtype.c index d729da651..1df9cc52e 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. * - * - * g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))); - * + * 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