From 975b0d4487809270100efce56270314d816e3073 Mon Sep 17 00:00:00 2001 From: Pavel Holejsovsky Date: Wed, 29 Dec 2010 13:51:44 +0100 Subject: [PATCH] Add GI annotations to Gio lowlevel network support classes --- gio/ginetaddress.c | 2 +- gio/ginetsocketaddress.c | 2 +- gio/gproxy.c | 11 +++++---- gio/gproxyaddress.c | 6 +++-- gio/gsocket.c | 44 +++++++++++++++++----------------- gio/gsocketaddressenumerator.c | 9 +++---- gio/gsocketcontrolmessage.c | 2 +- gio/gunixfdlist.c | 14 +++++++---- gio/gunixfdmessage.c | 6 +++-- gio/gunixsocketaddress.c | 4 ++-- 10 files changed, 55 insertions(+), 45 deletions(-) diff --git a/gio/ginetaddress.c b/gio/ginetaddress.c index 429cac25c..0f67e4ff9 100644 --- a/gio/ginetaddress.c +++ b/gio/ginetaddress.c @@ -570,7 +570,7 @@ g_inet_address_to_string (GInetAddress *address) } /** - * g_inet_address_to_bytes: + * g_inet_address_to_bytes: (skip) * @address: a #GInetAddress * * Gets the raw binary address data from @address. diff --git a/gio/ginetsocketaddress.c b/gio/ginetsocketaddress.c index 3f0935b58..071c49ff3 100644 --- a/gio/ginetsocketaddress.c +++ b/gio/ginetsocketaddress.c @@ -289,7 +289,7 @@ g_inet_socket_address_new (GInetAddress *address, * * Gets @address's #GInetAddress. * - * Returns: (transfer full): the #GInetAddress for @address, which must be + * Returns: (transfer none): the #GInetAddress for @address, which must be * g_object_ref()'d if it will be stored * * Since: 2.22 diff --git a/gio/gproxy.c b/gio/gproxy.c index b40e23caa..d24e86eae 100644 --- a/gio/gproxy.c +++ b/gio/gproxy.c @@ -56,7 +56,8 @@ g_proxy_default_init (GProxyInterface *iface) * Lookup "gio-proxy" extension point for a proxy implementation that supports * specified protocol. * - * Return value: return a #GProxy or NULL if protocol is not supported. + * Return value: (transfer full): return a #GProxy or NULL if protocol + * is not supported. * * Since: 2.26 **/ @@ -84,7 +85,7 @@ g_proxy_get_default_for_protocol (const gchar *protocol) * @proxy: a #GProxy * @connection: a #GIOStream * @proxy_address: a #GProxyAddress - * @cancellable: a #GCancellable + * @cancellable: (allow-none): a #GCancellable * @error: return #GError * * Given @connection to communicate with a proxy (eg, a @@ -123,9 +124,9 @@ g_proxy_connect (GProxy *proxy, * @proxy: a #GProxy * @connection: a #GIOStream * @proxy_address: a #GProxyAddress - * @cancellable: a #GCancellable - * @callback: a #GAsyncReadyCallback - * @user_data: callback data + * @cancellable: (allow-none): a #GCancellable + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): callback data * * Asynchronous version of g_proxy_connect(). * diff --git a/gio/gproxyaddress.c b/gio/gproxyaddress.c index 61dfc7d08..68ef29420 100644 --- a/gio/gproxyaddress.c +++ b/gio/gproxyaddress.c @@ -233,8 +233,10 @@ g_proxy_address_init (GProxyAddress *proxy) * @protocol: The proxy protocol to support, in lower case (e.g. socks, http). * @dest_hostname: The destination hostname the the proxy should tunnel to. * @dest_port: The destination port to tunnel to. - * @username: The username to authenticate to the proxy server (or %NULL). - * @password: The password to authenticate to the proxy server (or %NULL). + * @username: (allow-none): The username to authenticate to the proxy server + * (or %NULL). + * @password: (allow-none): The password to authenticate to the proxy server + * (or %NULL). * * Creates a new #GProxyAddress for @inetaddr with @protocol that should * tunnel through @dest_hostname and @dest_port. diff --git a/gio/gsocket.c b/gio/gsocket.c index ae45802b7..b78a586f8 100644 --- a/gio/gsocket.c +++ b/gio/gsocket.c @@ -1479,7 +1479,7 @@ g_socket_speaks_ipv4 (GSocket *socket) /** * g_socket_accept: * @socket: a #GSocket. - * @cancellable: a %GCancellable or %NULL + * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. * * Accept incoming connections on a connection-based socket. This removes @@ -1591,7 +1591,7 @@ g_socket_accept (GSocket *socket, * g_socket_connect: * @socket: a #GSocket. * @address: a #GSocketAddress specifying the remote address. - * @cancellable: a %GCancellable or %NULL + * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. * * Connect the socket to the specified remote address. @@ -1737,7 +1737,7 @@ g_socket_check_connect_result (GSocket *socket, * @buffer: 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: a %GCancellable or %NULL + * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. * * Receive data (up to @size bytes) from a socket. This is mainly used by @@ -1786,7 +1786,7 @@ g_socket_receive (GSocket *socket, * bytes long). * @size: the number of bytes you want to read from the socket * @blocking: whether to do blocking or non-blocking I/O - * @cancellable: a %GCancellable or %NULL + * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. * * This behaves exactly the same as g_socket_receive(), except that @@ -1864,7 +1864,7 @@ g_socket_receive_with_blocking (GSocket *socket, * @buffer: 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: a %GCancellable or %NULL + * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. * * Receive data (up to @size bytes) from a socket. @@ -1913,9 +1913,9 @@ g_socket_receive_from (GSocket *socket, /** * g_socket_send: * @socket: a #GSocket - * @buffer: the buffer containing the data to send. + * @buffer: (array length=size): the buffer containing the data to send. * @size: the number of bytes to send - * @cancellable: a %GCancellable or %NULL + * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. * * Tries to send @size bytes from @buffer on the socket. This is @@ -1953,10 +1953,10 @@ g_socket_send (GSocket *socket, /** * g_socket_send_with_blocking: * @socket: a #GSocket - * @buffer: the buffer containing the data to send. + * @buffer: (array length=size): 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: a %GCancellable or %NULL + * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. * * This behaves exactly the same as g_socket_send(), except that @@ -2032,9 +2032,9 @@ g_socket_send_with_blocking (GSocket *socket, * g_socket_send_to: * @socket: a #GSocket * @address: a #GSocketAddress, or %NULL - * @buffer: the buffer containing the data to send. + * @buffer: (array length=size): the buffer containing the data to send. * @size: the number of bytes to send - * @cancellable: a %GCancellable or %NULL + * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. * * Tries to send @size bytes from @buffer to @address. If @address is @@ -2588,10 +2588,10 @@ socket_source_new (GSocket *socket, } /** - * g_socket_create_source: + * g_socket_create_source: (skip) * @socket: a #GSocket * @condition: a #GIOCondition mask to monitor - * @cancellable: a %GCancellable or %NULL + * @cancellable: (allow-none): a %GCancellable or %NULL * * Creates a %GSource that can be attached to a %GMainContext to monitor * for the availibility of the specified @condition on the socket. @@ -2692,7 +2692,7 @@ g_socket_condition_check (GSocket *socket, * g_socket_condition_wait: * @socket: a #GSocket * @condition: a #GIOCondition mask to wait for - * @cancellable: a #GCancellable, or %NULL + * @cancellable: (allow-none): a #GCancellable, or %NULL * @error: a #GError pointer, or %NULL * * Waits for @condition to become true on @socket. When the condition @@ -2819,13 +2819,13 @@ g_socket_condition_wait (GSocket *socket, * g_socket_send_message: * @socket: a #GSocket * @address: a #GSocketAddress, or %NULL - * @vectors: an array of #GOutputVector structs + * @vectors: (array length=num_vectors): an array of #GOutputVector structs * @num_vectors: the number of elements in @vectors, or -1 - * @messages: a pointer to an array of #GSocketControlMessages, or - * %NULL. + * @messages: (array length=num_messages) (allow-none): a pointer to an + * array of #GSocketControlMessages, or %NULL. * @num_messages: number of elements in @messages, or -1. * @flags: an int containing #GSocketMsgFlags flags - * @cancellable: a %GCancellable or %NULL + * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. * * Send data to @address on @socket. This is the most complicated and @@ -3117,14 +3117,14 @@ g_socket_send_message (GSocket *socket, * g_socket_receive_message: * @socket: a #GSocket * @address: a pointer to a #GSocketAddress pointer, or %NULL - * @vectors: an array of #GInputVector structs + * @vectors: (array length=num_vectors): an array of #GInputVector structs * @num_vectors: the number of elements in @vectors, or -1 - * @messages: a pointer which may be filled with an array of - * #GSocketControlMessages, or %NULL + * @messages: (array length=num_messages) (allow-none): a pointer which + * may be filled with an array of #GSocketControlMessages, or %NULL * @num_messages: a pointer which will be filled with the number of * elements in @messages, or %NULL * @flags: a pointer to an int containing #GSocketMsgFlags flags - * @cancellable: a %GCancellable or %NULL + * @cancellable: (allow-none): a %GCancellable or %NULL * @error: a #GError pointer, or %NULL * * Receive data from a socket. This is the most complicated and diff --git a/gio/gsocketaddressenumerator.c b/gio/gsocketaddressenumerator.c index 1886f3602..2193860bf 100644 --- a/gio/gsocketaddressenumerator.c +++ b/gio/gsocketaddressenumerator.c @@ -50,7 +50,7 @@ g_socket_address_enumerator_class_init (GSocketAddressEnumeratorClass *enumerato /** * g_socket_address_enumerator_next: * @enumerator: a #GSocketAddressEnumerator - * @cancellable: optional #GCancellable object, %NULL to ignore. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @error: a #GError. * * Retrieves the next #GSocketAddress from @enumerator. Note that this @@ -115,9 +115,10 @@ g_socket_address_enumerator_real_next_async (GSocketAddressEnumerator *enumerato /** * g_socket_address_enumerator_next_async: * @enumerator: a #GSocketAddressEnumerator - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: the data to pass to callback function + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request + * is satisfied + * @user_data: (closure): the data to pass to callback function * * Asynchronously retrieves the next #GSocketAddress from @enumerator * and then calls @callback, which must call diff --git a/gio/gsocketcontrolmessage.c b/gio/gsocketcontrolmessage.c index cce825867..a2a6f44fe 100644 --- a/gio/gsocketcontrolmessage.c +++ b/gio/gsocketcontrolmessage.c @@ -153,7 +153,7 @@ g_socket_control_message_class_init (GSocketControlMessageClass *class) * @level: a socket level * @type: a socket control message type for the given @level * @size: the size of the data in bytes - * @data: pointer to the message data + * @data: (array length=size) (element-type guint8): pointer to the message data * * Tries to deserialize a socket control message of a given * @level and @type. This will ask all known (to GType) subclasses diff --git a/gio/gunixfdlist.c b/gio/gunixfdlist.c index e9425db96..68af47e68 100644 --- a/gio/gunixfdlist.c +++ b/gio/gunixfdlist.c @@ -161,7 +161,7 @@ g_unix_fd_list_new (void) /** * g_unix_fd_list_new_from_array: - * @fds: the initial list of file descriptors + * @fds: (array length=n_fds): the initial list of file descriptors * @n_fds: the length of #fds, or -1 * * Creates a new #GUnixFDList containing the file descriptors given in @@ -201,7 +201,8 @@ g_unix_fd_list_new_from_array (const gint *fds, /** * g_unix_fd_list_steal_fds: * @list: a #GUnixFDList - * @length: pointer to the length of the returned array, or %NULL + * @length: (out) (allow-none): pointer to the length of the returned + * array, or %NULL * * Returns the array of file descriptors that is contained in this * object. @@ -222,7 +223,8 @@ g_unix_fd_list_new_from_array (const gint *fds, * This function never returns %NULL. In case there are no file * descriptors contained in @list, an empty array is returned. * - * Returns: an array of file descriptors + * Returns: (array length=length) (transfer full): an array of file + * descriptors * * Since: 2.24 */ @@ -255,7 +257,8 @@ g_unix_fd_list_steal_fds (GUnixFDList *list, /** * g_unix_fd_list_peek_fds: * @list: a #GUnixFDList - * @length: pointer to the length of the returned array, or %NULL + * @length: (out) (allow-none): pointer to the length of the returned + * array, or %NULL * * Returns the array of file descriptors that is contained in this * object. @@ -271,7 +274,8 @@ g_unix_fd_list_steal_fds (GUnixFDList *list, * This function never returns %NULL. In case there are no file * descriptors contained in @list, an empty array is returned. * - * Returns: an array of file descriptors + * Returns: (array length=length) (transfer none): an array of file + * descriptors * * Since: 2.24 */ diff --git a/gio/gunixfdmessage.c b/gio/gunixfdmessage.c index 7dc0f8bbb..aaf749beb 100644 --- a/gio/gunixfdmessage.c +++ b/gio/gunixfdmessage.c @@ -257,7 +257,8 @@ g_unix_fd_message_new_with_fd_list (GUnixFDList *fd_list) /** * g_unix_fd_message_steal_fds: * @message: a #GUnixFDMessage - * @length: pointer to the length of the returned array, or %NULL + * @length: (out) (allow-none): pointer to the length of the returned + * array, or %NULL * * Returns the array of file descriptors that is contained in this * object. @@ -277,7 +278,8 @@ g_unix_fd_message_new_with_fd_list (GUnixFDList *fd_list) * This function never returns %NULL. In case there are no file * descriptors contained in @message, an empty array is returned. * - * Returns: an array of file descriptors + * Returns: (array length=length) (transfer full): an array of file + * descriptors * * Since: 2.22 **/ diff --git a/gio/gunixsocketaddress.c b/gio/gunixsocketaddress.c index a1e06b143..440ab253d 100644 --- a/gio/gunixsocketaddress.c +++ b/gio/gunixsocketaddress.c @@ -349,7 +349,7 @@ g_unix_socket_address_new (const gchar *path) /** * g_unix_socket_address_new_abstract: - * @path: the abstract name + * @path: (array length=path_len) (element-type gchar): the abstract name * @path_len: the length of @path, or -1 * * Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED @@ -369,7 +369,7 @@ g_unix_socket_address_new_abstract (const gchar *path, /** * g_unix_socket_address_new_with_type: - * @path: the name + * @path: (array length=path_len) (element-type gchar): the name * @path_len: the length of @path, or -1 * @type: a #GUnixSocketAddressType *