Update glib annotations from git master

3 files changed, 609 insertions, 270 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index aa175b21..f0978775 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -2279,6 +2279,14 @@
  * @parameter will always be of the expected type.  In the event that
  * an incorrect type was given, no signal will be emitted.
  *
+ * Since GLib 2.40, if no handler is connected to this signal then the
+ * default behaviour for boolean-stated actions with a %NULL parameter
+ * type is to toggle them via the #GSimpleAction::change-state signal.
+ * For stateful actions where the state type is equal to the parameter
+ * type, the default is to forward them directly to
+ * #GSimpleAction::change-state.  This should allow almost all users
+ * of #GSimpleAction to connect only one handler or the other.
+ *
  * Since: 2.28
  */
 
@@ -3549,6 +3557,7 @@
  * SECTION:gaction
  * @title: GAction
  * @short_description: An action interface
+ * @include: gio/gio.h
  *
  * #GAction represents a single named action.
  *
@@ -3568,7 +3577,7 @@
  *
  * #GAction is merely the interface to the concept of an action, as
  * described above.  Various implementations of actions exist, including
- * #GSimpleAction and #GtkAction.
+ * #GSimpleAction.
  *
  * In all cases, the implementing class is responsible for storing the
  * name of the action, the parameter type, the enabled state, the
@@ -3586,6 +3595,7 @@
  * SECTION:gactiongroup
  * @title: GActionGroup
  * @short_description: A group of actions
+ * @include: gio/gio.h
  * @see_also: #GAction
  *
  * #GActionGroup represents a group of actions. Actions can be used to
@@ -3639,6 +3649,7 @@
 /**
  * SECTION:gactiongroupexporter
  * @title: GActionGroup exporter
+ * @include: gio/gio.h
  * @short_description: Export GActionGroups on D-Bus
  * @see_also: #GActionGroup, #GDBusActionGroup
  *
@@ -3654,6 +3665,7 @@
 /**
  * SECTION:gactionmap
  * @title: GActionMap
+ * @include: gio/gio.h
  * @short_description: Interface for action containers
  *
  * The GActionMap interface is implemented by #GActionGroup
@@ -3759,6 +3771,7 @@
  * SECTION:gapplication
  * @title: GApplication
  * @short_description: Core application class
+ * @include: gio/gio.h
  *
  * A #GApplication is the foundation of an application.  It wraps some
  * low-level platform-specific services and is intended to act as the
@@ -3901,6 +3914,7 @@
  * SECTION:gapplicationcommandline
  * @title: GApplicationCommandLine
  * @short_description: A command-line invocation of an application
+ * @include: gio/gio.h
  * @see_also: #GApplication
  *
  * #GApplicationCommandLine represents a command-line invocation of
@@ -4386,6 +4400,7 @@
  * SECTION:gdbusactiongroup
  * @title: GDBusActionGroup
  * @short_description: A D-Bus GActionGroup implementation
+ * @include: gio/gio.h
  * @see_also: <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link>
  *
  * #GDBusActionGroup is an implementation of the #GActionGroup
@@ -4610,6 +4625,7 @@
  * SECTION:gdbusmenumodel
  * @title: GDBusMenuModel
  * @short_description: A D-Bus GMenuModel implementation
+ * @include: gio/gio.h
  * @see_also: <link linkend="gio-GMenuModel-exporter">GMenuModel Exporter</link>
  *
  * #GDBusMenuModel is an implementation of #GMenuModel that can be used
@@ -5513,6 +5529,7 @@
 /**
  * SECTION:ginetaddress
  * @short_description: An IPv4/IPv6 address
+ * @include: gio/gio.h
  *
  * #GInetAddress represents an IPv4 or IPv6 internet address. Use
  * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to
@@ -5530,6 +5547,7 @@
 /**
  * SECTION:ginetaddressmask
  * @short_description: An IPv4/IPv6 address mask
+ * @include: gio/gio.h
  *
  * #GInetAddressMask represents a range of IPv4 or IPv6 addresses
  * described by a base address and a length indicating how many bits
@@ -5541,6 +5559,7 @@
 /**
  * SECTION:ginetsocketaddress
  * @short_description: Internet GSocketAddress
+ * @include: gio/gio.h
  *
  * An IPv4 or IPv6 socket address; that is, the combination of a
  * #GInetAddress and a port number.
@@ -5709,6 +5728,7 @@
  * SECTION:gmenu
  * @title: GMenu
  * @short_description: A simple implementation of GMenuModel
+ * @include: gio/gio.h
  *
  * #GMenu is a simple implementation of #GMenuModel.
  * You populate a #GMenu by adding #GMenuItem instances to it.
@@ -5725,6 +5745,7 @@
  * SECTION:gmenuexporter
  * @title: GMenuModel exporter
  * @short_description: Export GMenuModels on D-Bus
+ * @include: gio/gio.h
  * @see_also: #GMenuModel, #GDBusMenuModel
  *
  * These functions support exporting a #GMenuModel on D-Bus.
@@ -5740,6 +5761,7 @@
  * SECTION:gmenumodel
  * @title: GMenuModel
  * @short_description: An abstract class representing the contents of a menu
+ * @include: gio/gio.h
  * @see_also: #GActionGroup
  *
  * #GMenuModel represents the contents of a menu -- an ordered list of
@@ -5999,6 +6021,7 @@
 /**
  * SECTION:gnotification
  * @short_description: User Notifications (pop up messages)
+ * @include: gio/gio.h
  *
  * #GNotification is a mechanism for creating a notification to be shown
  * to the user -- typically as a pop-up notification presented by the
@@ -6045,8 +6068,9 @@
 /**
  * SECTION:gpermission
  * @title: GPermission
- * @short_description: An object representing the permission to perform
- *                     a certain action
+ * @short_description: An object representing the permission
+ *     to perform a certain action
+ * @include: gio/gio.h
  *
  * A #GPermission represents the status of the caller's permission to
  * perform a certain action.
@@ -6110,6 +6134,7 @@
  * SECTION:gpropertyaction
  * @title: GPropertyAction
  * @short_description: A GAction reflecting a GObject property
+ * @include: gio/gio.h
  *
  * A #GPropertyAction is a way to get a #GAction with a state value
  * reflecting and controlling the value of a #GObject property.
@@ -6171,6 +6196,7 @@
 /**
  * SECTION:gproxy
  * @short_description: Interface for proxy handling
+ * @include: gio/gio.h
  *
  * A #GProxy handles connecting to a remote host via a given type of
  * proxy server. It is implemented by the 'gio-proxy' extension point.
@@ -6186,6 +6212,7 @@
 /**
  * SECTION:gproxyaddress
  * @short_description: An internet address with proxy information
+ * @include: gio/gio.h
  *
  * Support for proxied #GInetSocketAddress.
  */
@@ -6206,6 +6233,7 @@
  * SECTION:gremoteactiongroup
  * @title: GRemoteActionGroup
  * @short_description: A GActionGroup that interacts with other processes
+ * @include: gio/gio.h
  *
  * The GRemoteActionGroup interface is implemented by #GActionGroup
  * instances that either transmit action invocations to other processes
