From 9f6bcdd5ee629ebe73c3a85d819e0863785cea13 Mon Sep 17 00:00:00 2001 From: Edward Hervey Date: Tue, 21 Dec 2010 18:51:29 +0100 Subject: [PATCH] pbutils: More gtk-doc annotations --- gst-libs/gst/pbutils/encoding-target.c | 29 ++++++++----- gst-libs/gst/pbutils/gstdiscoverer-types.c | 70 +++++++++++++++++------------- gst-libs/gst/pbutils/gstdiscoverer.c | 8 ++-- gst-libs/gst/pbutils/install-plugins.c | 4 +- gst-libs/gst/pbutils/missing-plugins.c | 10 ++--- 5 files changed, 69 insertions(+), 52 deletions(-) diff --git a/gst-libs/gst/pbutils/encoding-target.c b/gst-libs/gst/pbutils/encoding-target.c index b62895c..cc8cac3 100644 --- a/gst-libs/gst/pbutils/encoding-target.c +++ b/gst-libs/gst/pbutils/encoding-target.c @@ -101,7 +101,7 @@ gst_encoding_target_class_init (GstMiniObjectClass * klass) * * Since: 0.10.32 * - * Returns: The name of the @target. + * Returns: (transfer none): The name of the @target. */ const gchar * gst_encoding_target_get_name (GstEncodingTarget * target) @@ -115,7 +115,7 @@ gst_encoding_target_get_name (GstEncodingTarget * target) * * Since: 0.10.32 * - * Returns: The category of the @target. + * Returns: (transfer none): The category of the @target. */ const gchar * gst_encoding_target_get_category (GstEncodingTarget * target) @@ -129,7 +129,7 @@ gst_encoding_target_get_category (GstEncodingTarget * target) * * Since: 0.10.32 * - * Returns: The description of the @target. + * Returns: (transfer none): The description of the @target. */ const gchar * gst_encoding_target_get_description (GstEncodingTarget * target) @@ -143,7 +143,8 @@ gst_encoding_target_get_description (GstEncodingTarget * target) * * Since: 0.10.32 * - * Returns: A list of #GstEncodingProfile(s) this @target handles. + * Returns: (transfer none) (element-type Gst.EncodingProfile): A list of + * #GstEncodingProfile(s) this @target handles. */ const GList * gst_encoding_target_get_profiles (GstEncodingTarget * target) @@ -189,9 +190,12 @@ validate_name (const gchar * name) /** * gst_encoding_target_new: * @name: The name of the target. - * @category: The name of the category to which this @target belongs. - * @description: A description of #GstEncodingTarget in the current locale. - * @profiles: A #GList of #GstEncodingProfile. + * @category: (transfer none): The name of the category to which this @target + * belongs. + * @description: (transfer none): A description of #GstEncodingTarget in the + * current locale. + * @profiles: (transfer none) (element-type Gst.EncodingProfile): A #GList of + * #GstEncodingProfile. * * Creates a new #GstEncodingTarget. * @@ -201,8 +205,8 @@ validate_name (const gchar * name) * * Since: 0.10.32 * - * Returns: The newly created #GstEncodingTarget or %NULL if there was an - * error. + * Returns: (transfer full): The newly created #GstEncodingTarget or %NULL if + * there was an error. */ GstEncodingTarget * @@ -252,7 +256,7 @@ invalid_category: /** * gst_encoding_target_add_profile: * @target: the #GstEncodingTarget to add a profile to - * @profile: the #GstEncodingProfile to add + * @profile: (transfer full): the #GstEncodingProfile to add * * Adds the given @profile to the @target. * @@ -642,7 +646,8 @@ empty_name: * * Since: 0.10.32 * - * Returns: The #GstEncodingTarget contained in the file, else %NULL + * Returns: (transfer full): The #GstEncodingTarget contained in the file, else + * %NULL */ GstEncodingTarget * @@ -677,7 +682,7 @@ beach: * * Since: 0.10.32 * - * Returns: The #GstEncodingTarget if available, else %NULL + * Returns: (transfer full): The #GstEncodingTarget if available, else %NULL. */ GstEncodingTarget * diff --git a/gst-libs/gst/pbutils/gstdiscoverer-types.c b/gst-libs/gst/pbutils/gstdiscoverer-types.c index 2a5839b..3cf3562 100644 --- a/gst-libs/gst/pbutils/gstdiscoverer-types.c +++ b/gst-libs/gst/pbutils/gstdiscoverer-types.c @@ -382,8 +382,9 @@ gst_discoverer_stream_info_list_free (GList * infos) * Finds the #GstDiscovererStreamInfo contained in @info that match the * given @streamtype. * - * Returns: A #GList of matching #GstDiscovererStreamInfo. The caller should - * free it with #gst_discoverer_stream_info_list_free. + * Returns: (transfer full) (element-type Gst.DiscovererStreamInfo): A #GList of + * matching #GstDiscovererStreamInfo. The caller should free it with + * gst_discoverer_stream_info_list_free(). * * Since: 0.10.31 */ @@ -408,8 +409,9 @@ gst_discoverer_info_get_streams (GstDiscovererInfo * info, GType streamtype) * * Finds all the #GstDiscovererAudioInfo contained in @info * - * Returns: A #GList of matching #GstDiscovererStreamInfo. The caller should - * free it with #gst_discoverer_stream_info_list_free. + * Returns: (transfer full) (element-type Gst.DiscovererStreamInfo): A #GList of + * matching #GstDiscovererStreamInfo. The caller should free it with + * gst_discoverer_stream_info_list_free(). * * Since: 0.10.31 */ @@ -425,8 +427,9 @@ gst_discoverer_info_get_audio_streams (GstDiscovererInfo * info) * * Finds all the #GstDiscovererVideoInfo contained in @info * - * Returns: A #GList of matching #GstDiscovererStreamInfo. The caller should - * free it with #gst_discoverer_stream_info_list_free. + * Returns: (transfer full) (element-type Gst.DiscovererStreamInfo): A #GList of + * matching #GstDiscovererStreamInfo. The caller should free it with + * gst_discoverer_stream_info_list_free(). * * Since: 0.10.31 */ @@ -442,8 +445,9 @@ gst_discoverer_info_get_video_streams (GstDiscovererInfo * info) * * Finds all the #GstDiscovererContainerInfo contained in @info * - * Returns: A #GList of matching #GstDiscovererStreamInfo. The caller should - * free it with #gst_discoverer_stream_info_list_free. + * Returns: (transfer full) (element-type Gst.DiscovererStreamInfo): A #GList of + * matching #GstDiscovererStreamInfo. The caller should free it with + * gst_discoverer_stream_info_list_free(). * * Since: 0.10.31 */ @@ -493,8 +497,9 @@ gst_discoverer_stream_info_get_stream_type_nick (GstDiscovererStreamInfo * info) * gst_discoverer_stream_info_get_previous: * @info: a #GstDiscovererStreamInfo * - * Returns: the previous #GstDiscovererStreamInfo in a chain. %NULL for starting - * points. Unref with #gst_discoverer_stream_info_unref after usage. + * Returns: (transfer full): the previous #GstDiscovererStreamInfo in a chain. + * %NULL for starting points. Unref with #gst_discoverer_stream_info_unref + * after usage. * * Since: 0.10.31 */ @@ -512,7 +517,8 @@ gst_discoverer_stream_info_get_previous (GstDiscovererStreamInfo * info) * gst_discoverer_stream_info_get_next: * @info: a #GstDiscovererStreamInfo * - * Returns: the next #GstDiscovererStreamInfo in a chain. %NULL for final streams. + * Returns: (transfer full): the next #GstDiscovererStreamInfo in a chain. %NULL + * for final streams. * Unref with #gst_discoverer_stream_info_unref after usage. * * Since: 0.10.31 @@ -532,7 +538,8 @@ gst_discoverer_stream_info_get_next (GstDiscovererStreamInfo * info) * gst_discoverer_stream_info_get_caps: * @info: a #GstDiscovererStreamInfo * - * Returns: the #GstCaps of the stream. Unref with #gst_caps_unref after usage. + * Returns: (transfer full): the #GstCaps of the stream. Unref with + * #gst_caps_unref after usage. * * Since: 0.10.31 */ @@ -550,8 +557,8 @@ gst_discoverer_stream_info_get_caps (GstDiscovererStreamInfo * info) * gst_discoverer_stream_info_get_tags: * @info: a #GstDiscovererStreamInfo * - * Returns: the tags contained in this stream. If you wish to use the tags after - * the life-time of @info you will need to copy them. + * Returns: (transfer none): the tags contained in this stream. If you wish to + * use the tags after the life-time of @info you will need to copy them. * * Since: 0.10.31 */ @@ -568,9 +575,9 @@ gst_discoverer_stream_info_get_tags (GstDiscovererStreamInfo * info) * gst_discoverer_stream_info_get_misc: * @info: a #GstDiscovererStreamInfo * - * Returns: additional information regarding the stream (for example codec version, - * profile, etc..). If you wish to use the #GstStructure after the life-time of - * @info you will need to copy it. + * Returns: (transfer none): additional information regarding the stream (for + * example codec version, profile, etc..). If you wish to use the #GstStructure + * after the life-time of @info you will need to copy it. * * Since: 0.10.31 */ @@ -588,8 +595,9 @@ gst_discoverer_stream_info_get_misc (GstDiscovererStreamInfo * info) * gst_discoverer_container_info_get_streams: * @info: a #GstDiscovererStreamInfo * - * Returns: the list of #GstDiscovererStreamInfo this container stream offers. - * Free with #gst_discoverer_stream_info_list_free after usage. + * Returns: (transfer full) (element-type Gst.DiscovererStreamInfo): the list of + * #GstDiscovererStreamInfo this container stream offers. + * Free with gst_discoverer_stream_info_list_free() after usage. * * Since: 0.10.31 */ @@ -822,8 +830,8 @@ gst_discoverer_video_info_is_image (const GstDiscovererVideoInfo * info) * gst_discoverer_info_get_uri: * @info: a #GstDiscovererInfo * - * Returns: the URI to which this information corresponds to. Copy it if you - * wish to use it after the life-time of @info. + * Returns: (transfer none): the URI to which this information corresponds to. + * Copy it if you wish to use it after the life-time of @info. * * Since: 0.10.31 */ @@ -845,9 +853,10 @@ DISCOVERER_INFO_ACCESSOR_CODE (result, GstDiscovererResult, GST_DISCOVERER_OK); * gst_discoverer_info_get_stream_info: * @info: a #GstDiscovererInfo * - * Returns: the structure (or topology) of the URI as a #GstDiscovererStreamInfo. + * Returns: (transfer full): the structure (or topology) of the URI as a + * #GstDiscovererStreamInfo. * This structure can be traversed to see the original hierarchy. Unref with - * #gst_discoverer_stream_info_unref after usage. + * gst_discoverer_stream_info_unref() after usage. * * Since: 0.10.31 */ @@ -866,8 +875,9 @@ gst_discoverer_info_get_stream_info (GstDiscovererInfo * info) * gst_discoverer_info_get_stream_list: * @info: a #GstDiscovererInfo * - * Returns: the list of all streams contained in the #info. Free after usage - * with #gst_discoverer_stream_info_list_free. + * Returns: (transfer full) (element-type Gst.DiscovererStreamInfo): the list of + * all streams contained in the #info. Free after usage + * with gst_discoverer_stream_info_list_free(). * * Since: 0.10.31 */ @@ -912,9 +922,9 @@ DISCOVERER_INFO_ACCESSOR_CODE (seekable, gboolean, FALSE); * gst_discoverer_info_get_misc: * @info: a #GstDiscovererInfo * - * Returns: Miscellaneous information stored as a #GstStructure (for example: - * information about missing plugins). If you wish to use the #GstStructure - * after the life-time of @info, you will need to copy it. + * Returns: (transfer none): Miscellaneous information stored as a #GstStructure + * (for example: information about missing plugins). If you wish to use the + * #GstStructure after the life-time of @info, you will need to copy it. * * Since: 0.10.31 */ @@ -925,8 +935,8 @@ DISCOVERER_INFO_ACCESSOR_CODE (misc, const GstStructure *, NULL); * gst_discoverer_info_get_tags: * @info: a #GstDiscovererInfo * - * Returns: all tags contained in the %URI. If you wish to use the tags after - * the life-time of @info, you will need to copy them. + * Returns: (transfer none): all tags contained in the %URI. If you wish to use + * the tags after the life-time of @info, you will need to copy them. * * Since: 0.10.31 */ diff --git a/gst-libs/gst/pbutils/gstdiscoverer.c b/gst-libs/gst/pbutils/gstdiscoverer.c index cdeb913..fa5b742 100644 --- a/gst-libs/gst/pbutils/gstdiscoverer.c +++ b/gst-libs/gst/pbutils/gstdiscoverer.c @@ -1346,9 +1346,11 @@ gst_discoverer_discover_uri_async (GstDiscoverer * discoverer, * * Synchronously discovers the given @uri. * - * A copy of @uri will be done internally, the caller can safely g_free() afterwards. + * A copy of @uri will be done internally, the caller can safely g_free() + * afterwards. * - * Returns: see #GstDiscovererInfo. The caller must unref this structure after use. + * Returns: (transfer full): the result of the scanning. Can be %NULL iif an + * error occured. * * Since: 0.10.31 */ @@ -1400,7 +1402,7 @@ gst_discoverer_discover_uri (GstDiscoverer * discoverer, const gchar * uri, * * Creates a new #GstDiscoverer with the provided timeout. * - * Returns: The new #GstDiscoverer. Free with gst_object_unref() when done. + * Returns: (transfer full): The new #GstDiscoverer. * If an error happened when creating the discoverer, @err will be set * accordingly and %NULL will be returned. If @err is set, the caller must * free it when no longer needed using g_error_free(). diff --git a/gst-libs/gst/pbutils/install-plugins.c b/gst-libs/gst/pbutils/install-plugins.c index 60a4263..9b5f45e 100644 --- a/gst-libs/gst/pbutils/install-plugins.c +++ b/gst-libs/gst/pbutils/install-plugins.c @@ -608,8 +608,8 @@ gst_install_plugins_installer_exited (GPid pid, gint status, gpointer data) * gst_install_plugins_async: * @details: NULL-terminated array of installer string details (see below) * @ctx: a #GstInstallPluginsContext, or NULL - * @func: the function to call when the installer program returns - * @user_data: the user data to pass to @func when called, or NULL + * @func: (scope async): the function to call when the installer program returns + * @user_data: (closure): the user data to pass to @func when called, or NULL * * Requests plugin installation without blocking. Once the plugins have been * installed or installation has failed, @func will be called with the result diff --git a/gst-libs/gst/pbutils/missing-plugins.c b/gst-libs/gst/pbutils/missing-plugins.c index ca82ce5..1b6d44b 100644 --- a/gst-libs/gst/pbutils/missing-plugins.c +++ b/gst-libs/gst/pbutils/missing-plugins.c @@ -166,7 +166,7 @@ copy_and_clean_caps (const GstCaps * caps) * that a source element for a particular URI protocol is missing. This * function is mainly for use in plugins. * - * Returns: a new #GstMessage, or NULL on error + * Returns: (transfer full): a new #GstMessage, or NULL on error */ GstMessage * gst_missing_uri_source_message_new (GstElement * element, @@ -199,7 +199,7 @@ gst_missing_uri_source_message_new (GstElement * element, * that a sink element for a particular URI protocol is missing. This * function is mainly for use in plugins. * - * Returns: a new #GstMessage, or NULL on error + * Returns: (transfer full): a new #GstMessage, or NULL on error */ GstMessage * gst_missing_uri_sink_message_new (GstElement * element, const gchar * protocol) @@ -231,7 +231,7 @@ gst_missing_uri_sink_message_new (GstElement * element, const gchar * protocol) * that a certain required element is missing. This function is mainly for * use in plugins. * - * Returns: a new #GstMessage, or NULL on error + * Returns: (transfer full): a new #GstMessage, or NULL on error */ GstMessage * gst_missing_element_message_new (GstElement * element, @@ -263,7 +263,7 @@ gst_missing_element_message_new (GstElement * element, * that a decoder element for a particular set of (fixed) caps is missing. * This function is mainly for use in plugins. * - * Returns: a new #GstMessage, or NULL on error + * Returns: (transfer full): a new #GstMessage, or NULL on error */ GstMessage * gst_missing_decoder_message_new (GstElement * element, @@ -303,7 +303,7 @@ gst_missing_decoder_message_new (GstElement * element, * that an encoder element for a particular set of (fixed) caps is missing. * This function is mainly for use in plugins. * - * Returns: a new #GstMessage, or NULL on error + * Returns: (transfer full): a new #GstMessage, or NULL on error */ GstMessage * gst_missing_encoder_message_new (GstElement * element, -- 2.7.4