Commit 570b27b9 authored by Evan Nemerson's avatar Evan Nemerson

gio: port annotations from the Vala metadata.

https://bugzilla.gnome.org/show_bug.cgi?id=730493
parent e3db9632
......@@ -328,7 +328,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: (transfer full): the state range hint
* Returns: (nullable) (transfer full): the state range hint
*
* Since: 2.28
**/
......
......@@ -389,7 +389,7 @@ g_action_group_has_action (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 parameter type.
*
* Returns: the parameter type
* Returns: (nullable): the parameter type
*
* Since: 2.28
**/
......@@ -425,7 +425,8 @@ g_action_group_get_action_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: (transfer full): the state type, if the action is stateful
* Returns: (nullable) (transfer full): the state type, if the action
* is stateful
*
* Since: 2.28
**/
......@@ -463,7 +464,7 @@ g_action_group_get_action_state_type (GActionGroup *action_group,
* The return value (if non-%NULL) should be freed with
* g_variant_unref() when it is no longer required.
*
* Returns: (transfer full): the state range hint
* Returns: (nullable) (transfer full): the state range hint
*
* Since: 2.28
**/
......@@ -515,7 +516,7 @@ g_action_group_get_action_enabled (GActionGroup *action_group,
* 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: (nullable): the current state of the action
*
* Since: 2.28
**/
......
......@@ -780,7 +780,7 @@ g_application_command_line_get_exit_status (GApplicationCommandLine *cmdline)
*
* For local invocation, it will be %NULL.
*
* Returns: (allow-none): the platform data, or %NULL
* Returns: (nullable): the platform data, or %NULL
*
* Since: 2.28
**/
......
......@@ -221,8 +221,8 @@ g_cancellable_pop_current (GCancellable *cancellable)
*
* Gets the top cancellable from the stack.
*
* Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL
* if the stack is empty.
* Returns: (nullable) (transfer none): a #GCancellable from the top
* of the stack, or %NULL if the stack is empty.
**/
GCancellable *
g_cancellable_get_current (void)
......
......@@ -382,7 +382,7 @@ g_content_type_get_description (const gchar *type)
*
* Gets the mime type for the content type, if one is registered.
*
* Returns: (allow-none): the registered mime type for the given @type,
* Returns: (nullable): the registered mime type for the given @type,
* or %NULL if unknown.
*/
char *
......@@ -569,8 +569,8 @@ looks_like_text (const guchar *data, gsize data_size)
*
* Tries to find a content type based on the mime type name.
*
* Returns: (allow-none): Newly allocated string with content type
* or %NULL. Free with g_free()
* Returns: (nullable): Newly allocated string with content type or
* %NULL. Free with g_free()
*
* Since: 2.18
**/
......
......@@ -735,12 +735,12 @@ scan_for_newline (GDataInputStream *stream,
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
* Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a
* NUL terminated byte array with the line that was read in (without
* the newlines). Set @length to a #gsize to get the length of the
* read line. On an error, it will return %NULL and @error will be
* set. If there's no content to read, it will still return %NULL,
* but @error won't be set.
* Returns: (nullable) (transfer full) (array zero-terminated=1) (element-type guint8):
* a NUL terminated byte array with the line that was read in
* (without the newlines). Set @length to a #gsize to get the length
* of the read line. On an error, it will return %NULL and @error
* will be set. If there's no content to read, it will still return
* %NULL, but @error won't be set.
**/
char *
g_data_input_stream_read_line (GDataInputStream *stream,
......@@ -819,12 +819,13 @@ g_data_input_stream_read_line (GDataInputStream *stream,
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
* Returns: (transfer full): a NUL terminated UTF-8 string with the
* line that was read in (without the newlines). Set @length to a
* #gsize to get the length of the read line. On an error, it will
* return %NULL and @error will be set. For UTF-8 conversion errors,
* the set error domain is %G_CONVERT_ERROR. If there's no content to
* read, it will still return %NULL, but @error won't be set.
* Returns: (nullable) (transfer full): a NUL terminated UTF-8 string
* with the line that was read in (without the newlines). Set
* @length to a #gsize to get the length of the read line. On an
* error, it will return %NULL and @error will be set. For UTF-8
* conversion errors, the set error domain is %G_CONVERT_ERROR. If
* there's no content to read, it will still return %NULL, but @error
* won't be set.
*
* Since: 2.30
**/
......@@ -1197,12 +1198,12 @@ g_data_input_stream_read_until_async (GDataInputStream *stream,
* string encoding in g_data_input_stream_read_line() applies here as
* well.
*
* Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a
* NUL-terminated byte array with the line that was read in
* (without the newlines). Set @length to a #gsize to get the
* length of the read line. On an error, it will return %NULL and
* @error will be set. If there's no content to read, it will
* still return %NULL, but @error won't be set.
* Returns: (nullable) (transfer full) (array zero-terminated=1) (element-type guint8):
* a NUL-terminated byte array with the line that was read in
* (without the newlines). Set @length to a #gsize to get the length
* of the read line. On an error, it will return %NULL and @error
* will be set. If there's no content to read, it will still return
* %NULL, but @error won't be set.
*
* Since: 2.20
*/
......@@ -1227,12 +1228,12 @@ g_data_input_stream_read_line_finish (GDataInputStream *stream,
* Finish an asynchronous call started by
* g_data_input_stream_read_line_async().
*
* Returns: (transfer full): a string with the line that was read in
* (without the newlines). Set @length to a #gsize to get the length
* of the read line. On an error, it will return %NULL and @error
* will be set. For UTF-8 conversion errors, the set error domain is
* %G_CONVERT_ERROR. If there's no content to read, it will still
* return %NULL, but @error won't be set.
* Returns: (nullable) (transfer full): a string with the line that
* was read in (without the newlines). Set @length to a #gsize to
* get the length of the read line. On an error, it will return
* %NULL and @error will be set. For UTF-8 conversion errors, the set
* error domain is %G_CONVERT_ERROR. If there's no content to read,
* it will still return %NULL, but @error won't be set.
*
* Since: 2.30
*/
......
......@@ -1114,7 +1114,8 @@ g_dbus_message_get_header_fields (GDBusMessage *message)
*
* Gets the body of a message.
*
* Returns: A #GVariant or %NULL if the body is empty. Do not free, it is owned by @message.
* Returns: (transfer none): A #GVariant or %NULL if the body is
* empty. Do not free, it is owned by @message.
*
* Since: 2.26
*/
......
......@@ -957,8 +957,8 @@ g_dbus_object_manager_client_get_flags (GDBusObjectManagerClient *manager)
* #GObject::notify signal to track changes to the
* #GDBusObjectManagerClient:name-owner property.
*
* Returns: The name owner or %NULL if no name owner exists. Free with
* g_free().
* Returns: (nullable): The name owner or %NULL if no name owner
* exists. Free with g_free().
*
* Since: 2.30
*/
......
......@@ -486,8 +486,8 @@ g_file_get_uri_scheme (GFile *file)
*
* This call does no blocking I/O.
*
* Returns: string containing the #GFile's base name, or %NULL
* if given #GFile is invalid. The returned string should be
* Returns: (nullable): string containing the #GFile's base name, or
* %NULL if given #GFile is invalid. The returned string should be
* freed with g_free() when no longer needed.
*/
char *
......@@ -510,9 +510,9 @@ g_file_get_basename (GFile *file)
*
* This call does no blocking I/O.
*
* Returns: string containing the #GFile's path, or %NULL if
* no such path exists. The returned string should be
* freed with g_free() when no longer needed.
* Returns: (nullable): string containing the #GFile's path, or %NULL
* if no such path exists. The returned string should be freed
* with g_free() when no longer needed.
*/
char *
g_file_get_path (GFile *file)
......@@ -680,9 +680,9 @@ g_file_equal (GFile *file1,
*
* This call does no blocking I/O.
*
* Returns: (transfer full): a #GFile structure to the
* parent of the given #GFile or %NULL if there is
* no parent. Free the returned object with g_object_unref().
* Returns: (nullable) (transfer full): a #GFile structure to the
* parent of the given #GFile or %NULL if there is no parent. Free
* the returned object with g_object_unref().
*/
GFile *
g_file_get_parent (GFile *file)
......@@ -849,10 +849,10 @@ g_file_has_prefix (GFile *file,
*
* This call does no blocking I/O.
*
* Returns: string with the relative path from @descendant
* to @parent, or %NULL if @descendant doesn't have @parent
* as prefix. The returned string should be freed with g_free()
* when no longer needed.
* Returns: (nullable): string with the relative path from @descendant
* to @parent, or %NULL if @descendant doesn't have @parent as
* prefix. The returned string should be freed with g_free() when
* no longer needed.
*/
char *
g_file_get_relative_path (GFile *parent,
......
......@@ -191,8 +191,9 @@ g_file_enumerator_init (GFileEnumerator *enumerator)
* enumerator is at the end, %NULL will be returned and @error will
* be unset.
*
* Returns: (transfer full): A #GFileInfo or %NULL on error or end of enumerator.
* Free the returned object with g_object_unref() when no longer needed.
* Returns: (nullable) (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 *
g_file_enumerator_next_file (GFileEnumerator *enumerator,
......
......@@ -619,9 +619,9 @@ g_file_info_has_namespace (GFileInfo *info,
*
* Lists the file info structure's attributes.
*
* Returns: (array zero-terminated=1) (transfer full): a null-terminated array of strings of all of the
* possible attribute types for the given @name_space, or
* %NULL on error.
* Returns: (nullable) (array zero-terminated=1) (transfer full): a
* null-terminated array of strings of all of the possible attribute
* types for the given @name_space, or %NULL on error.
**/
char **
g_file_info_list_attributes (GFileInfo *info,
......
......@@ -203,8 +203,8 @@ g_icon_to_string_tokenized (GIcon *icon, GString *s)
* simply the name (such as `network-server`).
*
* Virtual: to_tokens
* Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't
* be serialized. Use g_free() to free.
* Returns: (nullable): An allocated NUL-terminated UTF8 string or
* %NULL if @icon can't be serialized. Use g_free() to free.
*
* Since: 2.20
*/
......
......@@ -60,11 +60,12 @@ g_loadable_icon_default_init (GLoadableIconIface *iface)
* g_loadable_icon_load:
* @icon: a #GLoadableIcon.
* @size: an integer.
* @type: (out) (allow-none): a location to store the type of the
* loaded icon, %NULL to ignore.
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
* @error: a #GError location to store the error occurring, or %NULL to
* @type: (out) (optional): a location to store the type of the loaded
* icon, %NULL to ignore.
* @cancellable: (allow-none): optional #GCancellable object, %NULL to
* ignore.
* @error: a #GError location to store the error occurring, or %NULL
* to ignore.
*
* Loads a loadable icon. For the asynchronous version of this function,
* see g_loadable_icon_load_async().
......@@ -120,8 +121,8 @@ g_loadable_icon_load_async (GLoadableIcon *icon,
* g_loadable_icon_load_finish:
* @icon: a #GLoadableIcon.
* @res: a #GAsyncResult.
* @type: (out) (allow-none): a location to store the type of the
* loaded icon, %NULL to ignore.
* @type: (out) (optional): a location to store the type of the loaded
* icon, %NULL to ignore.
* @error: a #GError location to store the error occurring, or %NULL to
* ignore.
*
......
......@@ -159,8 +159,8 @@ g_pollable_input_stream_default_read_nonblocking (GPollableInputStream *stream,
/**
* g_pollable_input_stream_read_nonblocking:
* @stream: a #GPollableInputStream
* @buffer: a buffer to read data into (which should be at least @count
* bytes long).
* @buffer: (array length=count) (element-type guint8): a buffer to
* read data into (which should be at least @count bytes long).
* @count: the number of bytes you want to read
* @cancellable: (allow-none): a #GCancellable, or %NULL
* @error: #GError for error reporting, or %NULL to ignore.
......
......@@ -169,7 +169,8 @@ g_pollable_source_new_full (gpointer pollable_stream,
/**
* g_pollable_stream_read:
* @stream: a #GInputStream
* @buffer: a buffer to read data into
* @buffer: (array length=count) (element-type guint8): a buffer to
* read data into
* @count: the number of bytes to read
* @blocking: whether to do blocking I/O
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
......
......@@ -394,7 +394,7 @@ g_settings_schema_source_get_default (void)
*
* If the schema isn't found, %NULL is returned.
*
* Returns: (transfer full): a new #GSettingsSchema
* Returns: (nullable) (transfer full): a new #GSettingsSchema
*
* Since: 2.32
**/
......
......@@ -121,7 +121,7 @@ g_tls_client_connection_default_init (GTlsClientConnectionInterface *iface)
G_PARAM_STATIC_STRINGS));
/**
* GTlsClientConnection:accepted-cas:
* GTlsClientConnection:accepted-cas: (type GLib.List) (element-type GLib.ByteArray):
*
* A list of the distinguished names of the Certificate Authorities
* that the server will accept client certificates signed by. If the
......
......@@ -568,7 +568,9 @@ g_tls_database_verify_chain_finish (GTlsDatabase *self,
* and between applications. If a certificate is modified in the database,
* then it is not guaranteed that this handle will continue to point to it.
*
* Returns: (allow-none): a newly allocated string containing the handle.
* Returns: (nullable): a newly allocated string containing the
* handle.
*
* Since: 2.30
*/
gchar*
......
......@@ -641,8 +641,8 @@ g_volume_enumerate_identifiers (GVolume *volume)
* implementations to find the underlying mount to shadow, see
* g_mount_is_shadowed() for more details.
*
* Returns: (transfer full): the activation root of @volume or %NULL. Use
* g_object_unref() to free.
* Returns: (nullable) (transfer full): the activation root of @volume
* or %NULL. Use g_object_unref() to free.
*
* Since: 2.18
*/
......
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