@@ -6363,6 +6391,7 @@
 /**
  * SECTION:gsettings
  * @short_description: High-level API for application settings
+ * @include: gio/gio.h
  *
  * The #GSettings class provides a convenient API for storing and retrieving
  * application settings.
@@ -6595,8 +6624,9 @@
 
 /**
  * SECTION:gsettingsschema
- * @short_description: Introspecting and controlling the loading of
- *                     GSettings schemas
+ * @short_description: Introspecting and controlling the loading
+ *     of GSettings schemas
+ * @include: gio/gio.h
  *
  * The #GSettingsSchemaSource and #GSettingsSchema APIs provide a
  * mechanism for advanced control over the loading of schemas and a
@@ -6697,6 +6727,7 @@
  * SECTION:gsimpleaction
  * @title: GSimpleAction
  * @short_description: A simple GAction implementation
+ * @include: gio/gio.h
  *
  * A #GSimpleAction is the obvious simple implementation of the #GAction
  * interface. This is the easiest way to create an action for purposes of
@@ -6710,6 +6741,7 @@
  * SECTION:gsimpleactiongroup
  * @title: GSimpleActionGroup
  * @short_description: A simple GActionGroup implementation
+ * @include: gio/gio.h
  *
  * #GSimpleActionGroup is a hash table filled with #GAction objects,
  * implementing the #GActionGroup and #GActionMap interfaces.
@@ -6898,6 +6930,7 @@
  * SECTION:gsimplepermission
  * @title: GSimplePermission
  * @short_description: A GPermission that doesn't change value
+ * @include: gio/gio.h
  *
  * #GSimplePermission is a trivial implementation of #GPermission that
  * represents a permission that is either always or never allowed.  The
@@ -6985,8 +7018,9 @@
 
 /**
  * SECTION:gsocketaddress
- * @short_description: Abstract base class representing endpoints for
- * socket communication
+ * @short_description: Abstract base class representing endpoints
+ *     for socket communication
+ * @include: gio/gio.h
  *
  * #GSocketAddress is the equivalent of <type>struct sockaddr</type>
  * in the BSD sockets API. This is an abstract class; use
@@ -7022,6 +7056,7 @@
 /**
  * SECTION:gsocketconnectable
  * @short_description: Interface for potential socket endpoints
+ * @include: gio/gio.h
  *
  * Objects that describe one or more potential socket endpoints
  * implement #GSocketConnectable. Callers can then use
@@ -7114,6 +7149,7 @@
  * SECTION:gsocketcontrolmessage
  * @title: GSocketControlMessage
  * @short_description: A GSocket control message
+ * @include: gio/gio.h
  * @see_also: #GSocket.
  *
  * A #GSocketControlMessage is a special-purpose utility message that
@@ -7145,6 +7181,7 @@
  * SECTION:gsocketlistener
  * @title: GSocketListener
  * @short_description: Helper for accepting network client connections
+ * @include: gio/gio.h
  * @see_also: #GThreadedSocketService, #GSocketService.
  *
  * A #GSocketListener is an object that keeps track of a set
@@ -7163,6 +7200,7 @@
  * SECTION:gsocketservice
  * @title: GSocketService
  * @short_description: Make it easy to implement a network service
+ * @include: gio/gio.h
  * @see_also: #GThreadedSocketService, #GSocketListener.
  *
  * A #GSocketService is an object that represents a service that
@@ -7222,6 +7260,7 @@
  * SECTION:gsubprocess
  * @title: GSubprocess
  * @short_description: Child processes
+ * @include: gio/gio.h
  * @see_also: #GSubprocessLauncher
  *
  * #GSubprocess allows the creation of and interaction with child
@@ -7288,6 +7327,7 @@
  * SECTION:gsubprocesslauncher
  * @title: GSubprocess Launcher
  * @short_description: Environment options for launching a child process
+ * @include: gio/gio.h
  *
  * This class contains a set of options for launching child processes,
  * such as where its standard input and output will be directed, the
@@ -7304,7 +7344,8 @@
 
 /**
  * SECTION:gtask
- * @short_description: Cancellable synchronous or asynchronous task and result
+ * @short_description: Cancellable synchronous or asynchronous task
+ *     and result
  * @include: gio/gio.h
  * @see_also: #GAsyncResult
  *
@@ -7834,6 +7875,7 @@
  * SECTION:gtcpconnection
  * @title: GTcpConnection
  * @short_description: A TCP GSocketConnection
+ * @include: gio/gio.h
  * @see_also: #GSocketConnection.
  *
  * This is the subclass of #GSocketConnection that is created
@@ -7846,7 +7888,9 @@
 /**
  * SECTION:gtcpwrapperconnection
  * @title: GTcpWrapperConnection
- * @short_description: Wrapper for non-GSocketConnection-based, GSocket-based GIOStreams
+ * @short_description: Wrapper for non-GSocketConnection-based,
+ *     GSocket-based GIOStreams
+ * @include: gio/gio.h
  * @see_also: #GSocketConnection.
  *
  * A #GTcpWrapperConnection can be used to wrap a #GIOStream that is
@@ -7972,6 +8016,7 @@
  * SECTION:gthreadedsocketservice
  * @title: GThreadedSocketService
  * @short_description: A threaded GSocketService
+ * @include: gio/gio.h
  * @see_also: #GSocketService.
  *
  * A #GThreadedSocketService is a simple subclass of #GSocketService
@@ -8036,6 +8081,7 @@
  * SECTION:gtlscertificate
  * @title: GTlsCertificate
  * @short_description: TLS certificate
+ * @include: gio/gio.h
  * @see_also: #GTlsConnection
  *
  * A certificate used for TLS authentication and encryption.
@@ -11134,7 +11180,12 @@
  *
  * Gets the list of arguments that was passed on the command line.
  *
- * The strings in the array may contain non-utf8 data.
+ * The strings in the array may contain non-UTF-8 data on UNIX (such as
+ * filenames or arguments given in the system locale) but are always in
+ * UTF-8 on Windows.
+ *
+ * If you wish to use the return value with #GOptionContext, you must
+ * use g_option_context_parse_strv().
  *
  * The return value is %NULL-terminated and should be freed using
  * g_strfreev().
@@ -11656,15 +11707,18 @@
  * is intended to be returned by main(). Although you are expected to pass
  * the @argc, @argv parameters from main() to this function, it is possible
  * to pass %NULL if @argv is not available or commandline handling is not
- * required.
+ * required.  Note that on Windows, @argc and @argv are ignored, and
+ * g_win32_get_command_line() is called internally (for proper support
+ * of Unicode commandline arguments).
  *
  * First, the local_command_line() virtual function is invoked.
  * This function always runs on the local instance. It gets passed a pointer
- * to a %NULL-terminated copy of @argv and is expected to remove the arguments
- * that it handled (shifting up remaining arguments). See
- * <xref linkend="gapplication-example-cmdline2"/> for an example of
- * parsing @argv manually. Alternatively, you may use the #GOptionContext API,
- * after setting <literal>argc = g_strv_length (argv);</literal>.
+ * to a %NULL-terminated copy of the command line and is expected to
+ * remove the arguments that it handled (shifting up remaining
+ * arguments). See <xref linkend="gapplication-example-cmdline2"/> for
+ * an example of parsing @argv manually. Alternatively, you may use the
+ * #GOptionContext API, but you must use g_option_context_parse_strv()
+ * in order to avoid memory leaks and encoding mismatches.
  *
  * The last argument to local_command_line() is a pointer to the @status
  * variable which can used to set the exit status that is returned from
@@ -11727,6 +11781,23 @@
  * be set accordingly, which helps the window manager determine which
  * application is showing the window.
  *
+ * Since 2.40, applications that are not explicitly flagged as services
+ * or launchers (ie: neither %G_APPLICATION_IS_SERVICE or
+ * %G_APPLICATION_IS_LAUNCHER are given as flags) will check (from the
+ * default handler for local_command_line) if "--gapplication-service"
+ * was given in the command line.  If this flag is present then normal
+ * commandline processing is interrupted and the
+ * %G_APPLICATION_IS_SERVICE flag is set.  This provides a "compromise"
+ * solution whereby running an application directly from the commandline
+ * will invoke it in the normal way (which can be useful for debugging)
+ * while still allowing applications to be D-Bus activated in service
+ * mode.  The D-Bus service file should invoke the executable with
+ * "--gapplication-service" as the sole commandline argument.  This
+ * approach is suitable for use by most graphical applications but
+ * should not be used from applications like editors that need precise
+ * control over when processes invoked via the commandline will exit and
+ * what their exit status will be.
+ *
  * Returns: the exit status
  * Since: 2.28
  */
@@ -18422,7 +18493,7 @@
  * of the keyfile backing @info.
  *
  * Returns: %TRUE if the @key exists
- * Since: 2.26
+ * Since: 2.36
  */
 
 
@@ -20226,9 +20297,8 @@
  * This call does no blocking I/O.
  *
  * Returns: string with the relative path from @descendant
- *     to @parent, or %NULL if @descendant doesn't have @parent
- *     as prefix. The returned string should be freed with g_free()
- *     when no longer needed.
+ *     to @parent. The returned string should be freed with
+ *     g_free() when no longer needed.
  */
 
 
@@ -21778,6 +21848,15 @@
  * This operation never fails, but the returned object might not
  * support any I/O operation if @arg points to a malformed path.
  *
+ * Note that on Windows, this function expects its argument to be in
+ * UTF-8 -- not the system code page.  This means that you
+ * should not use this function with string from argv as it is passed
+ * to main().  g_win32_get_command_line() will return a UTF-8 version of
+ * the commandline.  #GApplication also uses UTF-8 but
+ * g_application_command_line_create_file_for_arg() may be more useful
+ * for you there.  It is also always possible to use this function with
+ * #GOptionContext arguments of type %G_OPTION_ARG_FILENAME.
+ *
  * Returns: (transfer full): a new #GFile.
  *    Free the returned object with g_object_unref().
  */
@@ -29555,7 +29634,7 @@
  * It is a programmer error to give a @key that isn't contained in the
  * schema for @settings.
  *
- * Returns: (allow none) (transfer full): the default value
+ * Returns: (allow-none) (transfer full): the default value
  * Since: 2.40
  */
 
@@ -29780,7 +29859,7 @@
  * It is a programmer error to give a @key that isn't contained in the
  * schema for @settings.
  *
