GIO: add lots of annotations for Vala bindings

https://bugzilla.gnome.org/show_bug.cgi?id=667447

gio/gapplicationcommandline.c

@@ -589,7 +589,7 @@ g_application_command_line_get_exit_status (GApplicationCommandLine *cmdline)
  *
  * For local invocation, it will be %NULL.
  *
- * Returns: the platform data, or %NULL
+ * Returns: (allow-none): the platform data, or %NULL
  *
  * Since: 2.28
  **/

gio/gbufferedinputstream.c

@@ -566,7 +566,8 @@ g_buffered_input_stream_get_available (GBufferedInputStream *stream)
 /**
  * g_buffered_input_stream_peek:
  * @stream: a #GBufferedInputStream
- * @buffer: a pointer to an allocated chunk of memory
+ * @buffer: (array length=count) (element-type guint8): a pointer to
+ *   an allocated chunk of memory
  * @offset: a #gsize
  * @count: a #gsize
  *

gio/gdbusintrospection.c

@@ -1838,7 +1838,7 @@ g_dbus_node_info_new_for_xml (const gchar  *xml_data,
 
 /**
  * g_dbus_annotation_info_lookup:
- * @annotations: A %NULL-terminated array of annotations or %NULL.
+ * @annotations: (array zero-terminated=1): A %NULL-terminated array of annotations or %NULL.
  * @name: The name of the annotation to look up.
  *
  * Looks up the value of an annotation.

gio/gdbusmessage.c

@@ -674,9 +674,9 @@ g_dbus_message_set_header (GDBusMessage             *message,
  *
  * Gets an array of all header fields on @message that are set.
  *
- * Returns: An array of header fields terminated by
- * %G_DBUS_MESSAGE_HEADER_FIELD_INVALID.  Each element is a
- * #guchar. Free with g_free().
+ * Returns: (array zero-terminated=1): An array of header fields
+ * terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID.  Each element
+ * is a #guchar. Free with g_free().
  *
  * Since: 2.26
  */
