From 19d4a5ab4d94b689b8a4e03df217ab2ab28788db Mon Sep 17 00:00:00 2001 From: Arun Raghavan Date: Wed, 5 Jan 2011 15:53:09 +0530 Subject: [PATCH] discoverer: Documentation updates Some cosmetic changes and expands on some bits of the documentation to make it more newbie-friendly. --- docs/libs/gst-plugins-base-libs-sections.txt | 4 +-- gst-libs/gst/pbutils/gstdiscoverer-types.c | 45 ++++++++++++++++++++++++++-- gst-libs/gst/pbutils/gstdiscoverer.c | 15 +++++----- gst-libs/gst/pbutils/gstdiscoverer.h | 20 ++++++++++--- 4 files changed, 68 insertions(+), 16 deletions(-) diff --git a/docs/libs/gst-plugins-base-libs-sections.txt b/docs/libs/gst-plugins-base-libs-sections.txt index 91fb569..41235a0 100644 --- a/docs/libs/gst-plugins-base-libs-sections.txt +++ b/docs/libs/gst-plugins-base-libs-sections.txt @@ -2154,6 +2154,7 @@ gst_discoverer_info_get_stream_list gst_discoverer_info_get_tags gst_discoverer_info_get_uri gst_discoverer_info_get_seekable +gst_discoverer_info_ref gst_discoverer_info_unref GstDiscovererStreamInfo @@ -2169,8 +2170,6 @@ gst_discoverer_stream_info_ref gst_discoverer_stream_info_unref gst_discoverer_stream_info_list_free gst_discoverer_stream_info_get_stream_type_nick -gst_discoverer_info_copy -gst_discoverer_info_ref gst_discoverer_info_get_audio_streams gst_discoverer_info_get_container_streams gst_discoverer_info_get_streams @@ -2225,6 +2224,7 @@ gst_discoverer_audio_info_get_type gst_discoverer_container_info_get_type gst_discoverer_get_type gst_discoverer_info_get_type +gst_discoverer_info_copy gst_discoverer_result_get_type gst_discoverer_stream_info_get_type gst_discoverer_video_info_get_type diff --git a/gst-libs/gst/pbutils/gstdiscoverer-types.c b/gst-libs/gst/pbutils/gstdiscoverer-types.c index 3cf3562..2edf8e9 100644 --- a/gst-libs/gst/pbutils/gstdiscoverer-types.c +++ b/gst-libs/gst/pbutils/gstdiscoverer-types.c @@ -377,7 +377,7 @@ gst_discoverer_stream_info_list_free (GList * infos) /** * gst_discoverer_info_get_streams: * @info: a #GstDiscovererInfo - * @streamtype: a #GType of #GstDiscovererStreamInfo + * @streamtype: a #GType derived from #GstDiscovererStreamInfo * * Finds the #GstDiscovererStreamInfo contained in @info that match the * given @streamtype. @@ -712,8 +712,7 @@ VIDEO_INFO_ACCESSOR_CODE (height, guint, 0); * gst_discoverer_video_info_get_depth: * @info: a #GstDiscovererVideoInfo * - * Returns: the depth in bits of the video stream (only relevant for - * video streams). + * Returns: the depth in bits of the video stream. * * Since: 0.10.31 */ @@ -942,3 +941,43 @@ DISCOVERER_INFO_ACCESSOR_CODE (misc, const GstStructure *, NULL); */ DISCOVERER_INFO_ACCESSOR_CODE (tags, const GstTagList *, NULL); + +/** + * gst_discoverer_info_ref: + * @info: a #GstDiscovererInfo + * + * Increments the reference count of @info. + * + * Returns: the same #GstDiscovererInfo object + * + * Since: 0.10.31 + */ + +/** + * gst_discoverer_info_unref: + * @info: a #GstDiscovererInfo + * + * Decrements the reference count of @info. + * + * Since: 0.10.31 + */ + +/** + * gst_discoverer_stream_info_ref: + * @info: a #GstDiscovererStreamInfo + * + * Increments the reference count of @info. + * + * Returns: the same #GstDiscovererStreamInfo object + * + * Since: 0.10.31 + */ + +/** + * gst_discoverer_stream_info_unref: + * @info: a #GstDiscovererStreamInfo + * + * Decrements the reference count of @info. + * + * Since: 0.10.31 + */ diff --git a/gst-libs/gst/pbutils/gstdiscoverer.c b/gst-libs/gst/pbutils/gstdiscoverer.c index fa5b742..bc99f43 100644 --- a/gst-libs/gst/pbutils/gstdiscoverer.c +++ b/gst-libs/gst/pbutils/gstdiscoverer.c @@ -218,7 +218,7 @@ gst_discoverer_class_init (GstDiscovererClass * klass) * @discoverer: the #GstDiscoverer * @info: the results #GstDiscovererInfo * @error: (type GLib.Error): #GError, which will be non-NULL if an error - * occured during discovery + * occurred during discovery * * Will be emitted when all information on a URI could be discovered. */ @@ -1309,7 +1309,8 @@ gst_discoverer_stop (GstDiscoverer * discoverer) * discovery of the @uri will only take place if gst_discoverer_start() has * been called. * - * A copy of @uri will be done internally, the caller can safely g_free() afterwards. + * A copy of @uri will be made internally, so the caller can safely g_free() + * afterwards. * * Returns: %TRUE if the @uri was succesfully appended to the list of pending * uris, else %FALSE @@ -1342,15 +1343,15 @@ gst_discoverer_discover_uri_async (GstDiscoverer * discoverer, * gst_discoverer_discover_uri: * @discoverer: A #GstDiscoverer * @uri: The URI to run on. - * @err: If an error occured, this field will be filled in. + * @err: If an error occurred, this field will be filled in. * * Synchronously discovers the given @uri. * - * A copy of @uri will be done internally, the caller can safely g_free() + * A copy of @uri will be made internally, so the caller can safely g_free() * afterwards. * - * Returns: (transfer full): the result of the scanning. Can be %NULL iif an - * error occured. + * Returns: (transfer full): the result of the scanning. Can be %NULL if an + * error occurred. * * Since: 0.10.31 */ @@ -1403,7 +1404,7 @@ gst_discoverer_discover_uri (GstDiscoverer * discoverer, const gchar * uri, * Creates a new #GstDiscoverer with the provided timeout. * * Returns: (transfer full): The new #GstDiscoverer. - * If an error happened when creating the discoverer, @err will be set + * If an error occurred 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/gstdiscoverer.h b/gst-libs/gst/pbutils/gstdiscoverer.h index da8eb58..671dbaa 100644 --- a/gst-libs/gst/pbutils/gstdiscoverer.h +++ b/gst-libs/gst/pbutils/gstdiscoverer.h @@ -38,9 +38,21 @@ GType gst_discoverer_stream_info_get_type (void); /** * GstDiscovererStreamInfo: * - * Base structure for informations concerning a media stream. Depending on the @streamtype, - * One can find more media-specific information in #GstDiscovererAudioInfo, - * #GstDiscovererVideoInfo, #GstDiscovererContainerInfo. + * Base structure for information concerning a media stream. Depending on the + * stream type, one can find more media-specific information in + * #GstDiscovererAudioInfo, #GstDiscovererVideoInfo, and + * #GstDiscovererContainerInfo. + * + * The #GstDiscovererStreamInfo represents the topology of the stream. Siblings + * can be iterated over with gst_discoverer_stream_info_get_next() and + * gst_discoverer_stream_info_get_previous(). Children (sub-streams) of a + * stream can be accessed using the #GstDiscovererContainerInfo API. + * + * As a simple example, if you run #GstDiscoverer on an AVI file with one audio + * and one video stream, you will get a #GstDiscovererContainerInfo + * corresponding to the AVI container, which in turn will have a + * #GstDiscovererAudioInfo sub-stream and a #GstDiscovererVideoInfo sub-stream + * for the audio and video streams respectively. * * Since: 0.10.31 */ @@ -102,7 +114,7 @@ guint gst_discoverer_audio_info_get_max_bitrate(const GstDiscovererAudioInfo* in /** * GstDiscovererVideoInfo: * - * #GstDiscovererStreamInfo specific to video streams. + * #GstDiscovererStreamInfo specific to video streams (this includes images). * * Since: 0.10.31 */ -- 2.7.4