- * Returns: (allow none) (transfer full): the user's value, if set
+ * Returns: (allow-none) (transfer full): the user's value, if set
  * Since: 2.40
  */
 
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 61d6b196..a1bbb4fc 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -131,9 +131,9 @@
 
 /**
  * GCompareDataFunc:
- * @a: a value.
- * @b: a value to compare with.
- * @user_data: user data to pass to comparison function.
+ * @a: a value
+ * @b: a value to compare with
+ * @user_data: user data
  *
  * Specifies the type of a comparison function used to compare two
  * values.  The function should return a negative integer if the first
@@ -141,14 +141,14 @@
  * integer if the first value comes after the second.
  *
  * Returns: negative value if @a &lt; @b; zero if @a = @b; positive
- *          value if @a > @b.
+ *          value if @a > @b
  */
 
 
 /**
  * GCompareFunc:
- * @a: a value.
- * @b: a value to compare with.
+ * @a: a value
+ * @b: a value to compare with
  *
  * Specifies the type of a comparison function used to compare two
  * values.  The function should return a negative integer if the first
@@ -156,7 +156,7 @@
  * integer if the first value comes after the second.
  *
  * Returns: negative value if @a &lt; @b; zero if @a = @b; positive
- *          value if @a > @b.
+ *          value if @a > @b
  */
 
 
@@ -543,9 +543,8 @@
 
 /**
  * GFunc:
- * @data: the element's data.
- * @user_data: user data passed to g_list_foreach() or
- *             g_slist_foreach().
+ * @data: the element's data
+ * @user_data: user data passed to g_list_foreach() or g_slist_foreach()
  *
  * Specifies the type of functions passed to g_list_foreach() and
  * g_slist_foreach().
@@ -1221,8 +1220,8 @@
  *        of data, or any integer value using the <link
  *        linkend="glib-Type-Conversion-Macros">Type Conversion
  *        Macros</link>.
- * @next: contains the link to the next element in the list.
- * @prev: contains the link to the previous element in the list.
+ * @next: contains the link to the next element in the list
+ * @prev: contains the link to the previous element in the list
  *
  * The #GList struct is used for each element in a doubly-linked list.
  */
@@ -2232,16 +2231,16 @@
 
 /**
  * GTraverseFunc:
- * @key: a key of a #GTree node.
- * @value: the value corresponding to the key.
- * @data: user data passed to g_tree_traverse().
+ * @key: a key of a #GTree node
+ * @value: the value corresponding to the key
+ * @data: user data passed to g_tree_traverse()
  *
  * Specifies the type of function passed to g_tree_traverse(). It is
  * passed the key and value of each node, together with the @user_data
  * parameter passed to g_tree_traverse(). If the function returns
  * %TRUE, the traversal is stopped.
  *
- * Returns: %TRUE to stop the traversal.
+ * Returns: %TRUE to stop the traversal
  */
 
 
@@ -2251,8 +2250,32 @@
  *              then its right child. This is the one to use if you
  *              want the output sorted according to the compare
  *              function.
+ *              <informalfigure>
+ *                <mediaobject>
+ *                  <imageobject>
+ *                    <imagedata align="right" fileref="Sorted_binary_tree_inorder.svg" format="SVG"/>
+ *                  </imageobject>
+ *                  <caption>In order: A, B, C, D, E, F, G, H, I</caption>
+ *                </mediaobject>
+ *              </informalfigure>
  * @G_PRE_ORDER: visits a node, then its children.
+ *              <informalfigure>
+ *                <mediaobject>
+ *                  <imageobject>
+ *                    <imagedata align="right" fileref="Sorted_binary_tree_preorder.svg" format="SVG"/>
+ *                  </imageobject>
+ *                  <caption>Pre order: F, B, A, D, C, E, G, I, H</caption>
+ *                </mediaobject>
+ *              </informalfigure>
  * @G_POST_ORDER: visits the node's children, then the node itself.
+ *              <informalfigure>
+ *                <mediaobject>
+ *                  <imageobject>
+ *                    <imagedata align="right" fileref="Sorted_binary_tree_postorder.svg" format="SVG"/>
+ *                  </imageobject>
+ *                  <caption>Post order: A, C, E, D, B, H, I, G, F</caption>
+ *                </mediaobject>
+ *              </informalfigure>
  * @G_LEVEL_ORDER: is not implemented for <link
  *                 linkend="glib-Balanced-Binary-Trees">Balanced Binary
  *                 Trees</link>.  For <link
@@ -2260,6 +2283,14 @@
  *                 vists the root node first, then its children, then
  *                 its grandchildren, and so on. Note that this is less
  *                 efficient than the other orders.
+ *              <informalfigure>
+ *                <mediaobject>
+ *                  <imageobject>
+ *                    <imagedata align="right" fileref="Sorted_binary_tree_breadth-first_traversal.svg" format="SVG"/>
+ *                  </imageobject>
+ *                  <caption>Level order: F, B, G, A, D, I, C, E, H</caption>
+ *                </mediaobject>
+ *              </informalfigure>
  *
  * Specifies the type of traveral performed by g_tree_traverse(),
  * g_node_traverse() and g_node_find().
@@ -6922,10 +6953,16 @@
  * 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 <link
- * linkend="glib-Singly-Linked-Lists">Singly-Linked Lists</link> which
+ * directions (unlike the singly-linked <link
+ * linkend="glib-Singly-Linked-Lists">#GSList</link> 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
+ * <link linkend="glib-Double-ended-Queues">GQueue</link> instead.
+ *
  * The data contained in each element can be either integer values, by
  * using one of the <link linkend="glib-Type-Conversion-Macros">Type
  * Conversion Macros</link>, or simply pointers to any type of data.
@@ -6939,23 +6976,51 @@
  * elements return the new start of the list, which may have changed.
  *
  * There is no function to create a #GList. %NULL is considered to be
- * the empty list so you simply set a #GList* to %NULL.
+ * a valid, empty list so you simply set a #GList* to %NULL to initialize
+ * it.
  *
  * To add elements, use g_list_append(), g_list_prepend(),
  * g_list_insert() and g_list_insert_sorted().
  *
+ * To visit all elements in the list, use a loop over the list:
+ * |[
+ * GList *l;
+ * for (l = list; l != NULL; l = l->next)
+ *   {
+ *     /&ast; do something with l->data &ast;/
+ *   }
+ * ]|
+ *
+ * To call a function for each element in the list, use g_list_foreach().
+ *
+ * To loop over the list and modify it (e.g. remove a certain element)
+ * a while loop is more appropriate, for example:
+ * |[
+ * GList *l = list;
+ * while (l != NULL)
+ *   {
+ *     GList *next = l->next;
+ *     if (should_be_removed (l))
+ *       {
+ *         /&ast; possibly free l->data &ast;/
+ *         list = g_list_delete_link (list, l);
+ *       }
+ *     l = next;
+ *   }
+ * ]|
+ *
  * To remove elements, use g_list_remove().
  *
- * To find elements in the list use g_list_first(), g_list_last(),
- * g_list_next(), g_list_previous(), g_list_nth(), g_list_nth_data(),
+ * To navigate in a list, use g_list_first(), g_list_last(),
+ * g_list_next(), g_list_previous().
+ *
+ * To find elements in the list use g_list_nth(), g_list_nth_data(),
  * g_list_find() and g_list_find_custom().
  *
  * To find the index of an element use g_list_position() and
  * g_list_index().
  *
- * To call a function for each element in the list use g_list_foreach().
- *
- * To free the entire list, use g_list_free().
+ * To free the entire list, use g_list_free() or g_list_free_full().
  */
 
 
@@ -7380,7 +7445,7 @@
  * static gint max_size = 8;
  * static gboolean verbose = FALSE;
  * static gboolean beep = FALSE;
- * static gboolean rand = FALSE;
+ * static gboolean randomize = FALSE;
  *
  * static GOptionEntry entries[] =
  * {
@@ -7388,7 +7453,7 @@
  *   { "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Test up to 2^M items", "M" },
  *   { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL },
  *   { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL },
- *   { "rand", 0, 0, G_OPTION_ARG_NONE, &rand, "Randomize the data", NULL },
+ *   { "rand", 0, 0, G_OPTION_ARG_NONE, &randomize, "Randomize the data", NULL },
  *   { NULL }
  * };
  *
@@ -7411,6 +7476,57 @@
  *
  * }
  * </programlisting></informalexample>
