From 3ee2ad255b09a66e5184de6b9c642158bf4c9089 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Tim-Philipp=20M=C3=BCller?= <tim@centricular.net>
Date: Wed, 17 Oct 2012 19:59:57 +0100
Subject: [PATCH] audiocdsrc: mention TOCs in docs

---
 gst-libs/gst/audio/gstaudiocdsrc.c | 15 ++++++++++++++-
 gst-libs/gst/audio/gstaudiocdsrc.h | 18 +++++++-----------
 2 files changed, 21 insertions(+), 12 deletions(-)

diff --git a/gst-libs/gst/audio/gstaudiocdsrc.c b/gst-libs/gst/audio/gstaudiocdsrc.c
index 350dadf..b698e96 100644
--- a/gst-libs/gst/audio/gstaudiocdsrc.c
+++ b/gst-libs/gst/audio/gstaudiocdsrc.c
@@ -38,12 +38,12 @@
  * SECTION:gstaudiocdsrc
  * @short_description: Base class for Audio CD sources
  *
- * <refsect2>
  * <para>
  * Provides a base class for CD digital audio (CDDA) sources, which handles
  * things like seeking, querying, discid calculation, tags, and buffer
  * timestamping.
  * </para>
+ * <refsect2>
  * <title>Using GstAudioCdSrc-based elements in applications</title>
  * <para>
  * GstAudioCdSrc registers two #GstFormat<!-- -->s of its own, namely
@@ -70,6 +70,8 @@
  * setting a new cdda://n+1 URI on playbin (as setting a new URI on playbin
  * involves closing and re-opening the CD device, which is much much slower).
  * </para>
+ * <refsect2>
+ * </refsect2>
  * <title>Tags and meta-information</title>
  * <para>
  * CDDA sources will automatically emit a number of tags, details about which
@@ -79,6 +81,17 @@
  * among others.
  * </para>
  * </refsect2>
+ * <refsect2>
+ * <title>Tracks and Table of Contents (TOC)</title>
+ * <para>
+ * Applications will be informed of the available tracks via a TOC message
+ * on the pipeline's #GstBus. The #GstToc will contain a #GstTocEntry for
+ * each track, with information about each track. The duration for each
+ * track can be retrieved via the #GST_TAG_DURATION tag from each entry's
+ * tag list, or calculated via gst_toc_entry_get_start_stop_times().
+ * The track entries in the TOC will be sorted by track number.
+ * </para>
+ * </refsect2>
  */
 
 #ifdef HAVE_CONFIG_H
diff --git a/gst-libs/gst/audio/gstaudiocdsrc.h b/gst-libs/gst/audio/gstaudiocdsrc.h
index 27aee92..88c9628 100644
--- a/gst-libs/gst/audio/gstaudiocdsrc.h
+++ b/gst-libs/gst/audio/gstaudiocdsrc.h
@@ -61,7 +61,14 @@ typedef enum {
  * @tags: Track-specific tags (e.g. from cd-text information), or NULL
  *
  * CD track abstraction to communicate TOC entries to the base class.
+ *
+ * This structure is only for use by sub-classed in connection with
+ * gst_audio_cd_src_add_track().
+ *
+ * Applications will be informed of the available tracks via a TOC message
+ * on the pipeline's #GstBus instead.
  */
+/* FIXME 2.0: remove this struct and pass values directly to _add_track() */
 struct _GstAudioCdSrcTrack {
   gboolean     is_audio;      /* TRUE if this is an audio track             */
   guint        num;           /* real track number (usually starts from 1)  */
@@ -128,17 +135,6 @@ GType    gst_audio_cd_src_mode_get_type (void);
 gboolean gst_audio_cd_src_add_track (GstAudioCdSrc      * src,
                                      GstAudioCdSrcTrack * track);
 
-#if 0
-/*
- * GST_TAG_CDDA_TRACK_TAGS:
- *
- * Tag details for all available tracks
- * FiXME: find out which type we want for this!
- */
-#define GST_TAG_CDDA_TRACK_TAGS               "track-tags"
-#endif
-
 G_END_DECLS
 
 #endif /* __GST_AUDIO_CD_SRC_H__ */
-
-- 
2.7.4