[introspection] Move over annotations

Move all the annotations over from gobject-introspection.

They will not be used directly by the introspection scanner for now,
instead they will be extracted by a script and updated manually
until introspection is properly integrated into the glib build

18 files changed, 57 insertions, 51 deletions

diff --git a/gio/gaction.c b/gio/gaction.c
index f8b8a2c0c..37b46fbc7 100644
--- a/gio/gaction.c
+++ b/gio/gaction.c
@@ -199,7 +199,7 @@ g_action_set_state (GAction  *action,
  * The return value (if non-%NULL) should be freed with
  * g_variant_unref() when it is no longer required.
  *
- * Returns: (allow-none): the current state of the action
+ * Returns: (transfer full): the current state of the action
  *
  * Since: 2.26
  **/
@@ -310,7 +310,7 @@ g_action_get_state_type (GAction *action)
  * The return value (if non-%NULL) should be freed with
  * g_variant_unref() when it is no longer required.
  *
- * Returns: (allow-none): the state range hint
+ * Returns: (transfer full): the state range hint
  *
  * Since: 2.26
  **/
diff --git a/gio/gactiongroup.c b/gio/gactiongroup.c
index d60ba9027..1ee824f22 100644
--- a/gio/gactiongroup.c
+++ b/gio/gactiongroup.c
@@ -160,7 +160,8 @@ g_action_group_default_init (GActionGroupInterface *class)
  * The caller is responsible for freeing the list with g_strfreev() when
  * it is no longer required.
  *
- * Returns: a %NULL-terminated array of the names of the actions in the group
+ * Returns: (transfer full): a %NULL-terminated array of the names of the
+ * actions in the groupb
  *
  * Since: 2.26
  **/
@@ -248,7 +249,7 @@ g_action_group_get_parameter_type (GActionGroup *action_group,
  * possible for an action to be removed and for a new action to be added
  * with the same name but a different state type.
  *
- * Returns: (allow-none): the state type, if the action is stateful
+ * Returns: (transfer full): the state type, if the action is stateful
  *
  * Since: 2.26
  **/
@@ -286,7 +287,7 @@ g_action_group_get_state_type (GActionGroup *action_group,
  * The return value (if non-%NULL) should be freed with
  * g_variant_unref() when it is no longer required.
  *
- * Return value: the state range hint
+ * Return value: (transfer full): the state range hint
  *
  * Since: 2.26
  **/
diff --git a/gio/gappinfo.c b/gio/gappinfo.c
index 93dcbb712..a95315817 100644
--- a/gio/gappinfo.c
+++ b/gio/gappinfo.c
@@ -100,7 +100,7 @@ g_app_info_default_init (GAppInfoInterface *iface)
  * 
  * Creates a duplicate of a #GAppInfo.
  *
- * Returns: a duplicate of @appinfo.
+ * Returns: (transfer full): a duplicate of @appinfo.
  **/
 GAppInfo *
 g_app_info_dup (GAppInfo *appinfo)
@@ -732,7 +732,7 @@ g_app_launch_context_init (GAppLaunchContext *launch_context)
  * g_app_launch_context_get_display:
  * @context: a #GAppLaunchContext
  * @info: a #GAppInfo
- * @files: a #GList of #GFile objects
+ * @files: (element-type GFile): a #GList of #GFile objects
  *
  * Gets the display string for the @context. This is used to ensure new
  * applications are started on the same display as the launching
@@ -762,7 +762,7 @@ g_app_launch_context_get_display (GAppLaunchContext *context,
  * g_app_launch_context_get_startup_notify_id:
  * @context: a #GAppLaunchContext
  * @info: a #GAppInfo
- * @files: a #GList of of #GFile objects
+ * @files: (element-type GFile): a #GList of of #GFile objects
  * 
  * Initiates startup notification for the application and returns the
  * <envvar>DESKTOP_STARTUP_ID</envvar> for the launched operation,
diff --git a/gio/gasyncinitable.c b/gio/gasyncinitable.c
index 2e8a16a2c..64a89c202 100644
--- a/gio/gasyncinitable.c
+++ b/gio/gasyncinitable.c
@@ -437,7 +437,7 @@ g_async_initable_new_valist_async (GType                object_type,
  * Finishes the async construction for the various g_async_initable_new calls,
  * returning the created object or %NULL on error.
  *
- * Returns: a newly created #GObject, or %NULL on error. Free with
+ * Returns: (transfer full): a newly created #GObject, or %NULL on error. Free with
  *     g_object_unref().
  *
  * Since: 2.22
diff --git a/gio/gcontenttype.c b/gio/gcontenttype.c
index cc74cbfa0..e745b275d 100644
--- a/gio/gcontenttype.c
+++ b/gio/gcontenttype.c
@@ -1066,7 +1066,7 @@ enumerate_mimetypes_dir (const char *dir,
  * g_list_free (list);
  * </programlisting>
  *
- * Returns: #GList of the registered content types
+ * Returns: (element-type utf8) (transfer full): #GList of the registered content types
  */
 GList *
 g_content_types_get_registered (void)
diff --git a/gio/gdesktopappinfo.c b/gio/gdesktopappinfo.c
index 8aa87385c..0c0f8f23e 100644
--- a/gio/gdesktopappinfo.c
+++ b/gio/gdesktopappinfo.c
@@ -1635,7 +1635,7 @@ g_desktop_app_info_delete (GAppInfo *appinfo)
  *
  * Creates a new #GAppInfo from the given information.
  *
- * Returns: new #GAppInfo for given command.
+ * Returns: (transfer full): new #GAppInfo for given command.
  **/
 GAppInfo *
 g_app_info_create_from_commandline (const char           *commandline,
diff --git a/gio/gemblemedicon.c b/gio/gemblemedicon.c
index 9a8073749..5b5a158fa 100644
--- a/gio/gemblemedicon.c
+++ b/gio/gemblemedicon.c
@@ -146,7 +146,8 @@ g_emblemed_icon_get_icon (GEmblemedIcon *emblemed)
  *
  * Gets the list of emblems for the @icon.
  *
- * Returns: a #GList of #GEmblem <!-- -->s that is owned by @emblemed
+ * Returns: (element-type utf8) (transfer none): a #GList of #GEmblem <!-- -->s that
+ * is owned by @emblemed
  *
  * Since: 2.18
  **/
diff --git a/gio/gfile.c b/gio/gfile.c
index b97ada27a..dac697633 100644
--- a/gio/gfile.c
+++ b/gio/gfile.c
@@ -521,7 +521,7 @@ g_file_get_parse_name (GFile *file)
  *
  * This call does no blocking i/o.
  * 
- * Returns: a new #GFile that is a duplicate of the given #GFile. 
+ * Returns: (transfer full): a new #GFile that is a duplicate of the given #GFile. 
  **/
 GFile *
 g_file_dup (GFile *file)
@@ -675,7 +675,7 @@ g_file_has_parent (GFile *file,
  *
  * This call does no blocking i/o.
  * 
- * Returns: a #GFile to a child specified by @name.
+ * Returns: (transfer full): a #GFile to a child specified by @name.
  *     Free the returned object with g_object_unref().
  **/
 GFile *
@@ -702,7 +702,7 @@ g_file_get_child (GFile      *file,
  * 
  * This call does no blocking i/o.
  * 
- * Returns: a #GFile to the specified child, or 
+ * Returns: (transfer full): a #GFile to the specified child, or 
  *     %NULL if the display name couldn't be converted.  
  *     Free the returned object with g_object_unref().
  **/
@@ -843,7 +843,7 @@ g_file_resolve_relative_path (GFile      *file,
  * If the file is not a directory, the G_FILE_ERROR_NOTDIR error will be returned.
  * Other errors are possible too.
  *
- * Returns: A #GFileEnumerator if successful, %NULL on error. 
+ * Returns: (transfer full): A #GFileEnumerator if successful, %NULL on error. 
  *     Free the returned object with g_object_unref().
  **/
 GFileEnumerator *
@@ -928,7 +928,7 @@ g_file_enumerate_children_async (GFile               *file,
  * Finishes an async enumerate children operation.
  * See g_file_enumerate_children_async().
  *
- * Returns: a #GFileEnumerator or %NULL if an error occurred.
+ * Returns: (transfer full): a #GFileEnumerator or %NULL if an error occurred.
  *     Free the returned object with g_object_unref().
  **/
 GFileEnumerator *
@@ -4730,7 +4730,7 @@ g_file_monitor_directory (GFile             *file,
  * triggering the cancellable object from another thread. If the operation
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
- * Returns: a #GFileMonitor for the given @file, or %NULL on error.
+ * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error.
  *     Free the returned object with g_object_unref().
  **/
 GFileMonitor*
@@ -5889,7 +5889,7 @@ g_file_real_copy_finish (GFile        *file,
  * fails, but the returned object might not support any I/O
  * operation if @path is malformed.
  * 
- * Returns: a new #GFile for the given @path. 
+ * Returns: (transfer full): a new #GFile for the given @path. 
  **/
 GFile *
 g_file_new_for_path (const char *path)
@@ -5908,7 +5908,7 @@ g_file_new_for_path (const char *path)
  * operation if @uri is malformed or if the uri type is 
  * not supported.
  * 
- * Returns: a #GFile for the given @uri.
+ * Returns: (transfer full): a #GFile for the given @uri.
  **/ 
 GFile *
 g_file_new_for_uri (const char *uri)
@@ -5926,7 +5926,7 @@ g_file_new_for_uri (const char *uri)
  * This operation never fails, but the returned object might not support any I/O
  * operation if the @parse_name cannot be parsed.
  * 
- * Returns: a new #GFile.
+ * Returns: (transfer full): a new #GFile.
  **/
 GFile *
 g_file_parse_name (const char *parse_name)
@@ -5972,7 +5972,7 @@ has_valid_scheme (const char *uri)
  * This operation never fails, but the returned object might not support any
  * I/O operation if @arg points to a malformed path.
  *
- * Returns: a new #GFile. 
+ * Returns: (transfer full): a new #GFile. 
  **/
 GFile *
 g_file_new_for_commandline_arg (const char *arg)
@@ -6615,7 +6615,7 @@ g_file_load_contents_finish (GFile         *file,
  *     for the document, or %NULL
  * @make_backup: %TRUE if a backup should be created.
  * @flags: a set of #GFileCreateFlags.
- * @new_etag: a location to a new <link linkend="gfile-etag">entity tag</link>
+ * @new_etag: (allow-none) (out): a location to a new <link linkend="gfile-etag">entity tag</link>
  *      for the document. This should be freed with g_free() when no longer 
  *      needed, or %NULL
  * @cancellable: optional #GCancellable object, %NULL to ignore.
diff --git a/gio/gfileenumerator.c b/gio/gfileenumerator.c
index 41686aa50..b048d6598 100644
--- a/gio/gfileenumerator.c
+++ b/gio/gfileenumerator.c
@@ -185,7 +185,7 @@ g_file_enumerator_init (GFileEnumerator *enumerator)
  * enumerator is at the end, %NULL will be returned and @error will
  * be unset.
  *
- * Return value: A #GFileInfo or %NULL on error or end of enumerator.
+ * Return value: (transfer full): A #GFileInfo or %NULL on error or end of enumerator.
  *    Free the returned object with g_object_unref() when no longer needed.
  **/
 GFileInfo *
@@ -586,7 +586,7 @@ g_file_enumerator_set_pending (GFileEnumerator *enumerator,
  *
  * Get the #GFile container which is being enumerated.
  *
- * Returns: the #GFile which is being enumerated.
+ * Returns: (transfer full): the #GFile which is being enumerated.
  *
  * Since: 2.18
  */
diff --git a/gio/giomodule.c b/gio/giomodule.c
index 83f4cc788..61c3659e1 100644
--- a/gio/giomodule.c
+++ b/gio/giomodule.c
@@ -411,7 +411,8 @@ g_io_modules_scan_all_in_directory (const char *dirname)
  * all gtypes) then you can use g_io_modules_scan_all_in_directory()
  * which allows delayed/lazy loading of modules.
  *
- * Returns: a list of #GIOModules loaded from the directory,
+ * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded
+ *      from the directory,
  *      All the modules are loaded into memory, if you want to
  *      unload them (enabling on-demand loading) you must call
  *      g_type_module_unuse() on all the modules. Free the list
diff --git a/gio/gmount.c b/gio/gmount.c
index 402dabdbf..685d86251 100644
--- a/gio/gmount.c
+++ b/gio/gmount.c
@@ -122,7 +122,7 @@ g_mount_default_init (GMountInterface *iface)
  * 
  * Gets the root directory on @mount.
  * 
- * Returns: a #GFile. 
+ * Returns: (transfer full): a #GFile. 
  *      The returned object should be unreffed with 
  *      g_object_unref() when no longer needed.
  **/
@@ -197,7 +197,7 @@ g_mount_get_name (GMount *mount)
  * 
  * Gets the icon for @mount.
  * 
- * Returns: a #GIcon.
+ * Returns: (transfer full): a #GIcon.
  *      The returned object should be unreffed with 
  *      g_object_unref() when no longer needed.
  **/
@@ -244,7 +244,7 @@ g_mount_get_uuid (GMount *mount)
  * 
  * Gets the volume for the @mount.
  * 
- * Returns: a #GVolume or %NULL if @mount is not associated with a volume.
+ * Returns: (transfer full): a #GVolume or %NULL if @mount is not associated with a volume.
  *      The returned object should be unreffed with 
  *      g_object_unref() when no longer needed.
  **/
@@ -269,7 +269,7 @@ g_mount_get_volume (GMount *mount)
  * This is a convenience method for getting the #GVolume and then
  * using that object to get the #GDrive.
  * 
- * Returns: a #GDrive or %NULL if @mount is not associated with a volume or a drive.
+ * Returns: (transfer full): a #GDrive or %NULL if @mount is not associated with a volume or a drive.
  *      The returned object should be unreffed with 
  *      g_object_unref() when no longer needed.
  **/
diff --git a/gio/gresolver.c b/gio/gresolver.c
index 97daa1b71..5d86323d5 100644
--- a/gio/gresolver.c
+++ b/gio/gresolver.c
@@ -239,7 +239,8 @@ g_resolver_maybe_reload (GResolver *resolver)
  * address, it may be easier to create a #GNetworkAddress and use its
  * #GSocketConnectable interface.
  *
- * Return value: a #GList of #GInetAddress, or %NULL on error. You
+ * Return value: (element-type GInetAddress) (transfer full): a #GList
+ * of #GInetAddress, or %NULL on error. You
  * must unref each of the addresses and free the list when you are
  * done with it. (You can use g_resolver_free_addresses() to do this.)
  *
@@ -341,8 +342,9 @@ g_resolver_lookup_by_name_async (GResolver           *resolver,
  * a value from #GResolverError. If the operation was cancelled,
  * @error will be set to %G_IO_ERROR_CANCELLED.
  *
- * Return value: a #GList of #GInetAddress, or %NULL on error. See
- * g_resolver_lookup_by_name() for more details.
+ * Return value: (element-type GInetAddress) (transfer full): a #GList
+ * of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
+ * for more details.
  *
  * Since: 2.22
  */
@@ -375,7 +377,7 @@ g_resolver_lookup_by_name_finish (GResolver     *resolver,
 }
 
 /**
- * g_resolver_free_addresses:
+ * g_resolver_free_addresses: (skip)
  * @addresses: a #GList of #GInetAddress
  *
  * Frees @addresses (which should be the return value from
@@ -545,9 +547,9 @@ g_resolver_get_service_rrname (const char *service,
  * to create a #GNetworkService and use its #GSocketConnectable
  * interface.
  *
- * Return value: a #GList of #GSrvTarget, or %NULL on error. You must
- * free each of the targets and the list when you are done with it.
- * (You can use g_resolver_free_targets() to do this.)
+ * Return value: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget,
+ * or %NULL on error. You must free each of the targets and the list when you are
+ * done with it. (You can use g_resolver_free_targets() to do this.)
  *
  * Since: 2.22
  */
@@ -633,8 +635,8 @@ g_resolver_lookup_service_async (GResolver           *resolver,
  * a value from #GResolverError. If the operation was cancelled,
  * @error will be set to %G_IO_ERROR_CANCELLED.
  *
- * Return value: a #GList of #GSrvTarget, or %NULL on error. See
- * g_resolver_lookup_service() for more details.
+ * Return value: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget,
+ * or %NULL on error. See g_resolver_lookup_service() for more details.
  *
  * Since: 2.22
  */
@@ -658,7 +660,7 @@ g_resolver_lookup_service_finish (GResolver     *resolver,
 }
 
 /**
- * g_resolver_free_targets:
+ * g_resolver_free_targets: (skip)
  * @targets: a #GList of #GSrvTarget
  *
  * Frees @targets (which should be the return value from
diff --git a/gio/gsettings.c b/gio/gsettings.c
index eb4370cbe..7fc38e27e 100644
--- a/gio/gsettings.c
+++ b/gio/gsettings.c
@@ -1823,13 +1823,14 @@ g_settings_set_boolean (GSettings  *settings,
  * @key: the key to get the value for
  * @returns: a newly-allocated, %NULL-terminated array of strings
  *
- * Gets the value that is stored at @key in @settings.
- *
  * A convenience variant of g_settings_get() for string arrays.
  *
  * It is a programmer error to give a @key that isn't specified as
  * having an array of strings type in the schema for @settings.
  *
+ * Returns: (array zero-terminated=1) (transfer full): the value that is
+ * stored at @key in @settings.
+ *
  * Since: 2.26
  */
 gchar **
@@ -1850,7 +1851,7 @@ g_settings_get_strv (GSettings   *settings,
  * g_settings_set_strv:
  * @settings: a #GSettings object
  * @key: the name of the key to set
- * @value: (allow-none): the value to set it to, or %NULL
+ * @value: (allow-none): (array zero-terminated=1): the value to set it to, or %NULL
  * @returns: %TRUE if setting the key succeeded,
  *     %FALSE if the key was not writable
  *
diff --git a/gio/gsrvtarget.c b/gio/gsrvtarget.c
index 46bbeae0a..5bcf111de 100644
--- a/gio/gsrvtarget.c
+++ b/gio/gsrvtarget.c
@@ -222,7 +222,7 @@ compare_target (gconstpointer a, gconstpointer b)
 }
 
 /**
- * g_srv_target_list_sort:
+ * g_srv_target_list_sort: (skip)
  * @targets: a #GList of #GSrvTarget
  *
  * Sorts @targets in place according to the algorithm in RFC 2782.
diff --git a/gio/gunionvolumemonitor.c b/gio/gunionvolumemonitor.c
index 1b681f96d..0fb971453 100644
--- a/gio/gunionvolumemonitor.c
+++ b/gio/gunionvolumemonitor.c
@@ -645,7 +645,7 @@ _g_mount_get_for_mount_path (const gchar  *mount_path,
  * is to return #GVolume objects representing entries in the users
  * "favorite servers" list or similar.
  *
- * Returns: the #GVolume object that is the parent for @mount or %NULL
+ * Returns: (transfer full): the #GVolume object that is the parent for @mount or %NULL
  * if no wants to adopt the #GMount.
  *
  * Deprecated: 2.20: Instead of using this function, #GVolumeMonitor
diff --git a/gio/gunixmounts.c b/gio/gunixmounts.c
index cec926bff..e509421ad 100644
--- a/gio/gunixmounts.c
+++ b/gio/gunixmounts.c
@@ -1083,7 +1083,7 @@ get_mount_points_timestamp (void)
  * timestamp, allowing for checking if the mounts have changed
  * with g_unix_mounts_changed_since().
  *
- * Returns: a #GList of the UNIX mounts.
+ * Returns: (element-type utf8) (transfer full): a #GList of the UNIX mounts.
  **/
 GList *
 g_unix_mounts_get (guint64 *time_read)
@@ -1138,7 +1138,7 @@ g_unix_mount_at (const char *mount_path,
  * allowing for checking if the mounts have changed with
  * g_unix_mounts_points_changed_since().
  *
- * Returns: a #GList of the UNIX mountpoints.
+ * Returns: (element-type utf8) (transfer full): a #GList of the UNIX mountpoints.
  **/
 GList *
 g_unix_mount_points_get (guint64 *time_read)
diff --git a/gio/gvolume.c b/gio/gvolume.c
index 4046eb47a..33e8aea74 100644
--- a/gio/gvolume.c
+++ b/gio/gvolume.c
@@ -568,8 +568,8 @@ g_volume_get_identifier (GVolume    *volume,
  * that @volume has. Use g_volume_get_identifer() to obtain 
  * the identifiers themselves.
  *
- * Returns: a %NULL-terminated array of strings containing
- *   kinds of identifiers. Use g_strfreev() to free.
+ * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array
+ *   of strings containing kinds of identifiers. Use g_strfreev() to free.
  */
 char **
 g_volume_enumerate_identifiers (GVolume *volume)
@@ -619,7 +619,7 @@ g_volume_enumerate_identifiers (GVolume *volume)
  * implementations to find the underlying mount to shadow, see
  * g_mount_is_shadowed() for more details.
  *
- * Returns: the activation root of @volume or %NULL. Use
+ * Returns: (transfer full): the activation root of @volume or %NULL. Use
  * g_object_unref() to free.
  *
  * Since: 2.18
diff --git a/gio/gvolumemonitor.c b/gio/gvolumemonitor.c
index 5fbe4c0b8..ee53ca26e 100644
--- a/gio/gvolumemonitor.c
+++ b/gio/gvolumemonitor.c
@@ -349,7 +349,7 @@ g_volume_monitor_get_mounts (GVolumeMonitor *volume_monitor)
  * 
  * Finds a #GVolume object by its UUID (see g_volume_get_uuid())
  * 
- * Returns: a #GVolume or %NULL if no such volume is available.
+ * Returns: (transfer full): a #GVolume or %NULL if no such volume is available.
  *     Free the returned object with g_object_unref().
  **/
 GVolume *