+ *
+ * On UNIX systems, the argv that is passed to main() has no particular
+ * encoding, even to the extent that different parts of it may have
+ * different encodings.  In general, normal arguments and flags will be
+ * in the current locale and filenames should be considered to be opaque
+ * byte strings.  Proper use of %G_OPTION_ARG_FILENAME vs
+ * %G_OPTION_ARG_STRING is therefore important.
+ *
+ * Note that on Windows, filenames do have an encoding, but using
+ * #GOptionContext with the argv as passed to main() will result in a
+ * program that can only accept commandline arguments with characters
+ * from the system codepage.  This can cause problems when attempting to
+ * deal with filenames containing Unicode characters that fall outside
+ * of the codepage.
+ *
+ * A solution to this is to use g_win32_get_command_line() and
+ * g_option_context_parse_strv() which will properly handle full Unicode
+ * filenames.  If you are using #GApplication, this is done
+ * automatically for you.
+ *
+ * The following example shows how you can use #GOptionContext directly
+ * in order to correctly deal with Unicode filenames on Windows:
+ *
+ * |[
+ * int
+ * main (int argc, char **argv)
+ * {
+ *   GError *error = NULL;
+ *   GOptionContext *context;
+ *   gchar **args;
+ *
+ * #ifdef G_OS_WIN32
+ *   args = g_win32_get_command_line ();
+ * #else
+ *   args = g_strdupv (argv);
+ * #endif
+ *
+ *   /&ast; ... setup context ... &ast;/
+ *
+ *   if (!g_option_context_parse_strv (context, &args, &error))
+ *     {
+ *       /&ast; ... error ... &ast;/
+ *     }
+ *
+ *   /&ast; ... &ast;/
+ *
+ *   g_strfreev (args);
+ *
+ *   /&ast; ... &ast;/
+ * }
+ * ]|
  */
 
 
@@ -18318,7 +18434,7 @@
  * g_list_append(), g_list_prepend(), g_list_insert() and
  * g_list_insert_sorted() and so is rarely used on its own.
  *
- * Returns: a pointer to the newly-allocated #GList element.
+ * Returns: a pointer to the newly-allocated #GList element
  */
 
 
@@ -18329,51 +18445,55 @@
  *
  * Adds a new element on to the end of the list.
  *
- * <note><para>
- * The return value is the new start of the list, which
- * may have changed, so make sure you store the new value.
- * </para></note>
+ * Note that the return value is the new start of the list,
+ * if @list was empty; make sure you store the new value.
  *
- * <note><para>
- * Note that g_list_append() has to traverse the entire list
- * to find the end, which is inefficient when adding multiple
- * elements. A common idiom to avoid the inefficiency is to prepend
- * the elements and reverse the list when all elements have been added.
- * </para></note>
+ * g_list_append() has to traverse the entire list to find the end,
+ * which is inefficient when adding multiple elements. A common idiom
+ * to avoid the inefficiency is to use g_list_prepend() and reverse
+ * the list with g_list_reverse() when all elements have been added.
  *
  * |[
  * /&ast; Notice that these are initialized to the empty list. &ast;/
- * GList *list = NULL, *number_list = NULL;
+ * GList *string_list = NULL, *number_list = NULL;
  *
  * /&ast; This is a list of strings. &ast;/
- * list = g_list_append (list, "first");
- * list = g_list_append (list, "second");
+ * string_list = g_list_append (string_list, "first");
+ * string_list = g_list_append (string_list, "second");
  *
  * /&ast; This is a list of integers. &ast;/
  * number_list = g_list_append (number_list, GINT_TO_POINTER (27));
  * number_list = g_list_append (number_list, GINT_TO_POINTER (14));
  * ]|
  *
- * Returns: the new start of the #GList
+ * Returns: either @list or the new start of the #GList if @list was %NULL
  */
 
 
 /**
  * g_list_concat:
- * @list1: a #GList
- * @list2: the #GList to add to the end of the first #GList
+ * @list1: a #GList, this must point to the top of the list
+ * @list2: the #GList to add to the end of the first #GList,
+ *     this must point  to the top of the list
  *
  * Adds the second #GList onto the end of the first #GList.
  * Note that the elements of the second #GList are not copied.
  * They are used directly.
  *
- * Returns: the start of the new #GList
+ * This function is for example used to move an element in the list.
+ * The following example moves an element to the top of the list:
+ * |[
+ * list = g_list_remove_link (list, llink);
+ * list = g_list_concat (llink, list);
+ * ]|
+ *
+ * Returns: the start of the new #GList, which equals @list1 if not %NULL
  */
 
 
 /**
  * g_list_copy:
- * @list: a #GList
+ * @list: a #GList, this must point to the top of the list
  *
  * Copies a #GList.
  *
@@ -18384,24 +18504,25 @@
  * to copy the data as well.
  * </para></note>
  *
- * Returns: a copy of @list
+ * Returns: the start of the new list that holds the same data as @list
  */
 
 
 /**
  * g_list_copy_deep:
- * @list: a #GList
+ * @list: a #GList, this must point to the top of the list
  * @func: a copy function used to copy every element in the list
- * @user_data: user data passed to the copy function @func, or #NULL
+ * @user_data: user data passed to the copy function @func, or %NULL
  *
  * Makes a full (deep) copy of a #GList.
  *
- * In contrast with g_list_copy(), this function uses @func to make a copy of
- * each list element, in addition to copying the list container itself.
+ * In contrast with g_list_copy(), this function uses @func to make
+ * a copy of each list element, in addition to copying the list
+ * container itself.
  *
- * @func, as a #GCopyFunc, takes two arguments, the data to be copied and a user
- * pointer. It's safe to pass #NULL as user_data, if the copy function takes only
- * one argument.
+ * @func, as a #GCopyFunc, takes two arguments, the data to be copied
+ * and a @user_data pointer. It's safe to pass %NULL as user_data,
+ * if the copy function takes only one argument.
  *
  * For instance, if @list holds a list of GObjects, you can do:
  * |[
@@ -18413,40 +18534,39 @@
  * g_list_free_full (another_list, g_object_unref);
  * ]|
  *
- * Returns: a full copy of @list, use #g_list_free_full to free it
+ * Returns: the start of the new list that holds a full copy of @list,
+ *     use g_list_free_full() to free it
  * Since: 2.34
  */
 
 
 /**
  * g_list_delete_link:
- * @list: a #GList
+ * @list: a #GList, this must point to the top of the list
  * @link_: node to delete from @list
  *
  * Removes the node link_ from the list and frees it.
  * Compare this to g_list_remove_link() which removes the node
  * without freeing it.
  *
- * Returns: the new head of @list
+ * Returns: the (possibly changed) start of the #GList
  */
 
 
 /**
  * g_list_find:
- * @list: a #GList
+ * @list: a #GList, this must point to the top of the list
  * @data: the element data to find
  *
- * Finds the element in a #GList which
- * contains the given data.
+ * Finds the element in a #GList which contains the given data.
  *
- * Returns: the found #GList element,
- *     or %NULL if it is not found
+ * Returns: the found #GList element, or %NULL if it is not found
  */
 
 
 /**
  * g_list_find_custom:
- * @list: a #GList
+ * @list: a #GList, this must point to the top of the list
  * @data: user data passed to the function
  * @func: the function to call for each element.
  *     It should return 0 when the desired element is found
@@ -18464,7 +18584,7 @@
 
 /**
  * g_list_first:
- * @list: a #GList
+ * @list: any #GList element
  *
  * Gets the first element in a #GList.
  *
@@ -18475,7 +18595,7 @@
 
 /**
  * g_list_foreach:
- * @list: a #GList
+ * @list: a #GList, this must point to the top of the list
  * @func: the function to call with each element's data
  * @user_data: user data to pass to the function
  *
@@ -18488,7 +18608,7 @@
  * @list: a #GList
  *
  * Frees all of the memory used by a #GList.
- * The freed elements are returned to the slice allocator.
+ * The freed elements are returned to the slice allocator
  *
  * <note><para>
  * If list elements contain dynamically-allocated memory,
@@ -18519,8 +18639,8 @@
  * @list: a pointer to a #GList
  * @free_func: the function to be called to free each element's data
  *
- * Convenience method, which frees all the memory used by a #GList, and
- * calls the specified destroy function on every element's data.
+ * Convenience method, which frees all the memory used by a #GList,
+ * and calls @free_func on every element's data.
  *
  * Since: 2.28
  */
