pbutils: More gtk-doc annotations

diff --git a/gst-libs/gst/pbutils/encoding-target.c b/gst-libs/gst/pbutils/encoding-target.c
index b62895c..cc8cac3 100644 (file)
--- 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 (file)
--- 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 (file)
--- 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 (file)
--- 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 (file)
--- 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,