@@ -1573,7 +1573,7 @@ parse_value_from_blob (GMemoryInputStream    *mis,
 
 /**
  * g_dbus_message_bytes_needed:
- * @blob: A blob represent a binary D-Bus message.
+ * @blob: (array length=blob_len) (element-type guint8): A blob represent a binary D-Bus message.
  * @blob_len: The length of @blob (must be at least 16).
  * @error: Return location for error or %NULL.
  *
@@ -1641,7 +1641,7 @@ g_dbus_message_bytes_needed (guchar                *blob,
 
 /**
  * g_dbus_message_new_from_blob:
- * @blob: A blob represent a binary D-Bus message.
+ * @blob: (array length=blob_len) (element-type guint8): A blob represent a binary D-Bus message.
  * @blob_len: The length of @blob.
  * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
  * @error: Return location for error or %NULL.
@@ -2227,8 +2227,9 @@ append_body_to_blob (GVariant             *value,
  * Serializes @message to a blob. The byte order returned by
  * g_dbus_message_get_byte_order() will be used.
  *
- * Returns: A pointer to a valid binary D-Bus message of @out_size bytes
- * generated by @message or %NULL if @error is set. Free with g_free().
+ * Returns: (array length=out_size) (transfer full): A pointer to a
+ * valid binary D-Bus message of @out_size bytes generated by @message
+ * or %NULL if @error is set. Free with g_free().
  *
  * Since: 2.26
  */

gio/gdbusserver.c

@@ -447,7 +447,7 @@ on_run (GSocketService    *service,
  * @address: A D-Bus address.
  * @flags: Flags from the #GDBusServerFlags enumeration.
  * @guid: A D-Bus GUID.
- * @observer: A #GDBusAuthObserver or %NULL.
+ * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
  * @cancellable: A #GCancellable or %NULL.
  * @error: Return location for server or %NULL.
  *

gio/gemblemedicon.c

@@ -152,7 +152,7 @@ g_emblemed_icon_init (GEmblemedIcon *emblemed)
  *
  * Creates a new emblemed icon for @icon with the emblem @emblem.
  *
- * Returns: (transfer full): a new #GIcon
+ * Returns: (transfer full) (type GEmblemedIcon): a new #GIcon
  *
  * Since: 2.18
  **/

gio/gfile.c

@@ -625,7 +625,7 @@ g_file_get_parent (GFile *file)
 /**
  * g_file_has_parent:
  * @file: input #GFile
- * @parent: the parent to check for, or %NULL
+ * @parent: (allow-none): the parent to check for, or %NULL
  *
  * Checks if @file has a parent, and optionally, if it is @parent.
  *
@@ -3199,7 +3199,7 @@ g_file_copy_finish (GFile        *file,
  * @destination: #GFile pointing to the destination location.
  * @flags: set of #GFileCopyFlags.
  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @progress_callback: (scope call): #GFileProgressCallback function for updates.
+ * @progress_callback: (allow-none) (scope call): #GFileProgressCallback function for updates.
  * @progress_callback_data: (closure): gpointer to user data for the callback function.
  * @error: #GError for returning error conditions, or %NULL
  *
@@ -4233,7 +4233,7 @@ g_file_set_attribute_int64 (GFile                *file,
  * g_file_mount_mountable:
  * @file: input #GFile.
  * @flags: flags affecting the operation
- * @mount_operation: a #GMountOperation, or %NULL to avoid user interaction.
+ * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction.
  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
  * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
  * @user_data: (closure): the data to pass to callback function
@@ -4408,7 +4408,7 @@ g_file_unmount_mountable_finish (GFile         *file,
  * g_file_unmount_mountable_with_operation:
  * @file: input #GFile.
  * @flags: flags affecting the operation
- * @mount_operation: a #GMountOperation, or %NULL to avoid user interaction.
+ * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction.
  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
  * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
  * @user_data: (closure): the data to pass to callback function
@@ -4593,7 +4593,7 @@ g_file_eject_mountable_finish (GFile         *file,
  * g_file_eject_mountable_with_operation:
  * @file: input #GFile.
  * @flags: flags affecting the operation
- * @mount_operation: a #GMountOperation, or %NULL to avoid user interaction.
+ * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction.
  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
  * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
  * @user_data: (closure): the data to pass to callback function
@@ -6030,8 +6030,8 @@ g_file_new_for_commandline_arg (const char *arg)
  * g_file_mount_enclosing_volume:
  * @location: input #GFile.
  * @flags: flags affecting the operation
- * @mount_operation: a #GMountOperation or %NULL to avoid user interaction.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
  * @user_data: the data to pass to callback function
  * 
@@ -6966,7 +6966,7 @@ g_file_replace_contents_finish (GFile         *file,
  * g_file_start_mountable:
  * @file: input #GFile.
  * @flags: flags affecting the operation
- * @start_operation: a #GMountOperation, or %NULL to avoid user interaction.
+ * @start_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
  * @user_data: the data to pass to callback function
@@ -7058,7 +7058,7 @@ g_file_start_mountable_finish (GFile                      *file,
  * g_file_stop_mountable:
  * @file: input #GFile.
  * @flags: flags affecting the operation
- * @mount_operation: a #GMountOperation, or %NULL to avoid user interaction.
+ * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
  * @user_data: the data to pass to callback function

gio/gfileicon.c

@@ -158,7 +158,8 @@ g_file_icon_init (GFileIcon *file)
  * 
  * Creates a new icon for a file.
  * 
- * Returns: (transfer full): a #GIcon for the given @file, or %NULL on error.
+ * Returns: (transfer full) (type GFileIcon): a #GIcon for the given
+ *   @file, or %NULL on error.
  **/
 GIcon *
 g_file_icon_new (GFile *file)

gio/gfileinfo.c

@@ -1173,7 +1173,7 @@ _g_file_info_set_attribute_stringv_by_id (GFileInfo *info,
  * g_file_info_set_attribute_stringv:
  * @info: a #GFileInfo.
  * @attribute: a file attribute key
- * @attr_value: a %NULL terminated array of UTF-8 strings.
+ * @attr_value: (array) (element-type utf8): a %NULL terminated array of UTF-8 strings.
  *
  * Sets the @attribute to contain the given @attr_value,
  * if possible.

gio/gfilemonitor.c

@@ -221,7 +221,7 @@ g_file_monitor_class_init (GFileMonitorClass *klass)
    * GFileMonitor::changed:
    * @monitor: a #GFileMonitor.
    * @file: a #GFile.
-   * @other_file: a #GFile or #NULL.
+   * @other_file: (allow-none): a #GFile or #NULL.
    * @event_type: a #GFileMonitorEvent.
    *
    * Emitted when @file has been changed.

gio/ginetaddress.c

@@ -439,7 +439,7 @@ g_inet_address_new_from_string (const gchar *string)
 
 /**
  * g_inet_address_new_from_bytes:
- * @bytes: raw address data
+ * @bytes: (array) (element-type guint8): raw address data
  * @family: the address family of @bytes
  *
  * Creates a new #GInetAddress from the given @family and @bytes.

gio/ginitable.c

@@ -157,7 +157,7 @@ g_initable_new (GType          object_type,
  * g_initable_newv:
  * @object_type: a #GType supporting #GInitable.
  * @n_parameters: the number of parameters in @parameters
- * @parameters: the parameters to use to construct the object
+ * @parameters: (array length=n_parameters): the parameters to use to construct the object
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError location to store the error occurring, or %NULL to
  *     ignore.

gio/gmemoryinputstream.c

@@ -202,7 +202,7 @@ g_memory_input_stream_new (void)
 
 /**
  * g_memory_input_stream_new_from_data:
- * @data: (array length=len) (element-type guint8): input data
+ * @data: (array length=len) (element-type guint8) (transfer full): input data
  * @len: length of the data, may be -1 if @data is a nul-terminated string
  * @destroy: (allow-none): function that is called to free @data, or %NULL
  *
@@ -228,7 +228,7 @@ g_memory_input_stream_new_from_data (const void     *data,
 /**
  * g_memory_input_stream_add_data:
  * @stream: a #GMemoryInputStream
- * @data: (array length=len) (element-type guint8): input data
+ * @data: (array length=len) (element-type guint8) (transfer full): input data
  * @len: length of the data, may be -1 if @data is a nul-terminated string
  * @destroy: (allow-none): function that is called to free @data, or %NULL
  *

gio/gmountoperation.c

@@ -343,7 +343,8 @@ g_mount_operation_class_init (GMountOperationClass *klass)
    * GMountOperation::show-processes:
    * @op: a #GMountOperation.
    * @message: string containing a message to display to the user.
-   * @processes: an array of #GPid for processes blocking the operation.
+   * @processes: (element-type GPid): an array of #GPid for processes
+   *   blocking the operation.
    * @choices: an array of strings for each possible choice.
    *
    * Emitted when one or more processes are blocking an operation

gio/gnetworkaddress.c

@@ -251,7 +251,7 @@ g_network_address_set_addresses (GNetworkAddress *addr,
  * Creates a new #GSocketConnectable for connecting to the given
  * @hostname and @port.
  *
- * Return value: (transfer full): the new #GNetworkAddress
+ * Return value: (transfer full) (type GNetworkAddress): the new #GNetworkAddress
  *
  * Since: 2.22
  */

gio/gnetworkservice.c

@@ -245,7 +245,7 @@ g_network_service_get_property (GObject    *object,
  * @protocol, and @domain. This will initially be unresolved; use the
  * #GSocketConnectable interface to resolve it.
  *
- * Return value: (transfer full): a new #GNetworkService
+ * Return value: (transfer full) (type GNetworkService): a new #GNetworkService
  *
  * Since: 2.22
  */

gio/goutputstream.c

@@ -177,6 +177,8 @@ g_output_stream_init (GOutputStream *stream)
  *
  * On error -1 is returned and @error is set accordingly.
  * 
+ * Virtual: write_fn
+ *
  * Return value: Number of bytes written, or -1 on error
  **/
 gssize

gio/gsimpleactiongroup.c

@@ -367,8 +367,8 @@ g_simple_action_group_remove (GSimpleActionGroup *simple,
 /**
  * g_simple_action_group_add_entries:
  * @simple: a #GSimpleActionGroup
- * @entries: a pointer to the first item in an array of #GActionEntry
- *           structs
+ * @entries: (array length=n_entries): a pointer to the first item in
+ *           an array of #GActionEntry structs
  * @n_entries: the length of @entries, or -1
  * @user_data: the user data for signal connections
  *

gio/gsocket.c

@@ -1890,9 +1890,10 @@ g_socket_receive_with_blocking (GSocket       *socket,
 /**
  * g_socket_receive_from:
  * @socket: a #GSocket
- * @address: a pointer to a #GSocketAddress pointer, or %NULL
- * @buffer: a buffer to read data into (which should be at least @size
- *     bytes long).
+ * @address: (out) (allow-none): a pointer to a #GSocketAddress
+ *     pointer, or %NULL
+ * @buffer: (array length=size) (element-type guint8): a buffer to
+ *     read data into (which should be at least @size bytes long).
  * @size: the number of bytes you want to read from the socket
  * @cancellable: (allow-none): a %GCancellable or %NULL
  * @error: #GError for error reporting, or %NULL to ignore.
@@ -1944,7 +1945,8 @@ g_socket_receive_from (GSocket         *socket,
 /**
  * g_socket_send:
  * @socket: a #GSocket
- * @buffer: (array length=size): the buffer containing the data to send.
+ * @buffer: (array length=size) (element-type guint8): the buffer
+ *     containing the data to send.
  * @size: the number of bytes to send
  * @cancellable: (allow-none): a %GCancellable or %NULL
  * @error: #GError for error reporting, or %NULL to ignore.
@@ -1984,7 +1986,8 @@ g_socket_send (GSocket       *socket,
 /**
  * g_socket_send_with_blocking:
  * @socket: a #GSocket
- * @buffer: (array length=size): the buffer containing the data to send.
+ * @buffer: (array length=size) (element-type guint8): the buffer
+ *     containing the data to send.
  * @size: the number of bytes to send
  * @blocking: whether to do blocking or non-blocking I/O
  * @cancellable: (allow-none): a %GCancellable or %NULL
@@ -2063,7 +2066,8 @@ g_socket_send_with_blocking (GSocket       *socket,
  * g_socket_send_to:
  * @socket: a #GSocket
  * @address: a #GSocketAddress, or %NULL
- * @buffer: (array length=size): the buffer containing the data to send.
+ * @buffer: (array length=size) (element-type guint8): the buffer
+ *     containing the data to send.
  * @size: the number of bytes to send
  * @cancellable: (allow-none): a %GCancellable or %NULL
  * @error: #GError for error reporting, or %NULL to ignore.
@@ -3158,7 +3162,8 @@ g_socket_send_message (GSocket                *socket,
 /**
  * g_socket_receive_message:
  * @socket: a #GSocket
- * @address: a pointer to a #GSocketAddress pointer, or %NULL
+ * @address: (out) (allow-none): a pointer to a #GSocketAddress
+ *     pointer, or %NULL
  * @vectors: (array length=num_vectors): an array of #GInputVector structs
  * @num_vectors: the number of elements in @vectors, or -1
  * @messages: (array length=num_messages) (allow-none): a pointer which

gio/gsocketservice.c

@@ -254,7 +254,8 @@ g_socket_service_class_init (GSocketServiceClass *class)
    * GSocketService::incoming:
    * @service: the #GSocketService
    * @connection: a new #GSocketConnection object
-   * @source_object: the source_object passed to g_socket_listener_add_address()
+   * @source_object: (allow-none): the source_object passed to
+   *     g_socket_listener_add_address()
    *
    * The ::incoming signal is emitted when a new incoming connection
    * to @service needs to be handled. The handler must initiate the

gio/gthemedicon.c

@@ -263,7 +263,7 @@ g_themed_icon_init (GThemedIcon *themed)
  * 
  * Creates a new themed icon for @iconname.
  * 
- * Returns: (transfer full): a new #GThemedIcon.
+ * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon.
  **/
 GIcon *
 g_themed_icon_new (const char *iconname)
@@ -281,7 +281,7 @@ g_themed_icon_new (const char *iconname)
  * 
  * Creates a new themed icon for @iconnames.
  * 
- * Returns: (transfer full): a new #GThemedIcon
+ * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon
  **/
 GIcon *
 g_themed_icon_new_from_names (char **iconnames,
@@ -333,7 +333,7 @@ g_themed_icon_new_from_names (char **iconnames,
  * icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio");
  * ]|
  *
- * Returns: (transfer full): a new #GThemedIcon.
+ * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon.
  */
 GIcon *
 g_themed_icon_new_with_default_fallbacks (const char *iconname)

gio/gtlsclientconnection.c

@@ -153,7 +153,8 @@ g_tls_client_connection_default_init (GTlsClientConnectionInterface *iface)
  * must have pollable input and output streams) which is assumed to
  * communicate with the server identified by @server_identity.
  *
- * Return value: (transfer full): the new #GTlsClientConnection, or %NULL on error
+ * Return value: (transfer full) (type GTlsClientConnection): the new
+ * #GTlsClientConnection, or %NULL on error
  *
  * Since: 2.28
  */

gio/gtlsdatabase.c

@@ -868,8 +868,8 @@ g_tls_database_lookup_certificate_issuer_finish (GTlsDatabase          *self,
  * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
  * the lookup operation asynchronously.
  *
- * Return value: (transfer full): a newly allocated list of #GTlsCertificate objects.
- * Use g_object_unref() on each certificate, and g_list_free() on the release the list.
+ * Return value: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
+ * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
  *
  * Since: 2.30
  */

gio/gtlsfiledatabase.c

@@ -84,7 +84,8 @@ g_tls_file_database_default_init (GTlsFileDatabaseInterface *iface)
  *
  * The certificates in @anchors must be PEM encoded.
  *
- * Return value: (transfer full): the new #GTlsFileDatabase, or %NULL on error
+ * Return value: (transfer full) (type GTlsFileDatabase): the new
+ * #GTlsFileDatabase, or %NULL on error
  *
  * Since: 2.30
  */

gio/gtlspassword.c

@@ -295,6 +295,7 @@ g_tls_password_set_value (GTlsPassword  *password,
  * @length if using a null-terminated password, and @length will be calculated
  * automatically.
  *
+ * Virtual: set_value
  * Since: 2.30
  */
 void

gio/gtlsserverconnection.c

@@ -73,7 +73,8 @@ g_tls_server_connection_default_init (GTlsServerConnectionInterface *iface)
  * Creates a new #GTlsServerConnection wrapping @base_io_stream (which
  * must have pollable input and output streams).
  *
- * Return value: (transfer full): the new #GTlsServerConnection, or %NULL on error
+ * Return value: (transfer full) (type GTlsServerConnection): the new
+ * #GTlsServerConnection, or %NULL on error
  *
  * Since: 2.28
  */