@@ -18528,7 +18648,7 @@
 
 /**
  * g_list_index:
- * @list: a #GList
+ * @list: a #GList, this must point to the top of the list
  * @data: the data to find
  *
  * Gets the position of the element containing
@@ -18541,7 +18661,7 @@
 
 /**
  * g_list_insert:
- * @list: a pointer to a #GList
+ * @list: a pointer to a #GList, this must point to the top of the list
  * @data: the data for the new element
  * @position: the position to insert the element. If this is
  *     negative, or is larger than the number of elements in the
@@ -18549,26 +18669,27 @@
  *
  * Inserts a new element into the list at the given position.
  *
- * Returns: the new start of the #GList
+ * Returns: the (possibly changed) start of the #GList
  */
 
 
 /**
  * g_list_insert_before:
- * @list: a pointer to a #GList
+ * @list: a pointer to a #GList, this must point to the top of the list
  * @sibling: the list element before which the new element
  *     is inserted or %NULL to insert at the end of the list
  * @data: the data for the new element
  *
  * Inserts a new element into the list before the given position.
  *
- * Returns: the new start of the #GList
+ * Returns: the (possibly changed) start of the #GList
  */
 
 
 /**
  * g_list_insert_sorted:
- * @list: a pointer to a #GList
+ * @list: a pointer to a #GList, this must point to the top of the
+ *     already sorted list
  * @data: the data for the new element
  * @func: the function to compare elements in the list. It should
  *     return a number > 0 if the first parameter comes after the
@@ -18577,30 +18698,45 @@
  * Inserts a new element into the list, using the given comparison
  * function to determine its position.
  *
- * Returns: the new start of the #GList
+ * <note><para>
+ * If you are adding many new elements to a list, and the number of
+ * new elements is much larger than the length of the list, use
+ * g_list_prepend() to add the new items and sort the list afterwards
+ * with g_list_sort()
+ * </para></note>
+ *
+ * Returns: the (possibly changed) start of the #GList
  */
 
 
 /**
  * g_list_insert_sorted_with_data:
- * @list: a pointer to a #GList
+ * @list: a pointer to a #GList, this must point to the top of the
+ *     already sorted list
  * @data: the data for the new element
- * @func: the function to compare elements in the list.
- *     It should return a number > 0 if the first parameter
- *     comes after the second parameter in the sort order.
- * @user_data: user data to pass to comparison function.
+ * @func: the function to compare elements in the list. It should
+ *     return a number > 0 if the first parameter  comes after the
+ *     second parameter in the sort order.
+ * @user_data: user data to pass to comparison function
  *
  * Inserts a new element into the list, using the given comparison
  * function to determine its position.
  *
- * Returns: the new start of the #GList
+ * <note><para>
+ * If you are adding many new elements to a list, and the number of
+ * new elements is much larger than the length of the list, use
+ * g_list_prepend() to add the new items and sort the list afterwards
+ * with g_list_sort()
+ * </para></note>
+ *
+ * Returns: the (possibly changed) start of the #GList
  * Since: 2.10
  */
 
 
 /**
  * g_list_last:
- * @list: a #GList
+ * @list: any #GList element
  *
  * Gets the last element in a #GList.
  *
@@ -18611,13 +18747,14 @@
 
 /**
  * g_list_length:
- * @list: a #GList
+ * @list: a #GList, this must point to the top of the list
  *
  * Gets the number of elements in a #GList.
  *
  * <note><para>
- * This function iterates over the whole list to
- * count its elements.
+ * This function iterates over the whole list to count its elements.
+ * Use a <link linkend="glib-Double-ended-Queues">GQueue</link> instead
+ * of a GList if you regularly need the number of items.
  * </para></note>
  *
  * Returns: the number of elements in the #GList
@@ -18626,17 +18763,19 @@
 
 /**
  * g_list_next:
- * @list: an element in a #GList.
+ * @list: an element in a #GList
  *
  * A convenience macro to get the next element in a #GList.
+ * Note that it is considered perfectly acceptable to access
+ * @list->next directly.
  *
- * Returns: the next element, or %NULL if there are no more elements.
+ * Returns: the next element, or %NULL if there are no more elements
  */
 
 
 /**
  * g_list_nth:
- * @list: a #GList
+ * @list: a #GList, this must point to the top of the list
  * @n: the position of the element, counting from 0
  *
  * Gets the element at the given position in a #GList.
@@ -18648,7 +18787,7 @@
 
 /**
  * g_list_nth_data:
- * @list: a #GList
+ * @list: a #GList, this must point to the top of the list
  * @n: the position of the element
  *
  * Gets the data of the element at the given position.
@@ -18672,7 +18811,7 @@
 
 /**
  * g_list_position:
- * @list: a #GList
+ * @list: a #GList, this must point to the top of the list
  * @llink: an element in the #GList
  *
  * Gets the position of the given element
@@ -18685,54 +18824,61 @@
 
 /**
  * g_list_prepend:
- * @list: a pointer to a #GList
+ * @list: a pointer to a #GList, this must point to the top of the list
  * @data: the data for the new element
  *
- * Adds a new element on to the start of the list.
+ * Prepends a new element on to the start of the list.
  *
- * <note><para>
- * The return value is the new start of the list, which
- * may have changed, so make sure you store the new value.
- * </para></note>
+ * Note that the return value is the new start of the list,
+ * which will have changed, so make sure you store the new value.
  *
  * |[
  * /&ast; Notice that it is initialized to the empty list. &ast;/
  * GList *list = NULL;
+ *
  * list = g_list_prepend (list, "last");
  * list = g_list_prepend (list, "first");
  * ]|
  *
- * Returns: the new start of the #GList
+ * <note><para>
+ * Do not use this function to prepend a new element to a different element
+ * than the start of the list. Use g_list_insert_before() instead.
+ * </para></note>
+ *
+ * Returns: a pointer to the newly prepended element, which is the new
+ *     start of the #GList
  */
 
 
 /**
  * g_list_previous:
- * @list: an element in a #GList.
+ * @list: an element in a #GList
  *
  * A convenience macro to get the previous element in a #GList.
+ * Note that it is considered perfectly acceptable to access
+ * @list->previous directly.
  *
  * Returns: the previous element, or %NULL if there are no previous
- *          elements.
+ *          elements
  */
 
 
 /**
  * g_list_remove:
- * @list: a #GList
+ * @list: a #GList, this must point to the top of the list
  * @data: the data of the element to remove
  *
  * Removes an element from a #GList.
  * If two elements contain the same data, only the first is removed.
  * If none of the elements contain the data, the #GList is unchanged.
  *
- * Returns: the new start of the #GList
+ * Returns: the (possibly changed) start of the #GList
  */
 
 
 /**
  * g_list_remove_all:
- * @list: a #GList
+ * @list: a #GList, this must point to the top of the list
  * @data: data to remove
  *
  * Removes all list nodes with data equal to @data.
@@ -18740,26 +18886,35 @@
  * g_list_remove() which removes only the first node
  * matching the given data.
  *
- * Returns: new head of @list
+ * Returns: the (possibly changed) start of the #GList
  */
 
 
 /**
  * g_list_remove_link:
- * @list: a #GList
+ * @list: a #GList, this must point to the top of the list
  * @llink: an element in the #GList
  *
  * Removes an element from a #GList, without freeing the element.
  * The removed element's prev and next links are set to %NULL, so
  * that it becomes a self-contained list with one element.
  *
- * Returns: the new start of the #GList, without the element
+ * This function is for example used to move an element in the list
+ * (see the example for g_list_concat()) or to remove an element in
+ * the list before freeing its data:
+ * |[
+ * list = g_list_remove_link (list, llink);
+ * free_some_data_that_may_access_the_list_again (llink->data);
+ * g_list_free (llink);
+ * ]|
+ *
+ * Returns: the (possibly changed) start of the #GList
  */
 
 
 /**
  * g_list_reverse:
- * @list: a #GList
+ * @list: a #GList, this must point to the top of the list
  *
  * Reverses a #GList.
  * It simply switches the next and prev pointers of each element.
@@ -18770,7 +18925,7 @@
 
 /**
  * g_list_sort:
- * @list: a #GList
+ * @list: a #GList, this must point to the top of the list
  * @compare_func: the comparison function used to sort the #GList.
  *     This function is passed the data from 2 elements of the #GList
  *     and should return 0 if they are equal, a negative value if the
@@ -18780,20 +18935,20 @@
  * Sorts a #GList using the given comparison function. The algorithm
  * used is a stable sort.
  *
- * Returns: the start of the sorted #GList
+ * Returns: the (possibly changed) start of the #GList
  */
 
 
 /**
  * g_list_sort_with_data:
- * @list: a #GList
+ * @list: a #GList, this must point to the top of the list
  * @compare_func: comparison function
  * @user_data: user data to pass to comparison function
  *
  * Like g_list_sort(), but the comparison function accepts
  * a user data argument.
  *
- * Returns: the new head of @list
+ * Returns: the (possibly changed) start of the #GList
  */
 
 
@@ -21666,6 +21821,36 @@
 
 
 /**
+ * g_option_context_parse_strv:
+ * @context: a #GOptionContext
+ * @arguments: (inout) (array null-terminated=1): a pointer to the
+ *    command line arguments (which must be in UTF-8 on Windows)
+ * @error: a return location for errors
+ *
+ * Parses the command line arguments.
+ *
+ * This function is similar to g_option_context_parse() except that it
+ * respects the normal memory rules when dealing with a strv instead of
+ * assuming that the passed-in array is the argv of the main function.
+ *
+ * In particular, strings that are removed from the arguments list will
+ * be freed using g_free().
+ *
+ * On Windows, the strings are expected to be in UTF-8.  This is in
+ * contrast to g_option_context_parse() which expects them to be in the
+ * system codepage, which is how they are passed as @argv to main().
+ * See g_win32_get_command_line() for a solution.
+ *
+ * This function is useful if you are trying to use #GOptionContext with
+ * #GApplication.
+ *
+ * Returns: %TRUE if the parsing was successful,
+ *          %FALSE if an error occurred
+ * Since: 2.40
+ */
+
+
+/**
  * g_option_context_set_description:
  * @context: a #GOptionContext
  * @description: (allow-none): a string to be shown in <option>--help</option> output
@@ -22694,7 +22879,7 @@
  * queue consist of pointers to data, the pointers are copied, but the
  * actual data is not.
  *
- * Returns: A copy of @queue
+ * Returns: a copy of @queue
  * Since: 2.4
  */
 
