From: Matthias Clasen Date: Sat, 8 Feb 2014 17:26:56 +0000 (-0500) Subject: Eradicate links and xrefs X-Git-Tag: 2.39.90~51 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=e7fd3de86d6004d8dba5f8448eb063c6731546e9;p=platform%2Fupstream%2Fglib.git Eradicate links and xrefs These are all replaced by markdown ref links. --- diff --git a/gio/gapplication.c b/gio/gapplication.c index 08b24ab..b12d222 100644 --- a/gio/gapplication.c +++ b/gio/gapplication.c @@ -2010,7 +2010,8 @@ g_application_open (GApplication *application, * and override local_command_line(). In this case, you most likely want * to return %TRUE from your local_command_line() implementation to * suppress the default handling. See - * for an example. + * [gapplication-example-cmdline2.c][gapplication-example-cmdline2] + * for an example. * * If, after the above is done, the use count of the application is zero * then the exit status is returned immediately. If the use count is diff --git a/gio/gapplicationcommandline.c b/gio/gapplicationcommandline.c index 54f9787..9b5d174 100644 --- a/gio/gapplicationcommandline.c +++ b/gio/gapplicationcommandline.c @@ -57,7 +57,8 @@ * The GApplicationCommandLine object can provide the @argc and @argv * parameters for use with the #GOptionContext command-line parsing API, * with the g_application_command_line_get_arguments() function. See - * for an example. + * [gapplication-example-cmdline3.c][gapplication-example-cmdline3] + * for an example. * * The exit status of the originally-invoked process may be set and * messages can be printed to stdout or stderr of that process. The diff --git a/gio/gasyncinitable.c b/gio/gasyncinitable.c index 83bb78e..259057a 100644 --- a/gio/gasyncinitable.c +++ b/gio/gasyncinitable.c @@ -156,8 +156,7 @@ g_async_initable_default_init (GAsyncInitableInterface *iface) /** * g_async_initable_init_async: * @initable: a #GAsyncInitable. - * @io_priority: the I/O priority - * of the operation. + * @io_priority: the [I/O priority][io-priority] of the operation * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to callback function @@ -304,8 +303,7 @@ g_async_initable_real_init_finish (GAsyncInitable *initable, /** * g_async_initable_new_async: * @object_type: a #GType supporting #GAsyncInitable. - * @io_priority: the I/O priority - * of the operation. + * @io_priority: the [I/O priority][io-priority] of the operation * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback to call when the initialization is * finished @@ -348,8 +346,7 @@ g_async_initable_new_async (GType object_type, * @object_type: a #GType supporting #GAsyncInitable. * @n_parameters: the number of parameters in @parameters * @parameters: the parameters to use to construct the object - * @io_priority: the I/O priority - * of the operation. + * @io_priority: the [I/O priority][io-priority] of the operation * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback to call when the initialization is * finished @@ -390,8 +387,7 @@ g_async_initable_newv_async (GType object_type, * @first_property_name: the name of the first property, followed by * the value, and other property value pairs, and ended by %NULL. * @var_args: The var args list generated from @first_property_name. - * @io_priority: the I/O priority - * of the operation. + * @io_priority: the [I/O priority][io-priority] of the operation * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback to call when the initialization is * finished diff --git a/gio/gbufferedinputstream.c b/gio/gbufferedinputstream.c index 6b9829d..3b147d4 100644 --- a/gio/gbufferedinputstream.c +++ b/gio/gbufferedinputstream.c @@ -454,8 +454,7 @@ async_fill_callback_wrapper (GObject *source_object, * g_buffered_input_stream_fill_async: * @stream: a #GBufferedInputStream * @count: the number of bytes that will be read from the stream - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object * @callback: (scope async): a #GAsyncReadyCallback * @user_data: (closure): a #gpointer diff --git a/gio/gdatainputstream.c b/gio/gdatainputstream.c index 0a125a8..6ebb7f3 100644 --- a/gio/gdatainputstream.c +++ b/gio/gdatainputstream.c @@ -1114,8 +1114,7 @@ g_data_input_stream_read_finish (GDataInputStream *stream, /** * g_data_input_stream_read_line_async: * @stream: a given #GDataInputStream. - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied. * @user_data: (closure): the data to pass to callback function. @@ -1147,8 +1146,7 @@ g_data_input_stream_read_line_async (GDataInputStream *stream, * g_data_input_stream_read_until_async: * @stream: a given #GDataInputStream. * @stop_chars: characters to terminate the read. - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied. * @user_data: (closure): the data to pass to callback function. @@ -1387,8 +1385,7 @@ g_data_input_stream_read_upto (GDataInputStream *stream, * @stop_chars: characters to terminate the read * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is * nul-terminated - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function diff --git a/gio/gdbusactiongroup.c b/gio/gdbusactiongroup.c index 65bff2c..57454ed 100644 --- a/gio/gdbusactiongroup.c +++ b/gio/gdbusactiongroup.c @@ -31,7 +31,7 @@ * @title: GDBusActionGroup * @short_description: A D-Bus GActionGroup implementation * @include: gio/gio.h - * @see_also: GActionGroup exporter + * @see_also: [GActionGroup exporter][gio-GActionGroup-exporter] * * #GDBusActionGroup is an implementation of the #GActionGroup * interface that can be used as a proxy for an action group diff --git a/gio/gdbusaddress.c b/gio/gdbusaddress.c index 349e1b7..aaab165 100644 --- a/gio/gdbusaddress.c +++ b/gio/gdbusaddress.c @@ -60,7 +60,7 @@ * * Routines for working with D-Bus addresses. A D-Bus address is a string * like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses - * is explained in detail in the D-Bus specification. + * is explained in detail in the [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#addresses). */ static gchar *get_session_address_platform_specific (GError **error); diff --git a/gio/gdbusconnection.c b/gio/gdbusconnection.c index 7e2d9af..b0c295e 100644 --- a/gio/gdbusconnection.c +++ b/gio/gdbusconnection.c @@ -1226,9 +1226,9 @@ flush_in_thread_func (GSimpleAsyncResult *res, * been sent to the networking buffers in the OS kernel. * * This is an asynchronous method. When the operation is finished, - * @callback will be invoked in the thread-default main - * loop of the thread you are calling this method from. You can + * @callback will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this method from. You can * then call g_dbus_connection_flush_finish() to get the result of the * operation. See g_dbus_connection_flush_sync() for the synchronous * version. @@ -1430,14 +1430,14 @@ schedule_closed_unlocked (GDBusConnection *connection, * %G_IO_ERROR_CLOSED. * * When @connection has been closed, the #GDBusConnection::closed - * signal is emitted in the thread-default main - * loop of the thread that @connection was constructed in. + * signal is emitted in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread that @connection was constructed in. * * This is an asynchronous method. When the operation is finished, - * @callback will be invoked in the thread-default main - * loop of the thread you are calling this method from. You can + * @callback will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this method from. You can * then call g_dbus_connection_close_finish() to get the result of the * operation. See g_dbus_connection_close_sync() for the synchronous * version. @@ -1731,9 +1731,9 @@ g_dbus_connection_send_message_unlocked (GDBusConnection *connection, * %G_IO_ERROR_CLOSED. If @message is not well-formed, * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. * - * See and for an example of how to use this - * low-level API to send and receive UNIX file descriptors. + * See this [server][gdbus-server] and [client][gdbus-unix-fd-client] + * for an example of how to use this low-level API to send and receive + * UNIX file descriptors. * * Note that @message must be unlocked, unless @flags contain the * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. @@ -2050,8 +2050,9 @@ g_dbus_connection_send_message_with_reply_unlocked (GDBusConnection *connect * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed, * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. * - * This is an asynchronous method. When the operation is finished, @callback will be invoked - * in the thread-default main loop + * This is an asynchronous method. When the operation is finished, @callback + * will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] * of the thread you are calling this method from. You can then call * g_dbus_connection_send_message_with_reply_finish() to get the result of the operation. * See g_dbus_connection_send_message_with_reply_sync() for the synchronous version. @@ -2059,9 +2060,9 @@ g_dbus_connection_send_message_with_reply_unlocked (GDBusConnection *connect * Note that @message must be unlocked, unless @flags contain the * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. * - * See and for an example of how to use this - * low-level API to send and receive UNIX file descriptors. + * See this [server][gdbus-server] and [client][gdbus-unix-fd-client] + * for an example of how to use this low-level API to send and receive + * UNIX file descriptors. * * Since: 2.26 */ @@ -2106,9 +2107,9 @@ g_dbus_connection_send_message_with_reply (GDBusConnection *connection, * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use * g_dbus_message_to_gerror() to transcode this to a #GError. * - * See and for an example of how to use this - * low-level API to send and receive UNIX file descriptors. + * See this [server][gdbus-server] and [client][gdbus-unix-fd-client] + * for an example of how to use this low-level API to send and receive + * UNIX file descriptors. * * Returns: (transfer full): a locked #GDBusMessage or %NULL if @error is set * @@ -2192,9 +2193,9 @@ send_message_with_reply_sync_cb (GDBusConnection *connection, * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use * g_dbus_message_to_gerror() to transcode this to a #GError. * - * See and for an example of how to use this - * low-level API to send and receive UNIX file descriptors. + * See this [server][gdbus-server] and [client][gdbus-unix-fd-client] + * for an example of how to use this low-level API to send and receive + * UNIX file descriptors. * * Note that @message must be unlocked, unless @flags contain the * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. @@ -3416,11 +3417,10 @@ is_signal_data_for_name_lost_or_acquired (SignalData *signal_data) * @user_data_free_func: (allow-none): function to free @user_data with when * subscription is removed or %NULL * - * Subscribes to signals on @connection and invokes @callback with a - * whenever the signal is received. Note that @callback will be invoked - * in the thread-default main - * loop of the thread you are calling this method from. + * Subscribes to signals on @connection and invokes @callback with a whenever + * the signal is received. Note that @callback will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this method from. * * If @connection is not a message bus connection, @sender must be * %NULL. @@ -5091,9 +5091,10 @@ obj_message_func (GDBusConnection *connection, * Registers callbacks for exported objects at @object_path with the * D-Bus interface that is described in @interface_info. * - * Calls to functions in @vtable (and @user_data_free_func) will - * happen in the thread-default main - * loop of the thread you are calling this method from. + * Calls to functions in @vtable (and @user_data_free_func) will happen + * in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this method from. * * Note that all #GVariant values passed to functions in @vtable will match * the signature given in @interface_info - if a remote caller passes @@ -5124,7 +5125,7 @@ obj_message_func (GDBusConnection *connection, * reference count is -1, see g_dbus_interface_info_ref()) for as long * as the object is exported. Also note that @vtable will be copied. * - * See for an example of how to use this method. + * See this [server][gdbus-server] for an example of how to use this method. * * Returns: 0 if @error is set, otherwise a registration id (never 0) * that can be used with g_dbus_connection_unregister_object() @@ -5811,8 +5812,9 @@ g_dbus_connection_call_sync_internal (GDBusConnection *connection, * NULL); * ]| * - * This is an asynchronous method. When the operation is finished, @callback will be invoked - * in the thread-default main loop + * This is an asynchronous method. When the operation is finished, + * @callback will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] * of the thread you are calling this method from. You can then call * g_dbus_connection_call_finish() to get the result of the operation. * See g_dbus_connection_call_sync() for the synchronous version of this @@ -6522,9 +6524,9 @@ subtree_message_func (GDBusConnection *connection, * #gpointer will be used to call into the interface vtable for processing * the request. * - * All calls into user-provided code will be invoked in the thread-default main - * loop of the thread you are calling this method from. + * All calls into user-provided code will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this method from. * * If an existing subtree is already registered at @object_path or * then @error is set to #G_IO_ERROR_EXISTS. @@ -6539,7 +6541,8 @@ subtree_message_func (GDBusConnection *connection, * Note that @vtable will be copied so you cannot change it after * registration. * - * See for an example of how to use this method. + * See this [server][gdbus-subtree-server] for an example of how to use + * this method. * * Returns: 0 if @error is set, otherwise a subtree registration id (never 0) * that can be used with g_dbus_connection_unregister_subtree() . diff --git a/gio/gdbusinterfaceskeleton.c b/gio/gdbusinterfaceskeleton.c index d52ba43..0070e8b 100644 --- a/gio/gdbusinterfaceskeleton.c +++ b/gio/gdbusinterfaceskeleton.c @@ -357,7 +357,9 @@ g_dbus_interface_skeleton_get_vtable (GDBusInterfaceSkeleton *interface_) * * Gets all D-Bus properties for @interface_. * - * Returns: (transfer full): A #GVariant of type 'a{sv}'. Free with g_variant_unref(). + * Returns: (transfer full): A #GVariant of type + * ['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. + * Free with g_variant_unref(). * * Since: 2.30 */ diff --git a/gio/gdbusintrospection.c b/gio/gdbusintrospection.c index fc6b374..0623461 100644 --- a/gio/gdbusintrospection.c +++ b/gio/gdbusintrospection.c @@ -1760,7 +1760,7 @@ parser_error (GMarkupParseContext *context, * <node> element. * * Note that this routine is using a - * GMarkup-based + * [GMarkup][glib-Simple-XML-Subset-Parser.description]-based * parser that only accepts a subset of valid XML documents. * * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free diff --git a/gio/gdbusmenumodel.c b/gio/gdbusmenumodel.c index 95cad80..29f2e25 100644 --- a/gio/gdbusmenumodel.c +++ b/gio/gdbusmenumodel.c @@ -30,7 +30,7 @@ * @title: GDBusMenuModel * @short_description: A D-Bus GMenuModel implementation * @include: gio/gio.h - * @see_also: GMenuModel Exporter + * @see_also: [GMenuModel Exporter][gio-GMenuModel-exporter] * * #GDBusMenuModel is an implementation of #GMenuModel that can be used * as a proxy for a menu model that is exported over D-Bus with diff --git a/gio/gdbusmethodinvocation.c b/gio/gdbusmethodinvocation.c index 66abac5..5bd850b 100644 --- a/gio/gdbusmethodinvocation.c +++ b/gio/gdbusmethodinvocation.c @@ -272,9 +272,9 @@ g_dbus_method_invocation_get_connection (GDBusMethodInvocation *invocation) * descriptor passing, that cannot be properly expressed in the * #GVariant API. * - * See and for an example of how to use this - * low-level API to send and receive UNIX file descriptors. + * See this [server][gdbus-server] and [client][gdbus-unix-fd-client] + * for an example of how to use this low-level API to send and receive + * UNIX file descriptors. * * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation. * diff --git a/gio/gdbusnameowning.c b/gio/gdbusnameowning.c index 6ed1174..4d30415 100644 --- a/gio/gdbusnameowning.c +++ b/gio/gdbusnameowning.c @@ -563,9 +563,9 @@ g_bus_own_name_on_connection (GDBusConnection *connection, * * Starts acquiring @name on the bus specified by @bus_type and calls * @name_acquired_handler and @name_lost_handler when the name is - * acquired respectively lost. Callbacks will be invoked in the thread-default main - * loop of the thread you are calling this function from. + * acquired respectively lost. Callbacks will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this function from. * * You are guaranteed that one of the @name_acquired_handler and @name_lost_handler * callbacks will be invoked after calling this function - there are three @@ -607,7 +607,7 @@ g_bus_own_name_on_connection (GDBusConnection *connection, * before @name is requested from the bus. * * This behavior makes it very simple to write applications that wants - * to own names and export objects, see . + * to [own names][gdbus-owning-names] and export objects. * Simply register objects to be exported in @bus_acquired_handler and * unregister the objects (if any) in @name_lost_handler. * diff --git a/gio/gdbusnamewatching.c b/gio/gdbusnamewatching.c index f7da5dd..72a191d 100644 --- a/gio/gdbusnamewatching.c +++ b/gio/gdbusnamewatching.c @@ -511,9 +511,9 @@ connection_get_cb (GObject *source_object, * Starts watching @name on the bus specified by @bus_type and calls * @name_appeared_handler and @name_vanished_handler when the name is * known to have a owner respectively known to lose its - * owner. Callbacks will be invoked in the thread-default main - * loop of the thread you are calling this function from. + * owner. Callbacks will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this function from. * * You are guaranteed that one of the handlers will be invoked after * calling this function. When you are done watching the name, just @@ -532,11 +532,11 @@ connection_get_cb (GObject *source_object, * guaranteed that the next time one of the handlers is invoked, it * will be @name_vanished_handler. The reverse is also true. * - * This behavior makes it very simple to write applications that wants - * to take action when a certain name exists, see . Basically, the application - * should create object proxies in @name_appeared_handler and destroy - * them again (if any) in @name_vanished_handler. + * This behavior makes it very simple to write applications that want + * to take action when a certain [name exists][gdbus-watching-names]. + * Basically, the application should create object proxies in + * @name_appeared_handler and destroy them again (if any) in + * @name_vanished_handler. * * Returns: An identifier (never 0) that an be used with * g_bus_unwatch_name() to stop watching the name. diff --git a/gio/gdbusobjectmanagerclient.c b/gio/gdbusobjectmanagerclient.c index 2b5bd60..2165548 100644 --- a/gio/gdbusobjectmanagerclient.c +++ b/gio/gdbusobjectmanagerclient.c @@ -112,7 +112,7 @@ * #GDBusObjectManagerClient::interface-proxy-signal. * * Note that all callbacks and signals are emitted in the - * thread-default main loop + * [thread-default main context][g-main-context-push-thread-default] * that the #GDBusObjectManagerClient object was constructed * in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects * originating from the #GDBusObjectManagerClient object will be created in @@ -505,7 +505,7 @@ g_dbus_object_manager_client_class_init (GDBusObjectManagerClientClass *klass) * connect signals to all interface proxies managed by @manager. * * This signal is emitted in the - * thread-default main loop + * [thread-default main context][g-main-context-push-thread-default] * that @manager was constructed in. * * Since: 2.30 @@ -543,7 +543,7 @@ g_dbus_object_manager_client_class_init (GDBusObjectManagerClientClass *klass) * connect signals to all interface proxies managed by @manager. * * This signal is emitted in the - * thread-default main loop + * [thread-default main context][g-main-context-push-thread-default] * that @manager was constructed in. * * Since: 2.30 @@ -654,7 +654,7 @@ g_dbus_object_manager_client_new_sync (GDBusConnection *connection * * This is an asynchronous failable constructor. When the result is * ready, @callback will be invoked in the - * thread-default main loop + * [thread-default main context][g-main-context-push-thread-default] * of the thread you are calling this method from. You can * then call g_dbus_object_manager_client_new_finish() to get the result. See * g_dbus_object_manager_client_new_sync() for the synchronous version. @@ -807,7 +807,7 @@ g_dbus_object_manager_client_new_for_bus_sync (GBusType bu * * This is an asynchronous failable constructor. When the result is * ready, @callback will be invoked in the - * thread-default main loop + * [thread-default main loop][g-main-context-push-thread-default] * of the thread you are calling this method from. You can * then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See * g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version. diff --git a/gio/gdbusproxy.c b/gio/gdbusproxy.c index 7cbdc7b..0195c67 100644 --- a/gio/gdbusproxy.c +++ b/gio/gdbusproxy.c @@ -72,17 +72,16 @@ * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set). * * The generic #GDBusProxy::g-properties-changed and - * #GDBusProxy::g-signal signals are not very convenient to work - * with. Therefore, the recommended way of working with proxies is to - * subclass #GDBusProxy, and have more natural properties and signals - * in your derived class. See - * for how this can easily be done using the - * gdbus-codegen tool. + * #GDBusProxy::g-signal signals are not very convenient to work with. + * Therefore, the recommended way of working with proxies is to subclass + * #GDBusProxy, and have more natural properties and signals in your derived + * class. This [example][gdbus-example-gdbus-codegen] shows how this can + * easily be done using the [gdbus-codegen][gdbus-codegen] tool. * * A #GDBusProxy instance can be used from multiple threads but note * that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed * and #GObject::notify) are emitted in the - * thread-default main loop + * [thread-default main context][g-main-context-push-thread-default] * of the thread where the instance was constructed. * * GDBusProxy for a well-known-nameFIXME: MISSING XINCLUDE CONTENT @@ -2042,7 +2041,7 @@ initable_iface_init (GInitableIface *initable_iface) * * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor. * - * See for an example of how #GDBusProxy can be used. + * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. * * Since: 2.26 */ @@ -2136,7 +2135,7 @@ g_dbus_proxy_new_finish (GAsyncResult *res, * This is a synchronous failable constructor. See g_dbus_proxy_new() * and g_dbus_proxy_new_finish() for the asynchronous version. * - * See for an example of how #GDBusProxy can be used. + * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. * * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). * @@ -2192,7 +2191,7 @@ g_dbus_proxy_new_sync (GDBusConnection *connection, * * Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection. * - * See for an example of how #GDBusProxy can be used. + * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. * * Since: 2.26 */ @@ -2257,7 +2256,7 @@ g_dbus_proxy_new_for_bus_finish (GAsyncResult *res, * * Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. * - * See for an example of how #GDBusProxy can be used. + * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. * * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). * @@ -2984,7 +2983,7 @@ g_dbus_proxy_call_sync_internal (GDBusProxy *proxy, * * This is an asynchronous method. When the operation is finished, * @callback will be invoked in the - * thread-default main loop + * [thread-default main context][g-main-context-push-thread-default] * of the thread you are calling this method from. * You can then call g_dbus_proxy_call_finish() to get the result of * the operation. See g_dbus_proxy_call_sync() for the synchronous diff --git a/gio/gdbusserver.c b/gio/gdbusserver.c index c18d86d..12dedcf 100644 --- a/gio/gdbusserver.c +++ b/gio/gdbusserver.c @@ -404,9 +404,9 @@ g_dbus_server_class_init (GDBusServerClass *klass) * * If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD * then the signal is emitted in a new thread dedicated to the - * connection. Otherwise the signal is emitted in the thread-default main - * loop of the thread that @server was constructed in. + * connection. Otherwise the signal is emitted in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread that @server was constructed in. * * You are guaranteed that signal handlers for this signal runs * before incoming messages on @connection are processed. This means @@ -463,8 +463,7 @@ on_run (GSocketService *service, * The returned #GDBusServer isn't active - you have to start it with * g_dbus_server_start(). * - * See for how #GDBusServer can - * be used. + * #GDBusServer is used in this [example][gdbus-peer-to-peer]. * * This is a synchronous failable constructor. See * g_dbus_server_new() for the asynchronous version. diff --git a/gio/gdbusutils.c b/gio/gdbusutils.c index aa92e8d..254ed04 100644 --- a/gio/gdbusutils.c +++ b/gio/gdbusutils.c @@ -515,39 +515,64 @@ g_dbus_gvariant_to_gvalue (GVariant *value, * * * #G_TYPE_STRING - * 's', 'o', 'g' or 'ay' + * + * ['s'][G-VARIANT-TYPE-STRING:CAPS], + * ['o'][G-VARIANT-TYPE-OBJECT-PATH:CAPS], + * ['g'][G-VARIANT-TYPE-SIGNATURE:CAPS] or + * ['ay'][G-VARIANT-TYPE-BYTESTRING:CAPS] + * * * * #G_TYPE_STRV - * 'as', 'ao' or 'aay' + * + * ['as'][G-VARIANT-TYPE-STRING-ARRAY:CAPS], + * ['ao'][G-VARIANT-TYPE-OBJECT-PATH-ARRAY:CAPS] or + * ['aay'][G-VARIANT-TYPE-BYTESTRING-ARRAY:CAPS] + * * * * #G_TYPE_BOOLEAN - * 'b' + * + * ['b'][G-VARIANT-TYPE-BOOLEAN:CAPS] + * * * * #G_TYPE_UCHAR - * 'y' + * + * ['y'][G-VARIANT-TYPE-BYTE:CAPS] + * * * * #G_TYPE_INT - * 'i' or 'n' + * + * ['i'][G-VARIANT-TYPE-INT32:CAPS] or + * ['n'][G-VARIANT-TYPE-INT16:CAPS] + * * * * #G_TYPE_UINT - * 'u' or 'q' + * + * ['u'][G-VARIANT-TYPE-UINT32:CAPS] or + * ['q'][G-VARIANT-TYPE-UINT16:CAPS] + * * * * #G_TYPE_INT64 - * 'x' + * + * ['x'][G-VARIANT-TYPE-INT64:CAPS] + * * * * #G_TYPE_UINT64 - * 't' + * + * ['t'][G-VARIANT-TYPE-UINT64:CAPS] + * * * * #G_TYPE_DOUBLE - * 'd' + * + * ['d'][G-VARIANT-TYPE-DOUBLE:CAPS] + * * * * #G_TYPE_VARIANT @@ -557,9 +582,9 @@ g_dbus_gvariant_to_gvalue (GVariant *value, * * * This can fail if e.g. @gvalue is of type #G_TYPE_STRING and @type - * is 'i'. It will - * also fail for any #GType (including e.g. #G_TYPE_OBJECT and - * #G_TYPE_BOXED derived-types) not in the table above. + * is ['i'][G-VARIANT-TYPE-INT32:CAPS]. It will also fail for any #GType + * (including e.g. #G_TYPE_OBJECT and #G_TYPE_BOXED derived-types) not + * in the table above. * * Note that if @gvalue is of type #G_TYPE_VARIANT and its value is * %NULL, the empty #GVariant instance (never %NULL) for @type is diff --git a/gio/gfile.c b/gio/gfile.c index f70bddf..0b7ce29 100644 --- a/gio/gfile.c +++ b/gio/gfile.c @@ -971,8 +971,7 @@ g_file_enumerate_children (GFile *file, * @file: input #GFile * @attributes: an attribute query string * @flags: a set of #GFileQueryInfoFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call when the @@ -1209,8 +1208,7 @@ g_file_query_info (GFile *file, * @file: input #GFile * @attributes: an attribute query string * @flags: a set of #GFileQueryInfoFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call when the @@ -1347,8 +1345,7 @@ g_file_query_filesystem_info (GFile *file, * g_file_query_filesystem_info_async: * @file: input #GFile * @attributes: an attribute query string - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -1470,8 +1467,7 @@ g_file_find_enclosing_mount (GFile *file, /** * g_file_find_enclosing_mount_async: * @file: a #GFile - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -1699,7 +1695,7 @@ g_file_create (GFile *file, /** * g_file_replace: * @file: input #GFile - * @etag: (allow-none): an optional entity tag + * @etag: (allow-none): an optional [entity tag][gfile-etag] * for the current #GFile, or #NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags @@ -1904,7 +1900,7 @@ g_file_create_readwrite (GFile *file, /** * g_file_replace_readwrite: * @file: a #GFile - * @etag: (allow-none): an optional entity tag + * @etag: (allow-none): an optional [entity tag][gfile-etag] * for the current #GFile, or #NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags @@ -1959,8 +1955,7 @@ g_file_replace_readwrite (GFile *file, /** * g_file_read_async: * @file: input #GFile - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -2028,8 +2023,7 @@ g_file_read_finish (GFile *file, * g_file_append_to_async: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -2100,8 +2094,7 @@ g_file_append_to_finish (GFile *file, * g_file_create_async: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -2171,12 +2164,11 @@ g_file_create_finish (GFile *file, /** * g_file_replace_async: * @file: input #GFile - * @etag: (allow-none): an entity tag - * for the current #GFile, or NULL to ignore + * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile, + * or %NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -2250,8 +2242,7 @@ g_file_replace_finish (GFile *file, /** * g_file_open_readwrite_async * @file: input #GFile - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -2323,8 +2314,7 @@ g_file_open_readwrite_finish (GFile *file, * g_file_create_readwrite_async: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -2398,12 +2388,11 @@ g_file_create_readwrite_finish (GFile *file, /** * g_file_replace_readwrite_async: * @file: input #GFile - * @etag: (allow-none): an entity tag - * for the current #GFile, or NULL to ignore + * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile, + * or %NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -3404,8 +3393,7 @@ g_file_copy (GFile *source, * @source: input #GFile * @destination: destination #GFile * @flags: set of #GFileCopyFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @progress_callback: (allow-none): function to callback with progress @@ -3665,8 +3653,7 @@ g_file_make_directory (GFile *file, /** * g_file_make_directory_async: * @file: input #GFile - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: a #GAsyncReadyCallback to call @@ -3915,8 +3902,7 @@ g_file_delete (GFile *file, /** * g_file_delete_async: * @file: input #GFile - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: a #GAsyncReadyCallback to call @@ -4025,8 +4011,7 @@ g_file_trash (GFile *file, /** * g_file_trash_async: * @file: input #GFile - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: a #GAsyncReadyCallback to call @@ -4144,8 +4129,7 @@ g_file_set_display_name (GFile *file, * g_file_set_display_name_async: * @file: input #GFile * @display_name: a string - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -4474,8 +4458,7 @@ g_file_real_set_attributes_from_info (GFile *file, * @file: input #GFile * @info: a #GFileInfo * @flags: a #GFileQueryInfoFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback @@ -7093,11 +7076,11 @@ g_file_load_contents_finish (GFile *file, * @file: input #GFile * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file * @length: the length of @contents in bytes - * @etag: (allow-none): the old entity tag - * for the document, or %NULL + * @etag: (allow-none): the old [entity-tag][gfile-etag] for the document, + * or %NULL * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @new_etag: (allow-none) (out): a location to a new entity tag + * @new_etag: (allow-none) (out): a location to a new [entity tag][gfile-etag] * for the document. This should be freed with g_free() when no longer * needed, or %NULL * @cancellable: optional #GCancellable object, %NULL to ignore @@ -7298,7 +7281,7 @@ replace_contents_open_callback (GObject *obj, * @file: input #GFile * @contents: (element-type guint8) (array length=length): string of contents to replace the file with * @length: the length of @contents in bytes - * @etag: (allow-none): a new entity tag for the @file, or %NULL + * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags * @cancellable: optional #GCancellable object, %NULL to ignore @@ -7348,7 +7331,7 @@ g_file_replace_contents_async (GFile *file, * g_file_replace_contents_bytes_async: * @file: input #GFile * @contents: a #GBytes - * @etag: (allow-none): a new entity tag for the @file, or %NULL + * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags * @cancellable: optional #GCancellable object, %NULL to ignore @@ -7402,7 +7385,7 @@ g_file_replace_contents_bytes_async (GFile *file, * g_file_replace_contents_finish: * @file: input #GFile * @res: a #GAsyncResult - * @new_etag: (out) (allow-none): a location of a new entity tag + * @new_etag: (out) (allow-none): a location of a new [entity tag][gfile-etag] * for the document. This should be freed with g_free() when it is no * longer needed, or %NULL * @error: a #GError, or %NULL @@ -7656,8 +7639,7 @@ g_file_measure_disk_usage (GFile *file, * g_file_measure_disk_usage_async: * @file: a #GFile * @flags: #GFileMeasureFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable * @progress_callback: (allow-none): a #GFileMeasureProgressCallback * @progress_data: user_data for @progress_callback @@ -7986,11 +7968,10 @@ g_file_poll_mountable_finish (GFile *file, * g_file_supports_thread_contexts: * @file: a #GFile * - * Checks if @file supports thread-default - * contexts. If this returns %FALSE, you cannot perform - * asynchronous operations on @file in a thread that has a - * thread-default context. + * Checks if @file supports + * [thread-default contexts][g-main-context-push-thread-default-context]. + * If this returns %FALSE, you cannot perform asynchronous operations on + * @file in a thread that has a thread-default context. * * Returns: Whether or not @file supports thread-default contexts. * diff --git a/gio/gfileattribute.c b/gio/gfileattribute.c index 426143b..e09eba1 100644 --- a/gio/gfileattribute.c +++ b/gio/gfileattribute.c @@ -66,9 +66,9 @@ * "standard"The "Standard" namespace. General file * information that any application may need should be put in this namespace. * Examples include the file's name, type, and size. - * "etag"The "Entity Tag" - * namespace. Currently, the only key in this namespace is "value", which contains - * the value of the current entity tag. + * "etag"The [Entity Tag][gfile-etag] + * namespace. Currently, the only key in this namespace is "value", which + * contains the value of the current entity tag. * "id"The "Identification" namespace. This * namespace is used by file managers and applications that list directories * to check for loops and to uniquely identify files. diff --git a/gio/gfileenumerator.c b/gio/gfileenumerator.c index 3b05782..53783c8 100644 --- a/gio/gfileenumerator.c +++ b/gio/gfileenumerator.c @@ -309,8 +309,7 @@ next_async_callback_wrapper (GObject *source_object, * g_file_enumerator_next_files_async: * @enumerator: a #GFileEnumerator. * @num_files: the number of file info objects to request - * @io_priority: the io priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -436,8 +435,7 @@ close_async_callback_wrapper (GObject *source_object, /** * g_file_enumerator_close_async: * @enumerator: a #GFileEnumerator. - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function diff --git a/gio/gfileinfo.c b/gio/gfileinfo.c index 9ded53b..e3578e5 100644 --- a/gio/gfileinfo.c +++ b/gio/gfileinfo.c @@ -22,14 +22,14 @@ * SECTION:gfileinfo * @short_description: File Information and Attributes * @include: gio/gio.h - * @see_also: #GFile, GFileAttribute + * @see_also: #GFile, [GFileAttribute][gio-GFileAttribute] * * Functionality for manipulating basic metadata for files. #GFileInfo * implements methods for getting information that all files should * contain, and allows for manipulation of extended attributes. * - * See GFileAttribute for more - * information on how GIO handles file attributes. + * See [GFileAttribute][gio-GFileAttribute for more information on how + * GIO handles file attributes. * * To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its * async variant). To obtain a #GFileInfo for a file input or output @@ -364,7 +364,7 @@ g_file_info_new (void) * @src_info: source to copy attributes from. * @dest_info: destination to copy attributes to. * - * Copies all of the GFileAttributes + * Copies all of the [GFileAttribute][gio-GFileAttribute] * from @src_info to @dest_info. **/ void @@ -1795,7 +1795,7 @@ g_file_info_get_symlink_target (GFileInfo *info) * g_file_info_get_etag: * @info: a #GFileInfo. * - * Gets the entity tag for a given + * Gets the [entity tag][gfile-etag] for a given * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE. * * Returns: a string containing the value of the "etag:value" attribute. @@ -2050,7 +2050,7 @@ g_file_info_set_symbolic_icon (GFileInfo *info, /** * g_file_info_set_content_type: * @info: a #GFileInfo. - * @content_type: a content type. See GContentType. + * @content_type: a content type. See [GContentType][gio-GContentType] * * Sets the content type attribute for a given #GFileInfo. * See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE. diff --git a/gio/gfileinputstream.c b/gio/gfileinputstream.c index fb7a42e..41014d4 100644 --- a/gio/gfileinputstream.c +++ b/gio/gfileinputstream.c @@ -173,8 +173,7 @@ async_ready_callback_wrapper (GObject *source_object, * g_file_input_stream_query_info_async: * @stream: a #GFileInputStream. * @attributes: a file attribute query string. - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function diff --git a/gio/gfileiostream.c b/gio/gfileiostream.c index d3cc55c..87c424a 100644 --- a/gio/gfileiostream.c +++ b/gio/gfileiostream.c @@ -191,8 +191,7 @@ async_ready_callback_wrapper (GObject *source_object, * g_file_io_stream_query_info_async: * @stream: a #GFileIOStream. * @attributes: a file attribute query string. - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][gio-GIOScheduler] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function diff --git a/gio/gfilemonitor.c b/gio/gfilemonitor.c index b63a230..136006f 100644 --- a/gio/gfilemonitor.c +++ b/gio/gfilemonitor.c @@ -45,9 +45,9 @@ static void file_change_free (FileChange *change); * * To get informed about changes to the file or directory you are * monitoring, connect to the #GFileMonitor::changed signal. The - * signal will be emitted in the thread-default main - * context of the thread that the monitor was created in + * signal will be emitted in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread that the monitor was created in * (though if the global default main context is blocked, this may * cause notifications to be blocked even if the thread-default * context is still running). @@ -670,9 +670,8 @@ update_rate_limiter_timeout (GFileMonitor *monitor, * has taken place. Should be called from file monitor * implementations only. * - * The signal will be emitted from an idle handler (in the thread-default main - * context). + * The signal will be emitted from an idle handler (in the + * [thread-default main context][g-main-context-push-thread-default]). **/ void g_file_monitor_emit_event (GFileMonitor *monitor, diff --git a/gio/gfileoutputstream.c b/gio/gfileoutputstream.c index 56fd66a..2754405 100644 --- a/gio/gfileoutputstream.c +++ b/gio/gfileoutputstream.c @@ -188,8 +188,7 @@ async_ready_callback_wrapper (GObject *source_object, * g_file_output_stream_query_info_async: * @stream: a #GFileOutputStream. * @attributes: a file attribute query string. - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][gio-GIOScheduler] of the request * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: callback to call when the request is satisfied * @user_data: the data to pass to callback function diff --git a/gio/ginitable.c b/gio/ginitable.c index f64f634..38f46e7 100644 --- a/gio/ginitable.c +++ b/gio/ginitable.c @@ -85,8 +85,7 @@ g_initable_default_init (GInitableInterface *iface) * If the object is not initialized, or initialization returns with an * error, then all operations on the object except g_object_ref() and * g_object_unref() are considered to be invalid, and have undefined - * behaviour. See the section introduction - * for more details. + * behaviour. See the [introduction][ginitable] for more details. * * Implementations of this method must be idempotent, i.e. multiple calls * to this function with the same argument should return the same results. diff --git a/gio/ginputstream.c b/gio/ginputstream.c index 116457d..f728285 100644 --- a/gio/ginputstream.c +++ b/gio/ginputstream.c @@ -539,7 +539,7 @@ async_ready_close_callback_wrapper (GObject *source_object, * @buffer: (array length=count) (element-type guint8): a buffer to * read data into (which should be at least count bytes long). * @count: the number of bytes that will be read from the stream - * @io_priority: the I/O priority + * @io_priority: the [I/O priority][io-priority] * of the request. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied @@ -686,8 +686,7 @@ read_bytes_callback (GObject *stream, * g_input_stream_read_bytes_async: * @stream: A #GInputStream. * @count: the number of bytes that will be read from the stream - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -759,8 +758,7 @@ g_input_stream_read_bytes_finish (GInputStream *stream, * g_input_stream_skip_async: * @stream: A #GInputStream. * @count: the number of bytes that will be skipped from the stream - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -871,8 +869,7 @@ g_input_stream_skip_finish (GInputStream *stream, /** * g_input_stream_close_async: * @stream: A #GInputStream. - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional cancellable object * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function diff --git a/gio/giomodule.c b/gio/giomodule.c index 39989f3..5876fc5 100644 --- a/gio/giomodule.c +++ b/gio/giomodule.c @@ -60,7 +60,7 @@ * SECTION:extensionpoints * @short_description: Extension Points * @include: gio.h - * @see_also: Extending GIO + * @see_also: [Extending GIO][extending-gio] * * #GIOExtensionPoint provides a mechanism for modules to extend the * functionality of the library or application that loaded it in an @@ -102,7 +102,7 @@ * * To avoid opening all modules just to find out what extension * points they implement, GIO makes use of a caching mechanism, - * see gio-querymodules. + * see [gio-querymodules][gio-querymodules]. * You are expected to run this command after installing a * GIO module. * diff --git a/gio/gioscheduler.c b/gio/gioscheduler.c index 97c4bd2..49027cb 100644 --- a/gio/gioscheduler.c +++ b/gio/gioscheduler.c @@ -95,7 +95,7 @@ io_job_thread (GTask *task, * @job_func: a #GIOSchedulerJobFunc. * @user_data: data to pass to @job_func * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL - * @io_priority: the I/O priority + * @io_priority: the [I/O priority][io-priority] * of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * diff --git a/gio/gmenumodel.c b/gio/gmenumodel.c index 61be14c..a20f60b 100644 --- a/gio/gmenumodel.c +++ b/gio/gmenumodel.c @@ -43,8 +43,7 @@ * it (or, in the case of the 'root' menu, is defined by the context * in which it is used). * - * As an example, consider the visible portions of the menu in - * . + * As an example, consider the visible portions of this menu: * * ## An example menu # {#menu-example} * @@ -62,7 +61,7 @@ * - the Sources section (containing 2 items) * - the Markup section (containing 2 items) * - * illustrates the conceptual connection between + * The [example][menu-model] illustrates the conceptual connection between * these 8 menus. Each large block in the figure represents a menu and the * smaller blocks within the large block represent items in that menu. Some * items contain references to other menus. @@ -71,8 +70,8 @@ * * ![](menu-model.png) * - * Notice that the separators visible in - * appear nowhere in . This is because + * Notice that the separators visible in the [example][menu-example] + * appear nowhere in the [menu model][menu-model]. This is because * separators are not explicitly represented in the menu model. Instead, * a separator is inserted between any two non-empty sections of a menu. * Section items can have labels just like any other item. In that case, @@ -83,12 +82,10 @@ * outside the application. Examples include global menus, jumplists, * dash boards, etc. To support such uses, it is necessary to 'export' * information about actions and their representation in menus, which - * is exactly what the - * GActionGroup exporter - * and the - * GMenuModel exporter - * do for #GActionGroup and #GMenuModel. The client-side counterparts - * to make use of the exported information are #GDBusActionGroup and + * is exactly what the [GActionGroup exporter][gio-GActionGroup-exporter] + * and the [GMenuModel exporter][gio-GMenuModel-exporter] do for + * #GActionGroup and #GMenuModel. The client-side counterparts to + * make use of the exported information are #GDBusActionGroup and * #GDBusMenuModel. * * The API of #GMenuModel is very generic, with iterators for the diff --git a/gio/gresource.c b/gio/gresource.c index 939ef15..ae18b24 100644 --- a/gio/gresource.c +++ b/gio/gresource.c @@ -51,7 +51,7 @@ G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref) * icons, etc. These are often shipped as files in `$datadir/appname`, or * manually included as literal strings in the code. * - * The #GResource API and the glib-compile-resources program + * The #GResource API and the [glib-compile-resources][glib-compile-resources] program * provide a convenient and efficient alternative to this which has some nice properties. You * maintain the files as normal files, so its easy to edit them, but during the build the files * are combined into a binary bundle that is linked into the executable. This means that loading @@ -80,7 +80,7 @@ G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref) * set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will * abort. * - * Resource bundles are created by the glib-compile-resources program + * Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program * 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. * @@ -106,7 +106,7 @@ G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref) * 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. * - * You can then use glib-compile-resources to compile the xml to a + * You can then use [glib-compile-resources][glib-compile-resources] to compile the xml to a * binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and * --generate-header arguments to create a source file and header to link directly into your application. * @@ -955,7 +955,7 @@ register_lazy_static_resources (void) * GStaticResource. * * This is normally used by code generated by - * glib-compile-resources + * [glib-compile-resources][glib-compile-resources] * and is not typically used by other code. * * Since: 2.32 @@ -980,7 +980,7 @@ g_static_resource_init (GStaticResource *static_resource) * Finalized a GResource initialized by g_static_resource_init(). * * This is normally used by code generated by - * glib-compile-resources + * [glib-compile-resources][glib-compile-resources] * and is not typically used by other code. * * Since: 2.32 @@ -1012,7 +1012,7 @@ g_static_resource_fini (GStaticResource *static_resource) * Gets the GResource that was registered by a call to g_static_resource_init(). * * This is normally used by code generated by - * glib-compile-resources + * [glib-compile-resources][glib-compile-resources] * and is not typically used by other code. * * Return value: (transfer none): a #GResource diff --git a/gio/gsettings.c b/gio/gsettings.c index aaf4c21..5e94e69 100644 --- a/gio/gsettings.c +++ b/gio/gsettings.c @@ -91,14 +91,14 @@ * the <key> element. * * GSettings uses schemas in a compact binary form that is created - * by the glib-compile-schemas + * by the [glib-compile-schemas][glib-compile-schemas] * utility. The input is a schema description in an XML format. * * A DTD for the gschema XML format can be found here: * [gschema.dtd](https://git.gnome.org/browse/glib/tree/gio/gschema.dtd) * - * The glib-compile-schemas - * tool expects schema files to have the extension `.gschema.xml`. + * The [glib-compile-schemas][glib-compile-schemas] tool expects schema + * files to have the extension `.gschema.xml`. * * At runtime, schemas are identified by their id (as specified in the * id attribute of the <schema> element). The convention for schema @@ -111,12 +111,11 @@ * * In addition to #GVariant types, keys can have types that have * enumerated types. These can be described by a <choice>, - * <enum> or <flags> element, see - * . The underlying type of - * such a key is string, but you can use g_settings_get_enum(), - * g_settings_set_enum(), g_settings_get_flags(), g_settings_set_flags() - * access the numeric values corresponding to the string value of enum - * and flags keys. + * <enum> or <flags> element, as seen in the + * [example][schema-enumerated]. The underlying type of such a key + * is string, but you can use g_settings_get_enum(), g_settings_set_enum(), + * g_settings_get_flags(), g_settings_set_flags() access the numeric values + * corresponding to the string value of enum and flags keys. * * An example for default value: * |[ @@ -191,11 +190,11 @@ * an application. Sometimes, it is necessary for a vendor or distributor * to adjust these defaults. Since patching the XML source for the schema * is inconvenient and error-prone, - * glib-compile-schemas reads - * so-called 'vendor override' files. These are keyfiles in the same - * 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: + * [glib-compile-schemas][glib-compile-schemas] reads so-called vendor + * override' files. These are keyfiles in the same 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' diff --git a/gio/gsettingsschema.c b/gio/gsettingsschema.c index 85478c8..a3127fa 100644 --- a/gio/gsettingsschema.c +++ b/gio/gsettingsschema.c @@ -251,8 +251,7 @@ g_settings_schema_source_unref (GSettingsSchemaSource *source) * may be useful to authors of plugin management systems. * * The directory should contain a file called `gschemas.compiled` as - * produced by the - * glib-compile-schemas tool. + * produced by the [glib-compile-schemas][glib-compile-schemas] tool. * * If @trusted is %TRUE then `gschemas.compiled` is trusted not to be * corrupted. This assumption has a performance advantage, but can result diff --git a/gio/gsimpleasyncresult.c b/gio/gsimpleasyncresult.c index 406b6e9..aa413a7 100644 --- a/gio/gsimpleasyncresult.c +++ b/gio/gsimpleasyncresult.c @@ -82,9 +82,9 @@ * or it can use #GThreads. * g_simple_async_result_complete() will finish an I/O task directly * from the point where it is called. g_simple_async_result_complete_in_idle() - * will finish it from an idle handler in the thread-default main - * context. g_simple_async_result_run_in_thread() will run the + * will finish it from an idle handler in the + * [thread-default main context][g-main-context-push-thread-default] + * . g_simple_async_result_run_in_thread() will run the * job in a separate thread and then deliver the result to the * thread-default main context. * @@ -784,9 +784,9 @@ complete_in_idle_cb (gpointer data) * g_simple_async_result_complete_in_idle: * @simple: a #GSimpleAsyncResult. * - * Completes an asynchronous function in an idle handler in the thread-default main - * loop of the thread that @simple was initially created in + * Completes an asynchronous function in an idle handler in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread that @simple was initially created in * (and re-pushes that context around the invocation of the callback). * * Calling this function takes a reference to @simple for as long as diff --git a/gio/gsocket.c b/gio/gsocket.c index 7664f61..6c0bcc8 100644 --- a/gio/gsocket.c +++ b/gio/gsocket.c @@ -68,7 +68,7 @@ * SECTION:gsocket * @short_description: Low-level socket object * @include: gio/gio.h - * @see_also: #GInitable, gnetworking.h + * @see_also: #GInitable, [<gnetworking.h>][gio-gnetworking.h] * * A #GSocket is a low-level networking primitive. It is a more or less * direct mapping of the BSD socket API in a portable GObject based API. @@ -4516,7 +4516,7 @@ g_socket_get_credentials (GSocket *socket, * getsockopt(). (If you need to fetch a non-integer-valued option, * you will need to call getsockopt() directly.) * - * The `<gio/gnetworking.h>` + * The [<gio/gnetworking.h>][gio-gnetworking.h] * header pulls in system headers that will define most of the * standard/portable socket options. For unusual socket protocols or * platform-dependent options, you may need to include additional @@ -4583,7 +4583,7 @@ g_socket_get_option (GSocket *socket, * setsockopt(). (If you need to set a non-integer-valued option, * you will need to call setsockopt() directly.) * - * The `<gio/gnetworking.h>` + * The [<gio/gnetworking.h>][gio-gnetworking.h] * header pulls in system headers that will define most of the * standard/portable socket options. For unusual socket protocols or * platform-dependent options, you may need to include additional diff --git a/gio/gsocketservice.c b/gio/gsocketservice.c index 934d60e..0ee0ad0 100644 --- a/gio/gsocketservice.c +++ b/gio/gsocketservice.c @@ -47,9 +47,9 @@ * If you are interested in writing connection handlers that contain * blocking code then see #GThreadedSocketService. * - * The socket service runs on the main loop of the thread-default - * context of the thread it is created in, and is not + * The socket service runs on the main loop of the + * [thread-default context][g-main-context-push-thread-default-context] + * of the thread it is created in, and is not * threadsafe in general. However, the calls to start and stop the * service are thread-safe so these can be used from threads that * handle incoming clients. diff --git a/gio/gtask.c b/gio/gtask.c index 36d4109..62a4440 100644 --- a/gio/gtask.c +++ b/gio/gtask.c @@ -148,14 +148,13 @@ * * #GTask also tries to simplify asynchronous operations that * internally chain together several smaller asynchronous - * operations. g_task_get_cancellable(), g_task_get_context(), and - * g_task_get_priority() allow you to get back the task's - * #GCancellable, #GMainContext, and I/O priority when starting a new - * subtask, so you don't have to keep track of them yourself. - * g_task_attach_source() simplifies the case of waiting for a - * source to fire (automatically using the correct #GMainContext - * and priority). + * operations. g_task_get_cancellable(), g_task_get_context(), + * and g_task_get_priority() allow you to get back the task's + * #GCancellable, #GMainContext, and [I/O priority][io-priority] + * when starting a new subtask, so you don't have to keep track + * of them yourself. g_task_attach_source() simplifies the case + * of waiting for a source to fire (automatically using the correct + * #GMainContext and priority). * * Here is an example for chained asynchronous operations: * |[ @@ -477,7 +476,7 @@ * abuse of g_simple_async_result_set_op_res_gpointer() for the same * purpose with #GSimpleAsyncResult. * - In addition to the task data, #GTask also keeps track of the - * priority, #GCancellable, and + * [priority][io-priority], #GCancellable, and * #GMainContext associated with the task, so tasks that consist of * a chain of simpler asynchronous operations will have easy access * to those values when starting each sub-task. @@ -634,9 +633,8 @@ g_task_finalize (GObject *object) * @callback_data: (closure): user data passed to @callback. * * Creates a #GTask acting on @source_object, which will eventually be - * used to invoke @callback in the current thread-default main - * context. + * used to invoke @callback in the current + * [thread-default main context][g-main-context-push-thread-default]. * * Call this in the "start" method of your asynchronous method, and * pass the #GTask around throughout the asynchronous operation. You @@ -783,8 +781,7 @@ g_task_set_task_data (GTask *task, /** * g_task_set_priority: * @task: the #GTask - * @priority: the priority - * of the request. + * @priority: the [priority][io-priority] of the request * * Sets @task's priority. If you do not call this, it will default to * %G_PRIORITY_DEFAULT. @@ -994,9 +991,9 @@ g_task_get_priority (GTask *task) * @task: a #GTask * * Gets the #GMainContext that @task will return its result in (that - * is, the context that was the thread-default main - * context at the point when @task was created). + * is, the context that was the + * [thread-default main context][g-main-context-push-thread-default] + * at the point when @task was created). * * This will always return a non-%NULL value, even if the task's * context is the default #GMainContext. @@ -1380,9 +1377,8 @@ g_task_run_in_thread_sync (GTask *task, * * A utility function for dealing with async operations where you need * to wait for a #GSource to trigger. Attaches @source to @task's - * #GMainContext with @task's priority, and sets @source's callback - * to @callback, with @task as the callback's `user_data`. + * #GMainContext with @task's [priority][io-priority], and sets @source's + * callback to @callback, with @task as the callback's `user_data`. * * This takes a reference on @task until @source is destroyed. * diff --git a/gio/gtlsconnection.c b/gio/gtlsconnection.c index 1ebf83f..5c8c3df 100644 --- a/gio/gtlsconnection.c +++ b/gio/gtlsconnection.c @@ -771,8 +771,7 @@ g_tls_connection_handshake (GTlsConnection *conn, /** * g_tls_connection_handshake_async: * @conn: a #GTlsConnection - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): a #GCancellable, or %NULL * @callback: callback to call when the handshake is complete * @user_data: the data to pass to the callback function diff --git a/gio/gvolume.c b/gio/gvolume.c index 5e3266c..c25deb7 100644 --- a/gio/gvolume.c +++ b/gio/gvolume.c @@ -562,8 +562,8 @@ g_volume_eject_with_operation_finish (GVolume *volume, * @kind: the kind of identifier to return * * Gets the identifier of the given kind for @volume. - * See the introduction - * for more information about volume identifiers. + * See the [introduction][volume-identifier] for more + * information about volume identifiers. * * Returns: a newly allocated string containing the * requested identfier, or %NULL if the #GVolume @@ -590,9 +590,8 @@ g_volume_get_identifier (GVolume *volume, * g_volume_enumerate_identifiers: * @volume: a #GVolume * - * Gets the kinds of identifiers - * that @volume has. Use g_volume_get_identifier() to obtain - * the identifiers themselves. + * Gets the kinds of [identifiers][volume-identifier] that @volume has. + * Use g_volume_get_identifier() to obtain the identifiers themselves. * * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array * of strings containing kinds of identifiers. Use g_strfreev() to free. diff --git a/gio/gvolumemonitor.c b/gio/gvolumemonitor.c index f4b4009..441afc6 100644 --- a/gio/gvolumemonitor.c +++ b/gio/gvolumemonitor.c @@ -39,10 +39,10 @@ * on the computer. In other words, what a file selector or file manager * would show in a sidebar. * - * #GVolumeMonitor is not thread-default-context - * aware, and so should not be used other than from the main - * thread, with no thread-default-context active. + * #GVolumeMonitor is not + * [thread-default-context aware][g-main-context-push-thread-default], + * and so should not be used other than from the main thread, with no + * thread-default-context active. **/ G_DEFINE_TYPE (GVolumeMonitor, g_volume_monitor, G_TYPE_OBJECT); diff --git a/glib/gcharset.c b/glib/gcharset.c index 7b4208e..c14b8fe 100644 --- a/glib/gcharset.c +++ b/glib/gcharset.c @@ -154,11 +154,10 @@ charset_cache_free (gpointer data) * g_get_charset: * @charset: return location for character set name * - * Obtains the character set for the current - * locale; you might use this character set as an argument to - * g_convert(), to convert from the current locale's encoding to some - * other encoding. (Frequently g_locale_to_utf8() and g_locale_from_utf8() - * are nice shortcuts, though.) + * Obtains the character set for the [current locale][setlocale]; you + * might use this character set as an argument to g_convert(), to convert + * from the current locale's encoding to some other encoding. (Frequently + * g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts, though.) * * On Windows the character set returned by this function is the * so-called system default ANSI code-page. That is the character set diff --git a/glib/gconvert.c b/glib/gconvert.c index 33e7e07..b92fdd8 100644 --- a/glib/gconvert.c +++ b/glib/gconvert.c @@ -104,21 +104,20 @@ * encoding for their strings, and that is also what they use for * the file names they create. However, older file systems may * still contain file names created in "older" encodings, such as - * ISO-8859-1. In this case, for compatibility reasons, you may - * want to instruct Glib to use that particular encoding for file - * names rather than UTF-8. You can do this by specifying the - * encoding for file names in the `G_FILENAME_ENCODING` + * ISO-8859-1. In this case, for compatibility reasons, you may want + * to instruct Glib to use that particular encoding for file names + * rather than UTF-8. You can do this by specifying the encoding for + * file names in the [`G_FILENAME_ENCODING`][G_FILENAME_ENCODING] * environment variable. For example, if your installation uses * ISO-8859-1 for file names, you can put this in your `~/.profile` - * + * |[ * export G_FILENAME_ENCODING=ISO-8859-1 - * + * ]| * Glib provides the functions g_filename_to_utf8() and * g_filename_from_utf8() to perform the necessary conversions. * These functions convert file names from the encoding specified - * in `G_FILENAME_ENCODING` to UTF-8 and vice-versa. - * illustrates how + * in `G_FILENAME_ENCODING` to UTF-8 and vice-versa. This + * [diagram][file-name-encodings-diagram] illustrates how * these functions are used to convert between UTF-8 and the * encoding for file names in the file system. * @@ -885,8 +884,7 @@ strdup_len (const gchar *string, * * Converts a string which is in the encoding used for strings by * the C runtime (usually the same as that used by the operating - * system) in the current locale into a - * UTF-8 string. + * system) in the [current locale][setlocale] into a UTF-8 string. * * Return value: A newly-allocated buffer containing the converted string, * or %NULL on an error, and error will be set. @@ -929,8 +927,8 @@ g_locale_to_utf8 (const gchar *opsysstring, * * Converts a string from UTF-8 to the encoding used for strings by * the C runtime (usually the same as that used by the operating - * system) in the current locale. On - * Windows this means the system codepage. + * system) in the [current locale][setlocale]. On Windows this means + * the system codepage. * * Return value: A newly-allocated buffer containing the converted string, * or %NULL on an error, and error will be set. @@ -986,12 +984,12 @@ filename_charset_cache_free (gpointer data) * * `G_FILENAME_ENCODING` may be set to a comma-separated list of * character set names. The special token "@locale" is taken - * to mean the character set for the current - * locale. If `G_FILENAME_ENCODING` is not set, but - * `G_BROKEN_FILENAMES` is, the character set of the current locale - * is taken as the filename encoding. If neither environment variable - * is set, UTF-8 is taken as the filename encoding, but the character - * set of the current locale is also put in the list of encodings. + * to mean the character set for the [current locale][setlocale]. + * If `G_FILENAME_ENCODING` is not set, but `G_BROKEN_FILENAMES` is, + * the character set of the current locale is taken as the filename + * encoding. If neither environment variable is set, UTF-8 is taken + * as the filename encoding, but the character set of the current locale + * is also put in the list of encodings. * * The returned @charsets belong to GLib and must not be freed. * @@ -1134,7 +1132,7 @@ get_filename_charset (const gchar **filename_charset) * Converts a string which is in the encoding used by GLib for * filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8 * for filenames; on other platforms, this function indirectly depends on - * the current locale. + * the [current locale][setlocale]. * * Return value: The converted string, or %NULL on an error. **/ @@ -1206,7 +1204,7 @@ g_filename_to_utf8 (const gchar *opsysstring, * Converts a string from UTF-8 to the encoding GLib uses for * filenames. Note that on Windows GLib uses UTF-8 for filenames; * on other platforms, this function indirectly depends on the - * current locale. + * [current locale][setlocale]. * * Return value: (array length=bytes_written) (element-type guint8) (transfer full): * The converted string, or %NULL on an error. diff --git a/glib/gdataset.c b/glib/gdataset.c index 92325b7..ec72fec 100644 --- a/glib/gdataset.c +++ b/glib/gdataset.c @@ -121,9 +121,9 @@ /** * GData: * - * The #GData struct is an opaque data structure to represent a Keyed Data List. It should - * only be accessed via the following functions. + * The #GData struct is an opaque data structure to represent a + * [Keyed Data List][glib-Keyed-Data-Lists]. It should only be + * accessed via the following functions. **/ /** diff --git a/glib/gdate.c b/glib/gdate.c index e28b1c7..670f7aa 100644 --- a/glib/gdate.c +++ b/glib/gdate.c @@ -1111,10 +1111,10 @@ g_date_prepare_to_parse (const gchar *str, * @str: string to parse * * Parses a user-inputted string @str, and try to figure out what date it - * represents, taking the current locale - * into account. If the string is successfully parsed, the date will be - * valid after the call. Otherwise, it will be invalid. You should check - * using g_date_valid() to see whether the parsing succeeded. + * represents, taking the [current locale][setlocale] into account. If the + * string is successfully parsed, the date will be valid after the call. + * Otherwise, it will be invalid. You should check using g_date_valid() + * to see whether the parsing succeeded. * * This function is not appropriate for file formats and the like; it * isn't very precise, and its exact behavior varies with the locale. @@ -2424,7 +2424,7 @@ win32_strftime_helper (const GDate *d, * @date: valid #GDate * * Generates a printed representation of the date, in a - * locale-specific way. + * [locale][setlocale]-specific way. * Works just like the platform's C library strftime() function, * but only accepts date-related formats; time-related formats * give undefined results. Date must be valid. Unlike strftime() diff --git a/glib/ghash.c b/glib/ghash.c index 5c5ed2b..74b5c70 100644 --- a/glib/ghash.c +++ b/glib/ghash.c @@ -95,8 +95,8 @@ * GHashTable: * * The #GHashTable struct is an opaque data structure to represent a - * Hash Table. It should only be - * accessed via the following functions. + * [Hash Table][glib-Hash-Tables]. It should only be accessed via the + * following functions. */ /** diff --git a/glib/giochannel.c b/glib/giochannel.c index 1331069..a5767c3 100644 --- a/glib/giochannel.c +++ b/glib/giochannel.c @@ -50,9 +50,9 @@ * * The #GIOChannel data type aims to provide a portable method for * using file descriptors, pipes, and sockets, and integrating them - * into the main event - * loop. Currently full support is available on UNIX platforms, - * support for Windows is only partially complete. + * into the [main event loop][glib-The-Main-Event-Loop]. Currently, + * full support is available on UNIX platforms, support for Windows + * is only partially complete. * * To create a new #GIOChannel on UNIX systems use * g_io_channel_unix_new(). This works for plain file descriptors, @@ -64,9 +64,8 @@ * g_io_channel_write_chars(), g_io_channel_seek_position(), and * g_io_channel_shutdown(). * - * To add a #GIOChannel to the main event loop use - * g_io_add_watch() or g_io_add_watch_full(). Here you specify which + * To add a #GIOChannel to the [main event loop][glib-The-Main-Event-Loop], + * use g_io_add_watch() or g_io_add_watch_full(). Here you specify which * events you are interested in on the #GIOChannel, and provide a * function to be called whenever these events occur. * diff --git a/glib/glist.c b/glib/glist.c index 7ed6d3c..85d1e18 100644 --- a/glib/glist.c +++ b/glib/glist.c @@ -45,23 +45,21 @@ * Each element in the list contains a piece of data, together with * pointers which link to the previous and next elements in the list. * Using these pointers it is possible to move through the list in both - * directions (unlike the singly-linked #GSList which - * only allows movement through the list in the forward direction). + * directions (unlike the singly-linked [GSList][glib-Singly-Linked-Lists], + * which only allows movement through the list in the forward direction). * * The double linked list does not keep track of the number of items * and does not keep track of both the start and end of the list. If * you want fast access to both the start and the end of the list, * and/or the number of items in the list, use a - * GQueue instead. + * [GQueue][glib-Double-ended-Queues] instead. * * The data contained in each element can be either integer values, by - * using one of the Type - * Conversion Macros, or simply pointers to any type of data. + * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], + * or simply pointers to any type of data. * - * List elements are allocated from the slice allocator, which is more - * efficient than allocating elements individually. + * List elements are allocated from the [slice allocator][glib-Memory-Slices], + * which is more efficient than allocating elements individually. * * Note that most of the #GList functions expect to be passed a pointer * to the first element in the list. The functions which insert @@ -118,9 +116,8 @@ /** * GList: * @data: holds the element's data, which can be a pointer to any kind - * of data, or any integer value using the Type Conversion - * Macros. + * of data, or any integer value using the + * [Type Conversion Macros][glib-Type-Conversion-Macros] * @next: contains the link to the next element in the list * @prev: contains the link to the previous element in the list * diff --git a/glib/gmain.c b/glib/gmain.c index 41b5ca5..364dcae 100644 --- a/glib/gmain.c +++ b/glib/gmain.c @@ -688,7 +688,7 @@ static GPrivate thread_context_stack = G_PRIVATE_INIT (free_context_stack); * * Acquires @context and sets it as the thread-default context for the * current thread. This will cause certain asynchronous operations - * (such as most gio-based I/O) which are + * (such as most [gio][gio]-based I/O) which are * started in this thread to run under @context and deliver their * results to its main loop, rather than running under the global * default context in the main thread. Note that calling this function diff --git a/glib/gmessages.c b/glib/gmessages.c index 61d3b1d..5be6934 100644 --- a/glib/gmessages.c +++ b/glib/gmessages.c @@ -1129,8 +1129,7 @@ g_assert_warning (const char *log_domain, * g_test_expect_message: * @log_domain: (allow-none): the log domain of the message * @log_level: the log level of the message - * @pattern: a glob-style - * pattern + * @pattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * * Indicates that a message with the given @log_domain and @log_level, * with text matching @pattern, is expected to be logged. When this diff --git a/glib/gnode.c b/glib/gnode.c index 6fcc651..6677f33 100644 --- a/glib/gnode.c +++ b/glib/gnode.c @@ -86,8 +86,7 @@ * children are accessed by using the @next pointer of each * child. * - * The #GNode struct represents one node in a - * N-ary Tree. fields + * The #GNode struct represents one node in a [n-ary tree][glib-N-ary-Trees]. **/ #define g_node_alloc0() g_slice_new0 (GNode) @@ -851,10 +850,9 @@ g_node_depth_traverse_level (GNode *node, * Post order: A, C, E, D, B, H, I, G, F * * - * @G_LEVEL_ORDER: is not implemented for Balanced Binary - * Trees. For N-ary Trees, it + * @G_LEVEL_ORDER: is not implemented for + * [balanced binary trees][glib-Balanced-Binary-Trees]. + * For [n-ary trees][glib-N-ary-Trees], it * vists the root node first, then its children, then * its grandchildren, and so on. Note that this is less * efficient than the other orders. diff --git a/glib/goption.c b/glib/goption.c index 9d251ff..7a70ab3 100644 --- a/glib/goption.c +++ b/glib/goption.c @@ -1814,8 +1814,7 @@ platform_get_argv0 (void) * this function will produce help output to stdout and * call `exit (0)`. * - * Note that function depends on the - * current locale for + * Note that function depends on the [current locale][setlocale] for * automatic character set conversion of string and filename * arguments. * diff --git a/glib/gprintf.c b/glib/gprintf.c index 583695b..cf4bf21 100644 --- a/glib/gprintf.c +++ b/glib/gprintf.c @@ -28,7 +28,7 @@ /** * g_printf: * @format: a standard printf() format string, but notice - * string precision pitfalls. + * [string precision pitfalls][string-precision] * @...: the arguments to insert in the output. * * An implementation of the standard printf() function which supports @@ -60,7 +60,7 @@ g_printf (gchar const *format, * g_fprintf: * @file: the stream to write to. * @format: a standard printf() format string, but notice - * string precision pitfalls. + * [string precision pitfalls][string-precision] * @...: the arguments to insert in the output. * * An implementation of the standard fprintf() function which supports @@ -91,7 +91,7 @@ g_fprintf (FILE *file, * is up to the caller to ensure that the allocated buffer is large * enough to hold the formatted result * @format: a standard printf() format string, but notice - * string precision pitfalls. + * [string precision pitfalls][string-precision] * @...: the arguments to insert in the output. * * An implementation of the standard sprintf() function which supports @@ -127,7 +127,7 @@ g_sprintf (gchar *string, * @n: the maximum number of bytes to produce (including the * terminating nul character). * @format: a standard printf() format string, but notice - * string precision pitfalls. + * [string precision pitfalls][string-precision] * @...: the arguments to insert in the output. * * A safer form of the standard sprintf() function. The output is guaranteed @@ -170,7 +170,7 @@ g_snprintf (gchar *string, /** * g_vprintf: * @format: a standard printf() format string, but notice - * string precision pitfalls. + * [string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * An implementation of the standard vprintf() function which supports @@ -193,7 +193,7 @@ g_vprintf (gchar const *format, * g_vfprintf: * @file: the stream to write to. * @format: a standard printf() format string, but notice - * string precision pitfalls. + * [string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * An implementation of the standard fprintf() function which supports @@ -217,7 +217,7 @@ g_vfprintf (FILE *file, * g_vsprintf: * @string: the buffer to hold the output. * @format: a standard printf() format string, but notice - * string precision pitfalls. + * [string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * An implementation of the standard vsprintf() function which supports @@ -244,7 +244,7 @@ g_vsprintf (gchar *string, * @n: the maximum number of bytes to produce (including the * terminating nul character). * @format: a standard printf() format string, but notice - * string precision pitfalls. + * string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * A safer form of the standard vsprintf() function. The output is guaranteed @@ -284,7 +284,7 @@ g_vsnprintf (gchar *string, * g_vasprintf: * @string: the return location for the newly-allocated string. * @format: a standard printf() format string, but notice - * string precision pitfalls. + * [string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * An implementation of the GNU vasprintf() function which supports diff --git a/glib/gquark.c b/glib/gquark.c index 0ea0233..d620533 100644 --- a/glib/gquark.c +++ b/glib/gquark.c @@ -63,9 +63,8 @@ static gint quark_block_offset = 0; * Given either the string or the #GQuark identifier it is possible to * retrieve the other. * - * Quarks are used for both Datasets and Keyed Data Lists. + * Quarks are used for both [datasets][glib-Datasets] and + * [keyed data lists][glib-Keyed-Data-Lists]. * * To create a new quark from a string, use g_quark_from_string() or * g_quark_from_static_string(). diff --git a/glib/gqueue.c b/glib/gqueue.c index bc27ff8..2d6ea3e 100644 --- a/glib/gqueue.c +++ b/glib/gqueue.c @@ -32,8 +32,8 @@ * as #GList to store elements. * * The data contained in each element can be either integer values, by - * using one of the Type - * Conversion Macros, or simply pointers to any type of data. + * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], + * or simply pointers to any type of data. * * To create a new GQueue, use g_queue_new(). * diff --git a/glib/gregex.c b/glib/gregex.c index 5f1dedf..45d3c52 100644 --- a/glib/gregex.c +++ b/glib/gregex.c @@ -42,7 +42,7 @@ * SECTION:gregex * @title: Perl-compatible regular expressions * @short_description: matches strings against regular expressions - * @see_also: + * @see_also: [Regular expression syntax][glib-regex-syntax] * * The g_regex_*() functions implement regular * expression pattern matching using syntax and semantics similar to diff --git a/glib/gsequence.c b/glib/gsequence.c index a4d9790..3109345 100644 --- a/glib/gsequence.c +++ b/glib/gsequence.c @@ -30,11 +30,10 @@ * * The #GSequence data structure has the API of a list, but is * implemented internally with a balanced binary tree. This means that - * it is possible to maintain a sorted list of n elements in time O(n - * log n). The data contained in each element can be either integer - * values, by using of the Type Conversion Macros, - * or simply pointers to any type of data. + * it is possible to maintain a sorted list of n elements in time O(n log n). + * The data contained in each element can be either integer values, by using + * of the [Type Conversion Macros][glib-Type-Conversion-Macros], or simply + * pointers to any type of data. * * A #GSequence is accessed through "iterators", represented by a * #GSequenceIter. An iterator represents a position between two @@ -91,7 +90,7 @@ typedef struct _GSequenceNode GSequenceNode; * GSequence: * * The #GSequence struct is an opaque data type representing a - * Sequence data type. + * [sequence][glib-Sequences] data type. */ struct _GSequence { diff --git a/glib/gslice.c b/glib/gslice.c index ec89b10..d3a5adc 100644 --- a/glib/gslice.c +++ b/glib/gslice.c @@ -870,8 +870,7 @@ thread_memory_magazine2_free (ThreadMemory *tmem, * It calls g_slice_alloc() with `sizeof (@type)` and casts the * returned pointer to a pointer of the given type, avoiding a type * cast in the source code. Note that the underlying slice allocation - * mechanism can be changed with the - * G_SLICE=always-malloc + * mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE] * environment variable. * * Returns: a pointer to the allocated block, cast to a pointer to @type @@ -890,7 +889,7 @@ thread_memory_magazine2_free (ThreadMemory *tmem, * and casts the returned pointer to a pointer of the given type, * avoiding a type cast in the source code. * Note that the underlying slice allocation mechanism can - * be changed with the G_SLICE=always-malloc + * be changed with the [`G_SLICE=always-malloc`][G_SLICE] * environment variable. * * Since: 2.10 @@ -908,7 +907,7 @@ thread_memory_magazine2_free (ThreadMemory *tmem, * and casts the returned pointer to a pointer of the given type, * avoiding a type cast in the source code. * Note that the underlying slice allocation mechanism can - * be changed with the G_SLICE=always-malloc + * be changed with the [`G_SLICE=always-malloc`][G_SLICE] * environment variable. * * Returns: a pointer to the allocated block, cast to a pointer to @type @@ -927,9 +926,8 @@ thread_memory_magazine2_free (ThreadMemory *tmem, * It calls g_slice_free1() using `sizeof (type)` * as the block size. * Note that the exact release behaviour can be changed with the - * G_DEBUG=gc-friendly environment - * variable, also see G_SLICE for - * related debugging options. + * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see + * [`G_SLICE`][G_SLICE] for related debugging options. * * Since: 2.10 */ @@ -946,9 +944,8 @@ thread_memory_magazine2_free (ThreadMemory *tmem, * a @next pointer (similar to #GSList). The name of the * @next field in @type is passed as third argument. * Note that the exact release behaviour can be changed with the - * G_DEBUG=gc-friendly environment - * variable, also see G_SLICE for - * related debugging options. + * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see + * [`G_SLICE`][G_SLICE] for related debugging options. * * Since: 2.10 */ @@ -964,7 +961,7 @@ thread_memory_magazine2_free (ThreadMemory *tmem, * if a malloc() fallback implementation is used instead, * the alignment may be reduced in a libc dependent fashion. * Note that the underlying slice allocation mechanism can - * be changed with the G_SLICE=always-malloc + * be changed with the [`G_SLICE=always-malloc`][G_SLICE] * environment variable. * * Returns: a pointer to the allocated memory block @@ -1022,8 +1019,7 @@ g_slice_alloc (gsize mem_size) * * Allocates a block of memory via g_slice_alloc() and initializes * the returned memory to 0. Note that the underlying slice allocation - * mechanism can be changed with the - * G_SLICE=always-malloc + * mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE] * environment variable. * * Returns: a pointer to the allocated block @@ -1071,10 +1067,8 @@ g_slice_copy (gsize mem_size, * The memory must have been allocated via g_slice_alloc() or * g_slice_alloc0() and the @block_size has to match the size * specified upon allocation. Note that the exact release behaviour - * can be changed with the - * G_DEBUG=gc-friendly environment - * variable, also see G_SLICE for - * related debugging options. + * can be changed with the [`G_DEBUG=gc-friendly`][G_DEBUG] environment + * variable, also see [`G_SLICE`][G_SLICE] for related debugging options. * * Since: 2.10 */ @@ -1133,9 +1127,8 @@ g_slice_free1 (gsize mem_size, * @next pointer (similar to #GSList). The offset of the @next * field in each block is passed as third argument. * Note that the exact release behaviour can be changed with the - * G_DEBUG=gc-friendly environment - * variable, also see G_SLICE for - * related debugging options. + * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see + * [`G_SLICE`][G_SLICE] for related debugging options. * * Since: 2.10 */ diff --git a/glib/gslist.c b/glib/gslist.c index 4c6af46..fc4f865 100644 --- a/glib/gslist.c +++ b/glib/gslist.c @@ -1,60 +1,58 @@ /* GLIB - Library of useful routines for C programming - * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald - * - * This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU Lesser General Public - * License as published by the Free Software Foundation; either - * version 2 of the License, or (at your option) any later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public - * License along with this library; if not, see . - */ - -/* - * Modified by the GLib Team and others 1997-2000. See the AUTHORS - * file for a list of people on the GLib Team. See the ChangeLog - * files for a list of changes. These files are distributed with - * GLib at ftp://ftp.gtk.org/pub/gtk/. - */ - -/* - * MT safe - */ - -#include "config.h" - -#include "gslist.h" - -#include "gtestutils.h" -#include "gslice.h" - -/** - * SECTION:linked_lists_single - * @title: Singly-Linked Lists - * @short_description: linked lists that can be iterated in one direction - * - * The #GSList structure and its associated functions provide a - * standard singly-linked list data structure. - * - * Each element in the list contains a piece of data, together with a - * pointer which links to the next element in the list. Using this - * pointer it is possible to move through the list in one direction - * only (unlike the Doubly-Linked Lists which - * allow movement in both directions). - * - * The data contained in each element can be either integer values, by - * using one of the Type - * Conversion Macros, or simply pointers to any type of data. - * - * List elements are allocated from the slice allocator, which is more - * efficient than allocating elements individually. + * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, see . + */ + + /* + * Modified by the GLib Team and others 1997-2000. See the AUTHORS + * file for a list of people on the GLib Team. See the ChangeLog + * files for a list of changes. These files are distributed with + * GLib at ftp://ftp.gtk.org/pub/gtk/. + */ + + /* + * MT safe + */ + + #include "config.h" + + #include "gslist.h" + + #include "gtestutils.h" + #include "gslice.h" + + /** + * SECTION:linked_lists_single + * @title: Singly-Linked Lists + * @short_description: linked lists that can be iterated in one direction + * + * The #GSList structure and its associated functions provide a + * standard singly-linked list data structure. + * + * Each element in the list contains a piece of data, together with a + * pointer which links to the next element in the list. Using this + * pointer it is possible to move through the list in one direction + * only (unlike the [double-linked lists][glib-Doubly-Linked-Lists], + * which allow movement in both directions). + * + * The data contained in each element can be either integer values, by + * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], + * or simply pointers to any type of data. + * + * List elements are allocated from the [slice allocator][glib-Memory-Slices], + * which is more efficient than allocating elements individually. * * Note that most of the #GSList functions expect to be passed a * pointer to the first element in the list. The functions which insert @@ -84,9 +82,8 @@ /** * GSList: * @data: holds the element's data, which can be a pointer to any kind - * of data, or any integer value using the Type Conversion - * Macros. + * of data, or any integer value using the + * [Type Conversion Macros][glib-Type-Conversion-Macros] * @next: contains the link to the next element in the list. * * The #GSList struct is used for each element in the singly-linked diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c index 877cb4d..f4f6d5e 100644 --- a/glib/gstrfuncs.c +++ b/glib/gstrfuncs.c @@ -485,7 +485,7 @@ g_stpcpy (gchar *dest, /** * g_strdup_vprintf: * @format: a standard printf() format string, but notice - * string precision pitfalls + * [string precision pitfalls][string-precision] * @args: the list of parameters to insert into the format string * * Similar to the standard C vsprintf() function but safer, since it @@ -512,7 +512,7 @@ g_strdup_vprintf (const gchar *format, /** * g_strdup_printf: * @format: a standard printf() format string, but notice - * string precision pitfalls + * [string precision pitfalls][string-precision] * @...: the parameters to insert into the format string * * Similar to the standard C sprintf() function but safer, since it diff --git a/glib/gtestutils.c b/glib/gtestutils.c index bfcc8e1..92a40d7 100644 --- a/glib/gtestutils.c +++ b/glib/gtestutils.c @@ -59,8 +59,7 @@ * SECTION:testing * @title: Testing * @short_description: a test framework - * @see_also: gtester, - * gtester-report + * @see_also: [gtester][gtester], [gtester-report][gtester-report] * * GLib provides a framework for writing and maintaining unit tests * in parallel to the code they are testing. The API is designed according @@ -253,8 +252,7 @@ /** * g_test_trap_assert_stdout: - * @soutpattern: a glob-style - * pattern + * @soutpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * * Assert that the stdout output of the last test subprocess matches * @soutpattern. See g_test_trap_subprocess(). @@ -264,8 +262,7 @@ /** * g_test_trap_assert_stdout_unmatched: - * @soutpattern: a glob-style - * pattern + * @soutpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * * Assert that the stdout output of the last test subprocess * does not match @soutpattern. See g_test_trap_subprocess(). @@ -275,8 +272,7 @@ /** * g_test_trap_assert_stderr: - * @serrpattern: a glob-style - * pattern + * @serrpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * * Assert that the stderr output of the last test subprocess * matches @serrpattern. See g_test_trap_subprocess(). @@ -293,8 +289,7 @@ /** * g_test_trap_assert_stderr_unmatched: - * @serrpattern: a glob-style - * pattern + * @serrpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * * Assert that the stderr output of the last test subprocess * does not match @serrpattern. See g_test_trap_subprocess(). diff --git a/glib/gtree.c b/glib/gtree.c index 1b7b8ee..3ea375c 100644 --- a/glib/gtree.c +++ b/glib/gtree.c @@ -71,9 +71,9 @@ typedef struct _GTreeNode GTreeNode; /** * GTree: * - * The GTree struct is an opaque data structure representing a Balanced Binary Tree. - * It should be accessed only by using the following functions. + * The GTree struct is an opaque data structure representing a + * [balanced binary tree][glib-Balanced-Binary-Trees]. It should be + * accessed only by using the following functions. */ struct _GTree { @@ -940,8 +940,7 @@ g_tree_foreach (GTree *tree, * Deprecated:2.2: The order of a balanced tree is somewhat arbitrary. * If you just want to visit all nodes in sorted order, use * g_tree_foreach() instead. If you really need to visit nodes in - * a different order, consider using an - * N-ary Tree. + * a different order, consider using an [n-ary tree][glib-N-ary-Trees]. */ /** * GTraverseFunc: diff --git a/glib/gunicollate.c b/glib/gunicollate.c index b8a1481..6440dd2 100644 --- a/glib/gunicollate.c +++ b/glib/gunicollate.c @@ -65,7 +65,7 @@ msc_strxfrm_wrapper (char *string1, * @str2: a UTF-8 encoded string * * Compares two strings for ordering using the linguistically - * correct rules for the current locale. + * correct rules for the [current locale][setlocale]. * When sorting a large number of strings, it will be significantly * faster to obtain collation keys with g_utf8_collate_key() and * compare the keys with strcmp() when sorting instead of sorting @@ -363,8 +363,7 @@ carbon_collate_key_for_filename (const gchar *str, * with strcmp() will always be the same as comparing the two * original keys with g_utf8_collate(). * - * Note that this function depends on the - * current locale. + * Note that this function depends on the [current locale][setlocale]. * * Return value: a newly allocated string. This string should * be freed with g_free() when you are done with it. @@ -491,8 +490,7 @@ g_utf8_collate_key (const gchar *str, * would like to treat numbers intelligently so that "file1" "file10" "file5" * is sorted as "file1" "file5" "file10". * - * Note that this function depends on the - * current locale. + * Note that this function depends on the [current locale][setlocale]. * * Return value: a newly allocated string. This string should * be freed with g_free() when you are done with it. diff --git a/glib/gvariant-parser.c b/glib/gvariant-parser.c index 7617f34..7536844 100644 --- a/glib/gvariant-parser.c +++ b/glib/gvariant-parser.c @@ -2325,7 +2325,7 @@ parse (TokenStream *stream, * * A single #GVariant is parsed from the content of @text. * - * The format is described here. + * The format is described [here][gvariant-text]. * * The memory at @limit will never be accessed and the parser behaves as * if the character at @limit is the nul terminator. This has the @@ -2430,7 +2430,7 @@ g_variant_parse (const GVariantType *type, * * Note that the arguments in @app must be of the correct width for their types * specified in @format when collected into the #va_list. See - * the GVariant varargs documentation. + * the [GVariant varargs documentation][gvariant-varargs]. * * In order to behave correctly in all cases it is necessary for the * calling function to g_variant_ref_sink() the return result before @@ -2487,7 +2487,7 @@ g_variant_new_parsed_va (const gchar *format, * * Note that the arguments must be of the correct width for their types * specified in @format. This can be achieved by casting them. See - * the GVariant varargs documentation. + * the [GVariant varargs documentation][gvariant-varargs]. * * Consider this simple example: * |[ @@ -2540,7 +2540,7 @@ g_variant_new_parsed (const gchar *format, * * Note that the arguments must be of the correct width for their types * specified in @format_string. This can be achieved by casting them. See - * the GVariant varargs documentation. + * the [GVariant varargs documentation][gvariant-varargs]. * * This function might be used as follows: * diff --git a/glib/gvariant.c b/glib/gvariant.c index 93d2278..a64793b 100644 --- a/glib/gvariant.c +++ b/glib/gvariant.c @@ -922,7 +922,7 @@ g_variant_new_dict_entry (GVariant *key, * @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 - * GVariant Format Strings. + * [GVariant format strings][gvariant-format-strings-pointers]. * * This function is currently implemented with a linear scan. If you * plan to do many lookups then #GVariantDict may be more efficient. @@ -1069,8 +1069,7 @@ g_variant_lookup_value (GVariant *dictionary, * * @element_size must be the size of a single element in the array, * as given by the section on - * Serialised Data - * Memory. + * [serialized data memory][gvariant-serialised-data-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 the size @@ -2577,7 +2576,7 @@ g_variant_print_string (GVariant *value, * * Pretty-prints @value in the format understood by g_variant_parse(). * - * The format is described here. + * The format is described [here][gvariant-text]. * * If @type_annotate is %TRUE, then type information is included in * the output. @@ -3844,10 +3843,9 @@ g_variant_dict_init (GVariantDict *dict, * this function returns %FALSE. Otherwise, it unpacks the returned * value and returns %TRUE. * - * @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 - * GVariant Format Strings. + * @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 [GVariant format strings][gvariant-format-strings-pointers]. * * Returns: %TRUE if a value was unpacked * @@ -4158,8 +4156,7 @@ g_variant_dict_unref (GVariantDict *dict) * not be accessed and the effect is otherwise equivalent to if the * character at @limit were nul. * - * See the section on GVariant - * Format Strings. + * See the section on [GVariant format strings][gvariant-format-strings]. * * Returns: %TRUE if there was a valid format string * @@ -5158,11 +5155,11 @@ g_variant_valist_get (const gchar **str, * * Think of this function as an analogue to g_strdup_printf(). * - * The type of the created instance and the arguments that are - * expected by this function are determined by @format_string. See the - * section on GVariant Format - * Strings. Please note that the syntax of the format string is - * very likely to be extended in the future. + * The type of the created instance and the arguments that are expected + * by this function are determined by @format_string. See the section on + * [GVariant format strings][gvariant-format-strings]. Please note that + * the syntax of the format string is very likely to be extended in the + * future. * * The first character of the format string must not be '*' '?' '@' or * 'r'; in essence, a new #GVariant must always be constructed by this @@ -5170,7 +5167,7 @@ g_variant_valist_get (const gchar **str, * * Note that the arguments must be of the correct width for their types * specified in @format_string. This can be achieved by casting them. See - * the GVariant varargs documentation. + * the [GVariant varargs documentation][gvariant-varargs]. * * * MyFlags some_flags = FLAG_ONE | FLAG_TWO; @@ -5229,9 +5226,9 @@ g_variant_new (const gchar *format_string, * @format_string, are collected from this #va_list and the list is left * pointing to the argument following the last. * - * Note that the arguments in @app must be of the correct width for their types - * specified in @format_string when collected into the #va_list. See - * the GVariant varargs documentation. + * Note that the arguments in @app must be of the correct width for their + * types specified in @format_string when collected into the #va_list. + * See the [GVariant varargs documentation][gvariant-varargs. * * These two generalisations allow mixing of multiple calls to * g_variant_new_va() and g_variant_get_va() within a single actual @@ -5286,15 +5283,15 @@ g_variant_new_va (const gchar *format_string, * The arguments that are expected by this function are entirely * determined by @format_string. @format_string also restricts the * permissible types of @value. It is an error to give a value with - * an incompatible type. See the section on GVariant Format Strings. + * an incompatible type. See the section on + * [GVariant format strings][gvariant-format-strings]. * Please note that the syntax of the format string is very likely to be * extended in the future. * * @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 - * GVariant Format Strings. + * [GVariant format strings][gvariant-format-strings-pointers]. * * Since: 2.24 **/ @@ -5347,7 +5344,7 @@ g_variant_get (GVariant *value, * @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 - * GVariant Format Strings. + * [GVariant format strings][gvariant-format-strings-pointers]. * * Since: 2.24 **/ @@ -5386,7 +5383,7 @@ g_variant_get_va (GVariant *value, * * Note that the arguments must be of the correct width for their types * specified in @format_string. This can be achieved by casting them. See - * the GVariant varargs documentation. + * the [GVariant varargs documentation][gvariant-varargs]. * * This function might be used as follows: * @@ -5442,7 +5439,7 @@ g_variant_builder_add (GVariantBuilder *builder, * @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 - * GVariant Format Strings. + * [GVariant format strings][gvariant-format-strings-pointers]. * * Since: 2.24 **/ @@ -5511,7 +5508,7 @@ g_variant_get_child (GVariant *value, * the values and also determines if the values are copied or borrowed. * * See the section on - * GVariant Format Strings. + * [GVariant format strings][gvariant-format-strings-pointers]. * * Returns: %TRUE if a value was unpacked, or %FALSE if there as no value * @@ -5611,7 +5608,7 @@ g_variant_iter_next (GVariantIter *iter, * the values and also determines if the values are copied or borrowed. * * See the section on - * GVariant Format Strings. + * [GVariant format strings][gvariant-format-strings-pointers]. * * Returns: %TRUE if a value was unpacked, or %FALSE if there was no * value diff --git a/gmodule/gmodule.c b/gmodule/gmodule.c index fb04bfc..85d5c54 100644 --- a/gmodule/gmodule.c +++ b/gmodule/gmodule.c @@ -129,8 +129,8 @@ * GModule: * * The #GModule struct is an opaque data structure to represent a - * Dynamically-Loaded - * Module. It should only be accessed via the following functions. + * [dynamically-loaded module][glib-Dynamic-Loading-of-Modules]. + * It should only be accessed via the following functions. */ /** diff --git a/gobject/gclosure.c b/gobject/gclosure.c index 4ebbfcf..c28f841 100644 --- a/gobject/gclosure.c +++ b/gobject/gclosure.c @@ -61,9 +61,8 @@ * marshaller for any closure which is connected to this * signal. GObject provides a number of C marshallers for this * purpose, see the g_cclosure_marshal_*() functions. Additional C - * marshallers can be generated with the glib-genmarshal utility. Closures - * can be explicitly connected to signals with + * marshallers can be generated with the [glib-genmarshal][glib-genmarshal] + * utility. Closures can be explicitly connected to signals with * g_signal_connect_closure(), but it usually more convenient to let * GObject create a closure automatically by using one of the * g_signal_connect_*() functions which take a callback function/user @@ -308,9 +307,8 @@ g_closure_set_meta_va_marshal (GClosure *closure, * Sets the meta marshaller of @closure. A meta marshaller wraps * @closure->marshal and modifies the way it is called in some * fashion. The most common use of this facility is for C callbacks. - * The same marshallers (generated by glib-genmarshal) are used - * everywhere, but the way that we get the callback function + * The same marshallers (generated by [glib-genmarshal][glib-genmarshal]), + * are used everywhere, but the way that we get the callback function * differs. In most cases we want to use @closure->callback, but in * other cases we want to use some different technique to retrieve the * callback function. diff --git a/gobject/genums.c b/gobject/genums.c index d8f1d30..d6dc559 100644 --- a/gobject/genums.c +++ b/gobject/genums.c @@ -47,9 +47,8 @@ * GLib type system, it can be used as value type for object * properties, using g_param_spec_enum() or g_param_spec_flags(). * - * GObject ships with a utility called glib-mkenums that can construct - * suitable type registration functions from C enumeration + * GObject ships with a utility called [glib-mkenums][glib-mkenums], + * that can construct suitable type registration functions from C enumeration * definitions. */ @@ -171,10 +170,9 @@ value_flags_enum_lcopy_value (const GValue *value, * * Registers a new static enumeration type with the name @name. * - * It is normally more convenient to let glib-mkenums generate a - * my_enum_get_type() function from a usual C enumeration definition - * than to write one yourself using g_enum_register_static(). + * It is normally more convenient to let [glib-mkenums][glib-mkenums], + * generate a my_enum_get_type() function from a usual C enumeration + * definition than to write one yourself using g_enum_register_static(). * * Returns: The new type identifier. */ @@ -215,10 +213,9 @@ g_enum_register_static (const gchar *name, * * Registers a new static flags type with the name @name. * - * It is normally more convenient to let glib-mkenums generate a - * my_flags_get_type() function from a usual C enumeration definition - * than to write one yourself using g_flags_register_static(). + * It is normally more convenient to let [glib-mkenums][glib-mkenums] + * generate a my_flags_get_type() function from a usual C enumeration + * definition than to write one yourself using g_flags_register_static(). * * Returns: The new type identifier. */ diff --git a/gobject/gobject.c b/gobject/gobject.c index f2f9fe7..6be1e84 100644 --- a/gobject/gobject.c +++ b/gobject/gobject.c @@ -43,8 +43,7 @@ * methods for all object types in GTK+, Pango and other libraries * based on GObject. The GObject class provides methods for object * construction and destruction, property access methods, and signal - * support. Signals are described in detail in . + * support. Signals are described in detail [here][gobject-Signals]. * * ## Floating references # {#floating-ref} * @@ -479,7 +478,7 @@ g_object_do_class_init (GObjectClass *class) * text_view) * ]| * It is important to note that you must use - * canonical parameter names as + * [canonical][canonical-parameter-name] parameter names as * detail strings for the notify signal. */ gobject_signals[NOTIFY] = @@ -2739,8 +2738,7 @@ object_floating_flag_handler (GObject *object, * g_object_is_floating: * @object: (type GObject.Object): a #GObject * - * Checks whether @object has a floating - * reference. + * Checks whether @object has a [floating][floating-ref] reference. * * Since: 2.10 * @@ -2759,8 +2757,7 @@ g_object_is_floating (gpointer _object) * @object: (type GObject.Object): a #GObject * * Increase the reference count of @object, and possibly remove the - * floating reference, if @object - * has a floating reference. + * [floating][floating-ref] reference, if @object has a floating reference. * * In other words, if the object is floating, then this call "assumes * ownership" of the floating reference, converting it to a normal @@ -2790,11 +2787,10 @@ g_object_ref_sink (gpointer _object) * g_object_force_floating: * @object: a #GObject * - * This function is intended for #GObject implementations to re-enforce a - * floating object reference. - * Doing this is seldom required: all - * #GInitiallyUnowneds are created with a floating reference which - * usually just needs to be sunken by calling g_object_ref_sink(). + * This function is intended for #GObject implementations to re-enforce + * a [floating][floating-ref] object reference. Doing this is seldom + * required: all #GInitiallyUnowneds are created with a floating reference + * which usually just needs to be sunken by calling g_object_ref_sink(). * * Since: 2.10 */ diff --git a/gobject/gvalue.c b/gobject/gvalue.c index a47ed99..87fdd4b 100644 --- a/gobject/gvalue.c +++ b/gobject/gvalue.c @@ -35,9 +35,9 @@ * other type * @see_also: The fundamental types which all support #GValue * operations and thus can be used as a type initializer for - * g_value_init() are defined by a separate interface. See the Standard - * Values API for details. + * g_value_init() are defined by a separate interface. See the + * [standard values API][gobject-Standard-Parameter-and-Value-Types] + * for details * @title: Generic values * * The #GValue structure is basically a variable container that consists