discoverer: Documentation updates

Some cosmetic changes and expands on some bits of the documentation to
make it more newbie-friendly.

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 91fb569f6..41235a09e 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
 <SUBSECTION>
 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 3cf3562e4..2edf8e923 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 fa5b742e5..bc99f43c7 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 da8eb58b3..671dbaa4e 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
  */