@@ -22719,7 +22904,7 @@
  *
  * Finds the first link in @queue which contains @data.
  *
- * Returns: The first link in @queue which contains @data.
+ * Returns: the first link in @queue which contains @data
  * Since: 2.4
  */
 
@@ -22729,7 +22914,7 @@
  * @queue: a #GQueue
  * @data: user data passed to @func
  * @func: a #GCompareFunc to call for each element. It should return 0
- * when the desired element is found
+ *     when the desired element is found
  *
  * Finds an element in a #GQueue, using a supplied function to find the
  * desired element. It iterates over the queue, calling the given function
@@ -22737,7 +22922,7 @@
  * takes two gconstpointer arguments, the #GQueue element's data as the
  * first argument and the given user data as the second argument.
  *
- * Returns: The found link, or %NULL if it wasn't found
+ * Returns: the found link, or %NULL if it wasn't found
  * Since: 2.4
  */
 
@@ -22757,10 +22942,10 @@
 
 /**
  * g_queue_free:
- * @queue: a #GQueue.
+ * @queue: a #GQueue
  *
- * Frees the memory allocated for the #GQueue. Only call this function if
- * @queue was created with g_queue_new(). If queue elements contain
+ * Frees the memory allocated for the #GQueue. Only call this function
+ * if @queue was created with g_queue_new(). If queue elements contain
  * dynamically-allocated memory, they should be freed first.
  *
  * <note><para>
@@ -22776,8 +22961,8 @@
  * @queue: a pointer to a #GQueue
  * @free_func: the function to be called to free each element's data
  *
- * Convenience method, which frees all the memory used by a #GQueue, and
- * calls the specified destroy function on every element's data.
+ * Convenience method, which frees all the memory used by a #GQueue,
+ * and calls the specified destroy function on every element's data.
  *
  * Since: 2.32
  */
@@ -22789,7 +22974,7 @@
  *
  * Returns the number of items in @queue.
  *
- * Returns: The number of items in @queue.
+ * Returns: the number of items in @queue
  * Since: 2.4
  */
 
@@ -22797,11 +22982,12 @@
 /**
  * g_queue_index:
  * @queue: a #GQueue
- * @data: the data to find.
+ * @data: the data to find
  *
  * Returns the position of the first element in @queue which contains @data.
  *
- * Returns: The position of the first element in @queue which contains @data, or -1 if no element in @queue contains @data.
+ * Returns: the position of the first element in @queue which
+ *     contains @data, or -1 if no element in @queue contains @data
  * Since: 2.4
  */
 
@@ -22856,7 +23042,7 @@
  *     return 0 if the elements are equal, a negative value if the first
  *     element comes before the second, and a positive value if the second
  *     element comes before the first.
- * @user_data: user data passed to @func.
+ * @user_data: user data passed to @func
  *
  * Inserts @data into @queue using @func to determine the new position.
  *
@@ -22870,19 +23056,19 @@
  *
  * Returns %TRUE if the queue is empty.
  *
- * Returns: %TRUE if the queue is empty.
+ * Returns: %TRUE if the queue is empty
  */
 
 
 /**
  * g_queue_link_index:
  * @queue: a #GQueue
- * @link_: A #GList link
+ * @link_: a #GList link
  *
  * Returns the position of @link_ in @queue.
  *
- * Returns: The position of @link_, or -1 if the link is
- * not part of @queue
+ * Returns: the position of @link_, or -1 if the link is
+ *     not part of @queue
  * Since: 2.4
  */
 
@@ -22892,18 +23078,18 @@
  *
  * Creates a new #GQueue.
  *
- * Returns: a new #GQueue.
+ * Returns: a newly allocated #GQueue
  */
 
 
 /**
  * g_queue_peek_head:
- * @queue: a #GQueue.
+ * @queue: a #GQueue
  *
  * Returns the first element of the queue.
  *
- * Returns: the data of the first element in the queue, or %NULL if the queue
- *   is empty.
+ * Returns: the data of the first element in the queue, or %NULL
+ *     if the queue is empty
  */
 
 
@@ -22911,7 +23097,7 @@
  * g_queue_peek_head_link:
  * @queue: a #GQueue
  *
- * Returns the first link in @queue
+ * Returns the first link in @queue.
  *
  * Returns: the first link in @queue, or %NULL if @queue is empty
  * Since: 2.4
@@ -22921,12 +23107,12 @@
 /**
  * g_queue_peek_nth:
  * @queue: a #GQueue
- * @n: the position of the element.
+ * @n: the position of the element
  *
  * Returns the @n'th element of @queue.
  *
- * Returns: The data for the @n'th element of @queue, or %NULL if @n is
- *   off the end of @queue.
+ * Returns: the data for the @n'th element of @queue,
+ *     or %NULL if @n is off the end of @queue
  * Since: 2.4
  */
 
@@ -22938,20 +23124,20 @@
  *
  * Returns the link at the given position
  *
- * Returns: The link at the @n'th position, or %NULL if @n is off the
- * end of the list
+ * Returns: the link at the @n'th position, or %NULL
+ *     if @n is off the end of the list
  * Since: 2.4
  */
 
 
 /**
  * g_queue_peek_tail:
- * @queue: a #GQueue.
+ * @queue: a #GQueue
  *
  * Returns the last element of the queue.
  *
- * Returns: the data of the last element in the queue, or %NULL if the queue
- *   is empty.
+ * Returns: the data of the last element in the queue, or %NULL
+ *     if the queue is empty
  */
 
 
@@ -22959,7 +23145,7 @@
  * g_queue_peek_tail_link:
  * @queue: a #GQueue
  *
- * Returns the last link @queue.
+ * Returns the last link in @queue.
  *
  * Returns: the last link in @queue, or %NULL if @queue is empty
  * Since: 2.4
@@ -22968,34 +23154,34 @@
 
 /**
  * g_queue_pop_head:
- * @queue: a #GQueue.
+ * @queue: a #GQueue
  *
- * Removes the first element of the queue.
+ * Removes the first element of the queue and returns its data.
  *
- * Returns: the data of the first element in the queue, or %NULL if the queue
- *   is empty.
+ * Returns: the data of the first element in the queue, or %NULL
+ *     if the queue is empty
  */
 
 
 /**
  * g_queue_pop_head_link:
- * @queue: a #GQueue.
+ * @queue: a #GQueue
  *
- * Removes the first element of the queue.
+ * Removes and returns the first element of the queue.
  *
- * Returns: the #GList element at the head of the queue, or %NULL if the queue
- *   is empty.
+ * Returns: the #GList element at the head of the queue, or %NULL
+ *     if the queue is empty
  */
 
 
 /**
  * g_queue_pop_nth:
  * @queue: a #GQueue
- * @n: the position of the element.
+ * @n: the position of the element
  *
- * Removes the @n'th element of @queue.
+ * Removes the @n'th element of @queue and returns its data.
  *
- * Returns: the element's data, or %NULL if @n is off the end of @queue.
+ * Returns: the element's data, or %NULL if @n is off the end of @queue
  * Since: 2.4
  */
 
@@ -23007,30 +23193,30 @@
  *
  * Removes and returns the link at the given position.
  *
- * Returns: The @n'th link, or %NULL if @n is off the end of @queue.
+ * Returns: the @n'th link, or %NULL if @n is off the end of @queue
  * Since: 2.4
  */
 
 
 /**
  * g_queue_pop_tail:
- * @queue: a #GQueue.
+ * @queue: a #GQueue
  *
- * Removes the last element of the queue.
+ * Removes the last element of the queue and returns its data.
  *
- * Returns: the data of the last element in the queue, or %NULL if the queue
- *   is empty.
+ * Returns: the data of the last element in the queue, or %NULL
+ *     if the queue is empty
  */
 
 
 /**
  * g_queue_pop_tail_link:
- * @queue: a #GQueue.
+ * @queue: a #GQueue
  *
- * Removes the last element of the queue.
+ * Removes and returns the last element of the queue.
  *
- * Returns: the #GList element at the tail of the queue, or %NULL if the queue
- *   is empty.
+ * Returns: the #GList element at the tail of the queue, or %NULL
+ *     if the queue is empty
  */
 
 
