Commit c3d6595f authored by Evan Nemerson's avatar Evan Nemerson Committed by Colin Walters

GIO: add lots of annotations for Vala bindings

https://bugzilla.gnome.org/show_bug.cgi?id=667447
parent e98f17e5
......@@ -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
**/
......
......@@ -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
*
......
......@@ -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.
......
......@@ -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
*/
......
......@@ -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.
*
......
......@@ -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
**/
......
......@@ -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
......
......@@ -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)
......
......@@ -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.
......
......@@ -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.
......
......@@ -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.
......
......@@ -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.
......
......@@ -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
*
......
......@@ -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
......
......@@ -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
*/
......
......@@ -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
*/
......
......@@ -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
......
......@@ -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
*
......
......@@ -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
......
......@@ -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
......
......@@ -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)
......
......@@ -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
*/
......
......@@ -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
*/
......
......@@ -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
*/
......
......@@ -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
......
......@@ -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
*/
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment