Update annotations from gobject-introspection/gir/glib-2.0.c

This covers most of them.

glib/gcompletion.c

@@ -286,7 +286,7 @@ completion_check_cache (GCompletion* cmp,
  * You should use this function instead of g_completion_complete() if your 
  * items are UTF-8 strings.
  *
- * Return value: the list of items whose strings begin with @prefix. This should
+ * Return value: (element-type utf8) (transfer none): the list of items whose strings begin with @prefix. This should
  * not be changed.
  *
  * Since: 2.4

glib/gconvert.c

@@ -837,7 +837,7 @@ g_convert_with_iconv (const gchar *str,
                    </footnote>. 
  * @to_codeset:    name of character set into which to convert @str
  * @from_codeset:  character set of @str.
- * @bytes_read:    location to store the number of bytes in the
+ * @bytes_read: (out):   location to store the number of bytes in the
  *                 input string that were successfully converted, or %NULL.
  *                 Even if the conversion was successful, this may be 
  *                 less than @len if there were partial characters
@@ -845,7 +845,7 @@ g_convert_with_iconv (const gchar *str,
  *                 #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
  *                 stored will the byte offset after the last valid
  *                 input sequence.
- * @bytes_written: the number of bytes stored in the output buffer (not 
+ * @bytes_written: (out): the number of bytes stored in the output buffer (not 
  *                 including the terminating nul).
  * @error:         location to store the error occuring, or %NULL to ignore
  *                 errors. Any of the errors in #GConvertError may occur.
@@ -2007,7 +2007,7 @@ g_filename_from_uri (const gchar *uri,
  * @filename: an absolute filename specified in the GLib file name encoding,
  *            which is the on-disk file name bytes on Unix, and UTF-8 on 
  *            Windows
- * @hostname: A UTF-8 encoded hostname, or %NULL for none.
+ * @hostname: (allow-none): A UTF-8 encoded hostname, or %NULL for none.
  * @error: location to store the error occuring, or %NULL to ignore
  *         errors. Any of the errors in #GConvertError may occur.
  * 

glib/gfileutils.c

@@ -1506,7 +1506,7 @@ g_build_path_va (const gchar  *separator,
 /**
  * g_build_pathv:
  * @separator: a string used to separator the elements of the path.
- * @args: %NULL-terminated array of strings containing the path elements.
+ * @args: (array zero-terminated=1): %NULL-terminated array of strings containing the path elements.
  * 
  * Behaves exactly like g_build_path(), but takes the path elements 
  * as a string array, instead of varargs. This function is mainly

glib/giochannel.c

@@ -647,6 +647,7 @@ g_io_create_watch (GIOChannel   *channel,
  * You can do these steps manually if you need greater control.
  *
  * Returns: the event source id
+ * Rename to: g_io_add_watch
  */
 guint 
 g_io_add_watch_full (GIOChannel    *channel,

glib/gkeyfile.c

@@ -1505,8 +1505,9 @@ g_key_file_set_string (GKeyFile    *key_file,
  * event that the @group_name cannot be found, %NULL is returned
  * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
  *
- * Return value: a %NULL-terminated string array or %NULL if the specified 
- *   key cannot be found. The array should be freed with g_strfreev().
+ * Return value: (array zero-terminated=1 length=length) (element-type utf8) (transfer full): 
+ *  a %NULL-terminated string array or %NULL if the specified 
+ *  key cannot be found. The array should be freed with g_strfreev().
  *
  * Since: 2.6
  **/
@@ -1592,7 +1593,7 @@ g_key_file_get_string_list (GKeyFile     *key_file,
  * @key_file: a #GKeyFile
  * @group_name: a group name
  * @key: a key
- * @list: an array of string values
+ * @list: (array zero-terminated=1 length=length) (element-type utf8): an array of string values
  * @length: number of string values in @list
  *
  * Associates a list of string values for @key under @group_name.
@@ -1669,7 +1670,7 @@ g_key_file_set_locale_string (GKeyFile     *key_file,
  * @key_file: a #GKeyFile
  * @group_name: a group name
  * @key: a key
- * @locale: a locale identifier or %NULL
+ * @locale: (allow-none): a locale identifier or %NULL
  * @error: return location for a #GError, or %NULL
  *
  * Returns the value associated with @key under @group_name
@@ -1756,8 +1757,8 @@ g_key_file_get_locale_string (GKeyFile     *key_file,
  * @key_file: a #GKeyFile
  * @group_name: a group name
  * @key: a key
- * @locale: a locale identifier or %NULL
- * @length: return location for the number of returned strings or %NULL
+ * @locale: (allow-none): a locale identifier or %NULL
+ * @length: (out): return location for the number of returned strings or %NULL
  * @error: return location for a #GError or %NULL
  *
  * Returns the values associated with @key under @group_name
@@ -1771,7 +1772,7 @@ g_key_file_get_locale_string (GKeyFile     *key_file,
  * returned array is %NULL-terminated, so @length may optionally 
  * be %NULL.
  *
- * Return value: a newly allocated %NULL-terminated string array
+ * Return value: (array zero-terminated=1 length=length) (element-type utf8) (transfer full): a newly allocated %NULL-terminated string array
  *   or %NULL if the key isn't found. The string array should be freed
  *   with g_strfreev().
  *

glib/gmain.c

@@ -3196,7 +3196,7 @@ g_main_context_iteration (GMainContext *context, gboolean may_block)
 
 /**
  * g_main_loop_new:
- * @context: a #GMainContext  (if %NULL, the default context will be used).
+ * @context: (allow-none): a #GMainContext  (if %NULL, the default context will be used).
  * @is_running: set to %TRUE to indicate that the loop is running. This
  * is not very important since calling g_main_loop_run() will set this to
  * %TRUE anyway.
@@ -4044,6 +4044,7 @@ g_timeout_source_new_seconds (guint interval)
  * do these steps manually if you need greater control.
  * 
  * Return value: the ID (greater than 0) of the event source.
+ * Rename to: g_timeout_add
  **/
 guint
 g_timeout_add_full (gint           priority,
@@ -4151,6 +4152,7 @@ g_timeout_add (guint32        interval,
  * Return value: the ID (greater than 0) of the event source.
  *
  * Since: 2.14
+ * Rename to: g_timeout_add_seconds
  **/
 guint
 g_timeout_add_seconds_full (gint           priority,
@@ -4745,6 +4747,7 @@ g_child_watch_source_new (GPid pid)
  * Return value: the ID (greater than 0) of the event source.
  *
  * Since: 2.4
+ * Rename to: g_child_watch_add
  **/
 guint
 g_child_watch_add_full (gint            priority,
@@ -4882,6 +4885,7 @@ g_idle_source_new (void)
  * You can do these steps manually if you need greater control.
  * 
  * Return value: the ID (greater than 0) of the event source.
+ * Rename to: g_idle_add
  **/
 guint 
 g_idle_add_full (gint           priority,

glib/goption.c

@@ -1693,8 +1693,8 @@ platform_get_argv0 (void)
 /**
  * g_option_context_parse:
  * @context: a #GOptionContext
- * @argc: a pointer to the number of command line arguments
- * @argv: a pointer to the array of command line arguments
+ * @argc: (inout) (allow-none): a pointer to the number of command line arguments
+ * @argv: (inout) (array length=argc) (allow-none): a pointer to the array of command line arguments
  * @error: a return location for errors
  *
  * Parses the command line arguments, recognizing options