@@ -23045,9 +23231,9 @@
 
 /**
  * g_queue_push_head_link:
- * @queue: a #GQueue.
+ * @queue: a #GQueue
  * @link_: a single #GList element, <emphasis>not</emphasis> a list with
- *     more than one element.
+ *     more than one element
  *
  * Adds a new element at the head of the queue.
  */
@@ -23061,7 +23247,7 @@
  *     larger than the number of elements in the @queue, the element is
  *     added to the end of the queue.
  *
- * Inserts a new element into @queue at the given position
+ * Inserts a new element into @queue at the given position.
  *
  * Since: 2.4
  */
@@ -23083,8 +23269,8 @@
 
 /**
  * g_queue_push_tail:
- * @queue: a #GQueue.
- * @data: the data for the new element.
+ * @queue: a #GQueue
+ * @data: the data for the new element
  *
  * Adds a new element at the tail of the queue.
  */
@@ -23092,9 +23278,9 @@
 
 /**
  * g_queue_push_tail_link:
- * @queue: a #GQueue.
+ * @queue: a #GQueue
  * @link_: a single #GList element, <emphasis>not</emphasis> a list with
- *   more than one element.
+ *   more than one element
  *
  * Adds a new element at the tail of the queue.
  */
@@ -23103,7 +23289,7 @@
 /**
  * g_queue_remove:
  * @queue: a #GQueue
- * @data: data to remove.
+ * @data: the data to remove
  *
  * Removes the first element in @queue that contains @data.
  *
@@ -23115,7 +23301,7 @@
 /**
  * g_queue_remove_all:
  * @queue: a #GQueue
- * @data: data to remove
+ * @data: the data to remove
  *
  * Remove all elements whose data equals @data from @queue.
  *
@@ -23157,7 +23343,7 @@
  * Unlinks @link_ so that it will no longer be part of @queue. The link is
  * not freed.
  *
- * @link_ must be part of @queue,
+ * @link_ must be part of @queue.
  *
  * Since: 2.4
  */
@@ -27299,7 +27485,7 @@
  * improve the transliteration if the language of the source string is
  * known.
  *
- * Returns: the folded tokens
+ * Returns: (transfer full) (array zero-terminated=1): the folded tokens
  * Since: 2.40
  */
 
@@ -27344,12 +27530,14 @@
  * Removes trailing whitespace from a string.
  *
  * This function doesn't allocate or reallocate any memory;
- * it modifies @string in place. The pointer to @string is
- * returned to allow the nesting of functions.
+ * it modifies @string in place. Therefore, it cannot be used
+ * on statically allocated strings.
+ *
+ * The pointer to @string is returned to allow the nesting of functions.
  *
  * Also see g_strchug() and g_strstrip().
  *
- * Returns: @string.
+ * Returns: @string
  */
 
 
@@ -27361,8 +27549,10 @@
  * of the characters forward.
  *
  * This function doesn't allocate or reallocate any memory;
- * it modifies @string in place. The pointer to @string is
- * returned to allow the nesting of functions.
+ * it modifies @string in place. Therefore, it cannot be used on
+ * statically allocated strings.
+ *
+ * The pointer to @string is returned to allow the nesting of functions.
  *
  * Also see g_strchomp() and g_strstrip().
  *
@@ -28643,7 +28833,7 @@
  *
  * In order for this function to work in srcdir != builddir situations,
  * the G_TEST_SRCDIR and G_TEST_BUILDDIR environment variables need to
- * have been defined.  As of 2.38, this is done by the Makefile.decl
+ * have been defined.  As of 2.38, this is done by the glib.mk
  * included in GLib.  Please ensure that your copy is up to date before
  * using this function.
  *
@@ -29203,6 +29393,28 @@
  * g_test_run_suite() or g_test_run() may only be called once
  * in a program.
  *
+ * In general, the tests and sub-suites within each suite are run in
+ * the order in which they are defined. However, note that prior to
+ * GLib 2.36, there was a bug in the <literal>g_test_add_*</literal>
+ * functions which caused them to create multiple suites with the same
+ * name, meaning that if you created tests "/foo/simple",
+ * "/bar/simple", and "/foo/using-bar" in that order, they would get
+ * run in that order (since g_test_run() would run the first "/foo"
+ * suite, then the "/bar" suite, then the second "/foo" suite). As of
+ * 2.36, this bug is fixed, and adding the tests in that order would
+ * result in a running order of "/foo/simple", "/foo/using-bar",
+ * "/bar/simple". If this new ordering is sub-optimal (because it puts
+ * more-complicated tests before simpler ones, making it harder to
+ * figure out exactly what has failed), you can fix it by changing the
+ * test paths to group tests by suite in a way that will result in the
+ * desired running order. Eg, "/simple/foo", "/simple/bar",
+ * "/complex/foo-using-bar".
+ *
+ * However, you should never make the actual result of a test depend
+ * on the order that tests are run in. If you need to ensure that some
+ * particular code runs before or after a given test case, use
+ * g_test_add(), which lets you specify setup and teardown functions.
+ *
  * Returns: 0 on success, 1 on failure (assuming it returns at all),
  *   77 if all tests were skipped with g_test_skip().
  * Since: 2.16
@@ -29216,7 +29428,9 @@
  * Execute the tests within @suite and all nested #GTestSuites.
  * The test suites to be executed are filtered according to
  * test path arguments (-p <replaceable>testpath</replaceable>)
- * as parsed by g_test_init().
+ * as parsed by g_test_init(). See the g_test_run() documentation
+ * for more information on the order that tests are run in.
+ *
  * g_test_run_suite() or g_test_run() may only be called once
  * in a program.
  *
@@ -30592,12 +30806,12 @@
 
 /**
  * g_tree_destroy:
- * @tree: a #GTree.
+ * @tree: a #GTree
  *
  * Removes all keys and values from the #GTree and decreases its
  * reference count by one. If keys and/or values are dynamically
  * allocated, you should either free them first or create the #GTree
- * using g_tree_new_full().  In the latter case the destroy functions
+ * using g_tree_new_full(). In the latter case the destroy functions
  * you supplied will be called on all keys and values before destroying
  * the #GTree.
  */
@@ -30605,10 +30819,10 @@
 
 /**
  * g_tree_foreach:
- * @tree: a #GTree.
+ * @tree: a #GTree
  * @func: the function to call for each node visited.
  *     If this function returns %TRUE, the traversal is stopped.
- * @user_data: user data to pass to the function.
+ * @user_data: user data to pass to the function
  *
  * Calls the given function for each of the key/value pairs in the #GTree.
  * The function is passed the key and value of each pair, and the given
@@ -30623,7 +30837,7 @@
 
 /**
  * g_tree_height:
- * @tree: a #GTree.
+ * @tree: a #GTree
  *
  * Gets the height of a #GTree.
  *
@@ -30631,21 +30845,23 @@
  * If the #GTree contains only one root node the height is 1.
  * If the root node has children the height is 2, etc.
  *
- * Returns: the height of the #GTree.
+ * Returns: the height of @tree
  */
 
 
 /**
  * g_tree_insert:
- * @tree: a #GTree.
- * @key: the key to insert.
- * @value: the value corresponding to the key.
+ * @tree: a #GTree
+ * @key: the key to insert
+ * @value: the value corresponding to the key
  *
- * Inserts a key/value pair into a #GTree. If the given key already exists
- * in the #GTree its corresponding value is set to the new value. If you
- * supplied a value_destroy_func when creating the #GTree, the old value is
- * freed using that function. If you supplied a @key_destroy_func when
- * creating the #GTree, the passed key is freed using that function.
+ * Inserts a key/value pair into a #GTree.
+ *
+ * If the given key already exists in the #GTree its corresponding value
+ * is set to the new value. If you supplied a @value_destroy_func when
+ * creating the #GTree, the old value is freed using that function. If
+ * you supplied a @key_destroy_func when creating the #GTree, the passed
+ * key is freed using that function.
  *
  * The tree is automatically 'balanced' as new key/value pairs are added,
  * so that the distance from the root to every leaf is as small as possible.
@@ -30654,31 +30870,31 @@
 
 /**
  * g_tree_lookup:
- * @tree: a #GTree.
- * @key: the key to look up.
+ * @tree: a #GTree
+ * @key: the key to look up
  *
  * Gets the value corresponding to the given key. Since a #GTree is
- * automatically balanced as key/value pairs are added, key lookup is very
- * fast.
+ * automatically balanced as key/value pairs are added, key lookup
+ * is O(log n) (where n is the number of key/value pairs in the tree).
  *
- * Returns: the value corresponding to the key, or %NULL if the key was
- * not found.
+ * Returns: the value corresponding to the key, or %NULL
+ *     if the key was not found.
  */
 
 
 /**
  * g_tree_lookup_extended:
- * @tree: a #GTree.
- * @lookup_key: the key to look up.
- * @orig_key: returns the original key.
- * @value: returns the value associated with the key.
+ * @tree: a #GTree
+ * @lookup_key: the key to look up
+ * @orig_key: returns the original key
+ * @value: returns the value associated with the key
  *
  * Looks up a key in the #GTree, returning the original key and the
- * associated value and a #gboolean which is %TRUE if the key was found. This
- * is useful if you need to free the memory allocated for the original key,
- * for example before calling g_tree_remove().
+ * associated value. This is useful if you need to free the memory
+ * allocated for the original key, for example before calling
+ * g_tree_remove().
  *
- * Returns: %TRUE if the key was found in the #GTree.
+ * Returns: %TRUE if the key was found in the #GTree
  */
 
 
@@ -30692,67 +30908,68 @@
  *
  * Creates a new #GTree.
  *
- * Returns: a new #GTree.
+ * Returns: a newly allocated #GTree
  */
 
 
 /**
  * g_tree_new_full:
- * @key_compare_func: qsort()-style comparison function.
- * @key_compare_data: data to pass to comparison function.
+ * @key_compare_func: qsort()-style comparison function
+ * @key_compare_data: data to pass to comparison function
  * @key_destroy_func: a function to free the memory allocated for the key
  *   used when removing the entry from the #GTree or %NULL if you don't
- *   want to supply such a function.
+ *   want to supply such a function
  * @value_destroy_func: a function to free the memory allocated for the
  *   value used when removing the entry from the #GTree or %NULL if you
- *   don't want to supply such a function.
+ *   don't want to supply such a function
  *
  * Creates a new #GTree like g_tree_new() and allows to specify functions
  * to free the memory allocated for the key and value that get called when
  * removing the entry from the #GTree.
  *
- * Returns: a new #GTree.
+ * Returns: a newly allocated #GTree
  */
 
 
 /**
  * g_tree_new_with_data:
- * @key_compare_func: qsort()-style comparison function.
- * @key_compare_data: data to pass to comparison function.
+ * @key_compare_func: qsort()-style comparison function
+ * @key_compare_data: data to pass to comparison function
  *
  * Creates a new #GTree with a comparison function that accepts user data.
  * See g_tree_new() for more details.
  *
- * Returns: a new #GTree.
+ * Returns: a newly allocated #GTree
  */
 
 
 /**
  * g_tree_nnodes:
- * @tree: a #GTree.
+ * @tree: a #GTree
  *
  * Gets the number of nodes in a #GTree.
  *
- * Returns: the number of nodes in the #GTree.
+ * Returns: the number of nodes in @tree
  */
 
 
 /**
  * g_tree_ref:
- * @tree: a #GTree.
+ * @tree: a #GTree
  *
- * Increments the reference count of @tree by one.  It is safe to call
- * this function from any thread.
+ * Increments the reference count of @tree by one.
+ *
+ * It is safe to call this function from any thread.
  *
- * Returns: the passed in #GTree.
+ * Returns: the passed in #GTree
  * Since: 2.22
  */
 
 
 /**
  * g_tree_remove:
- * @tree: a #GTree.
- * @key: the key to remove.
+ * @tree: a #GTree
+ * @key: the key to remove
  *
  * Removes a key/value pair from a #GTree.
  *
@@ -30761,16 +30978,16 @@
  * make sure that any dynamically allocated values are freed yourself.
  * If the key does not exist in the #GTree, the function does nothing.
  *
- * Returns: %TRUE if the key was found (prior to 2.8, this function returned
- *   nothing)
+ * Returns: %TRUE if the key was found (prior to 2.8, this function
+ *     returned nothing)
  */
 
 
 /**
  * g_tree_replace:
- * @tree: a #GTree.
- * @key: the key to insert.
- * @value: the value corresponding to the key.
+ * @tree: a #GTree
+ * @key: the key to insert
+ * @value: the value corresponding to the key
  *
  * Inserts a new key and value into a #GTree similar to g_tree_insert().
  * The difference is that if the key already exists in the #GTree, it gets
@@ -30800,52 +31017,53 @@
  * @search_func returns 1, searching will proceed among the key/value
  * pairs that have a larger key.
  *
- * Returns: the value corresponding to the found key, or %NULL if
- * the key was not found.
+ * Returns: the value corresponding to the found key, or %NULL
+ *     if the key was not found.
  */
 
 
 /**
  * g_tree_steal:
- * @tree: a #GTree.
- * @key: the key to remove.
+ * @tree: a #GTree
+ * @key: the key to remove
  *
  * Removes a key and its associated value from a #GTree without calling
  * the key and value destroy functions.
  *
  * If the key does not exist in the #GTree, the function does nothing.
  *
- * Returns: %TRUE if the key was found (prior to 2.8, this function returned
- *    nothing)
+ * Returns: %TRUE if the key was found (prior to 2.8, this function
+ *     returned nothing)
  */
 
 
 /**
  * g_tree_traverse:
- * @tree: a #GTree.
+ * @tree: a #GTree
  * @traverse_func: the function to call for each node visited. If this
  *   function returns %TRUE, the traversal is stopped.
  * @traverse_type: the order in which nodes are visited, one of %G_IN_ORDER,
- *   %G_PRE_ORDER and %G_POST_ORDER.
- * @user_data: user data to pass to the function.
+ *   %G_PRE_ORDER and %G_POST_ORDER
+ * @user_data: user data to pass to the function
  *
  * Calls the given function for each node in the #GTree.
  *
- * 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 <link linkend="glib-N-ary-Trees">N-ary Tree</link>.
+ * 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
+ *     <link linkend="glib-N-ary-Trees">N-ary Tree</link>.
  */
 
 
 /**
  * g_tree_unref:
- * @tree: a #GTree.
+ * @tree: a #GTree
  *
- * Decrements the reference count of @tree by one.  If the reference count
- * drops to 0, all keys and values will be destroyed (if destroy
- * functions were specified) and all memory allocated by @tree will be
- * released.
+ * Decrements the reference count of @tree by one.
+ * If the reference count drops to 0, all keys and values will
+ * be destroyed (if destroy functions were specified) and all
+ * memory allocated by @tree will be released.
  *
  * It is safe to call this function from any thread.
  *
@@ -35380,6 +35598,45 @@
 
 
 /**
+ * g_win32_get_command_line:
+ *
+ * Gets the command line arguments, on Windows, in the GLib filename
+ * encoding (ie: UTF-8).
+ *
+ * Normally, on Windows, the command line arguments are passed to main()
+ * in the system codepage encoding.  This prevents passing filenames as
+ * arguments if the filenames contain characters that fall outside of
+ * this codepage.  If such filenames are passed, then substitutions
+ * will occur (such as replacing some characters with '?').
+ *
+ * GLib's policy of using UTF-8 as a filename encoding on Windows was
+ * designed to localise the pain of dealing with filenames outside of
+ * the system codepage to one area: dealing with commandline arguments
+ * in main().
+ *
+ * As such, most GLib programs should ignore the value of argv passed to
+ * their main() function and call g_win32_get_command_line() instead.
+ * This will get the "full Unicode" commandline arguments using
+ * GetCommandLineW() and convert it to the GLib filename encoding (which
+ * is UTF-8 on Windows).
+ *
+ * The strings returned by this function are suitable for use with
+ * functions such as g_open() and g_file_new_for_commandline_arg() but
+ * are not suitable for use with g_option_context_parse(), which assumes
+ * that its input will be in the system codepage.  The return value is
+ * suitable for use with g_option_context_parse_strv(), however, which
+ * is a better match anyway because it won't leak memory.
+ *
+ * Unlike argv, the returned value is a normal strv and can (and should)
+ * be freed with g_strfreev() when no longer needed.
+ *
+ * Returns: (transfer full): the commandline arguments in the GLib
+ *   filename encoding (ie: UTF-8)
+ * Since: 2.40
+ */
+
+
+/**
  * g_win32_get_package_installation_directory:
  * @package: (allow-none): You should pass %NULL for this.
  * @dll_name: (allow-none): The name of a DLL that a package provides in UTF-8, or %NULL.
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index a5cd41ab..c519b7c5 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -2531,7 +2531,8 @@
  * @notify: a function to call when this reference is the
  *  last reference to the object, or is no longer
  *  the last reference.
- * @data: data to pass to @notify
+ * @data: (allow-none): data to pass to @notify, or %NULL to
+ *  match any toggle refs with the @notify argument.
  *
  * Removes a reference added with g_object_add_toggle_ref(). The
  * reference count of the object is decreased by one.
@@ -6215,7 +6216,9 @@
  * @dest_type: Target type.
  *
  * Check whether g_value_transform() is able to transform values
- * of type @src_type into values of type @dest_type.
+ * of type @src_type into values of type @dest_type. Note that for
+ * the types to be transformable, they must be compatible and a
+ * transform function must be registered.
  *
  * Returns: %TRUE if the transformation is possible, %FALSE otherwise.
  */