mpegts: Improve documentation

* Add a base page for the library
* Add pages for the base MPEG-TS section and descriptors
* Add pages for the known variants
* Add documentation on more fields/sections/types
* Remove some fixmes that were ... fixed

7 files changed, 101 insertions, 10 deletions

diff --git a/gst-libs/gst/mpegts/gst-dvb-descriptor.c b/gst-libs/gst/mpegts/gst-dvb-descriptor.c
index 00cc92d74f..17b2845cde 100644
--- a/gst-libs/gst/mpegts/gst-dvb-descriptor.c
+++ b/gst-libs/gst/mpegts/gst-dvb-descriptor.c
@@ -27,6 +27,14 @@
 #include "gstmpegts-private.h"
 
 
+/**
+ * SECTION:gst-dvb-descriptor
+ * @title: DVB variants of MPEG-TS descriptors
+ * @short_description: Descriptors for the various DVB specifications
+ * @include: gst/mpegts/mpegts.h
+ *
+ */
+
 /*
  * TODO
  *
diff --git a/gst-libs/gst/mpegts/gst-dvb-descriptor.h b/gst-libs/gst/mpegts/gst-dvb-descriptor.h
index 0af814cceb..9fdde7c671 100644
--- a/gst-libs/gst/mpegts/gst-dvb-descriptor.h
+++ b/gst-libs/gst/mpegts/gst-dvb-descriptor.h
@@ -34,6 +34,16 @@
 
 #include <gst/gst.h>
 
+/**
+ * GstMpegTsDVBDescriptorType:
+ *
+ * The type of #GstMpegTsDescriptor
+ *
+ * These values correspond to the registered descriptor type from
+ * the various DVB specifications.
+ *
+ * Consult the relevant specifications for more details.
+ */
 typedef enum {
   /* 64-127 DVB tags ETSI EN 300 468
    * (Specification for Service Information (SI) in DVB systems)
@@ -197,8 +207,6 @@ gboolean gst_mpegts_descriptor_parse_satellite_delivery_system (const GstMpegTsD
 								GstMpegTsSatelliteDeliverySystemDescriptor *res);
 
 
-/* FIXME : Implement */
-
 /* GST_MTS_DESC_DVB_CABLE_DELIVERY_SYSTEM (0x44) */
 typedef enum {
   GST_MPEGTS_CABLE_OUTER_FEC_UNDEFINED = 0,
@@ -273,7 +281,6 @@ typedef enum {
   GST_DVB_SERVICE_RESERVED_FF
 } GstMpegTsDVBServiceType;
 
-/* FIXME : enum type for service_type ? */
 gboolean gst_mpegts_descriptor_parse_dvb_service (const GstMpegTsDescriptor *descriptor,
 						  GstMpegTsDVBServiceType *service_type,
 						  gchar **service_name,
diff --git a/gst-libs/gst/mpegts/gst-dvb-section.c b/gst-libs/gst/mpegts/gst-dvb-section.c
index fe3d09f431..9e3cea0de4 100644
--- a/gst-libs/gst/mpegts/gst-dvb-section.c
+++ b/gst-libs/gst/mpegts/gst-dvb-section.c
@@ -35,6 +35,15 @@
 #include "mpegts.h"
 #include "gstmpegts-private.h"
 
+/**
+ * SECTION:gst-dvb-section
+ * @title: DVB variants of MPEG-TS sections
+ * @short_description: Sections for the various DVB specifications
+ * @include: gst/mpegts/mpegts.h
+ *
+ */
+
+
 /*
  * TODO
  *
diff --git a/gst-libs/gst/mpegts/gst-dvb-section.h b/gst-libs/gst/mpegts/gst-dvb-section.h
index 465d614ca2..af85631536 100644
--- a/gst-libs/gst/mpegts/gst-dvb-section.h
+++ b/gst-libs/gst/mpegts/gst-dvb-section.h
@@ -129,7 +129,7 @@ typedef struct _GstMpegTsNIT GstMpegTsNIT;
  * GstMpegTsNITStream:
  * @transport_stream_id:
  * @original_network_id:
- * @descriptors: (element-type GstMpegTsDescriptor)
+ * @descriptors: (element-type GstMpegTsDescriptor):
  *
  */
 struct _GstMpegTsNITStream
@@ -143,8 +143,8 @@ struct _GstMpegTsNITStream
 /**
  * GstMpegTsNIT:
  * @actual_network: Whether this NIT corresponds to the actual stream
- * @descriptors: (element-type GstMpegTsDescriptor) the global descriptors
- * @streams: (element-type GstMpegTsNITStream) the streams
+ * @descriptors: (element-type GstMpegTsDescriptor): the global descriptors
+ * @streams: (element-type GstMpegTsNITStream): the streams
  *
  * Network Information Table (ISO/IEC 13818-1 / EN 300 468)
  *
@@ -182,13 +182,13 @@ struct _GstMpegTsBATStream
 
 /**
  * GstMpegTsBAT:
+ * @descriptors: (element-type GstMpegTsDescriptor):
+ * @streams: (element-type GstMpegTsBATStream):
  *
  * DVB Bouquet Association Table (EN 300 468)
  */
 struct _GstMpegTsBAT
 {
-  gboolean    actual_network;
-
   GArray     *descriptors;
 
   GPtrArray  *streams;
diff --git a/gst-libs/gst/mpegts/gstmpegtsdescriptor.c b/gst-libs/gst/mpegts/gstmpegtsdescriptor.c
index 9850b307b0..f890b0aace 100644
--- a/gst-libs/gst/mpegts/gstmpegtsdescriptor.c
+++ b/gst-libs/gst/mpegts/gstmpegtsdescriptor.c
@@ -28,12 +28,34 @@
 
 /**
  * SECTION:gstmpegtsdescriptor
- * @short_description: Convenience library for using MPEG-TS descriptors
+ * @title: Base MPEG-TS descriptors
+ * @short_description: Descriptors for ITU H.222.0 | ISO/IEC 13818-1 
+ * @include: gst/mpegts/mpegts.h
+ *
+ * These are the base descriptor types and methods.
  *
  * For more details, refer to the ITU H.222.0 or ISO/IEC 13818-1 specifications
  * and other specifications mentionned in the documentation.
  */
 
+/* FIXME : Move this to proper file once we have a C file for ATSC/ISDB descriptors */
+/**
+ * SECTION:gst-atsc-descriptor
+ * @title: ATSC variants of MPEG-TS descriptors
+ * @short_description: Descriptors for the various ATSC specifications
+ * @include: gst/mpegts/mpegts.h
+ *
+ */
+
+/**
+ * SECTION:gst-isdb-descriptor
+ * @title: ISDB variants of MPEG-TS descriptors
+ * @short_description: Descriptors for the various ISDB specifications
+ * @include: gst/mpegts/mpegts.h
+ *
+ */
+
+
 /*
  * TODO
  *
diff --git a/gst-libs/gst/mpegts/gstmpegtsdescriptor.h b/gst-libs/gst/mpegts/gstmpegtsdescriptor.h
index 233f3aa686..2ac27b16d0 100644
--- a/gst-libs/gst/mpegts/gstmpegtsdescriptor.h
+++ b/gst-libs/gst/mpegts/gstmpegtsdescriptor.h
@@ -64,6 +64,9 @@
  *
  * The type of #GstMpegTsDescriptor
  *
+ * These values correspond to the registered descriptor type from
+ * the base MPEG-TS specifications (ITU H.222.0 | ISO/IEC 13818-1).
+ *
  * Consult the relevant specifications for more details.
  */
 typedef enum {
@@ -132,12 +135,28 @@ typedef enum {
   /* 55-63 ITU-T Rec. H.222.0 | ISO/IEC 13818-1 Reserved */
 } GstMpegTsDescriptorType;
 
+/**
+ * GstMpegTsMiscDescriptorType:
+ *
+ * The type of #GstMpegTsDescriptor
+ *
+ * These values correspond to miscellaneous descriptor types that are
+ * not yet identified from known specifications.
+ */
 typedef enum {
   /* 0x80 - 0xFE are user defined */
   GST_MTS_DESC_AC3_AUDIO_STREAM                 = 0x81,
   GST_MTS_DESC_DTG_LOGICAL_CHANNEL              = 0x83,    /* from DTG D-Book */
 } GstMpegTsMiscDescriptorType;
 
+/**
+ * GstMpegTsATSCDescriptorType:
+ *
+ * These values correspond to the registered descriptor type from
+ * the various ATSC specifications.
+ *
+ * Consult the relevant specifications for more details.
+ */
 typedef enum {
   /* ATSC A/65 2009 */
   GST_MTS_DESC_ATSC_STUFFING                    = 0x80,
@@ -167,6 +186,14 @@ typedef enum {
   GST_MTS_DESC_ATSC_GROUP_LINK                  = 0xB8,
 } GstMpegTsATSCDescriptorType;
 
+/**
+ * GstMpegTsISDBDescriptorType:
+ *
+ * These values correspond to the registered descriptor type from
+ * the various ISDB specifications.
+ *
+ * Consult the relevant specifications for more details.
+ */
 typedef enum {
   /* ISDB ARIB B10 v4.6 */
   GST_MTS_DESC_ISDB_HIERARCHICAL_TRANSMISSION   = 0xC0,
diff --git a/gst-libs/gst/mpegts/gstmpegtssection.c b/gst-libs/gst/mpegts/gstmpegtssection.c
index 339444b056..1cded52170 100644
--- a/gst-libs/gst/mpegts/gstmpegtssection.c
+++ b/gst-libs/gst/mpegts/gstmpegtssection.c
@@ -36,13 +36,31 @@
 #include "gstmpegts-private.h"
 
 /**
+ * SECTION:gstmpegts
+ * @title: Mpeg-ts helper library
+ * @short_description: Mpeg-ts helper library for plugins and applications
+ * @include: gst/mpegts/mpegts.h
+ */
+
+/**
  * SECTION:gstmpegtssection
- * @short_description: Convenience library for using MPEG-TS sections 
+ * @title: Base MPEG-TS sections
+ * @short_description: Sections for ITU H.222.0 | ISO/IEC 13818-1 
+ * @include: gst/mpegts/mpegts.h
  *
  * For more details, refer to the ITU H.222.0 or ISO/IEC 13818-1 specifications
  * and other specifications mentionned in the documentation.
  */
 
+/* FIXME : Move this to proper file once we have a C file for it */
+/**
+ * SECTION:gst-atsc-section
+ * @title: ATSC variants of MPEG-TS sections
+ * @short_description: Sections for the various ATSC specifications
+ * @include: gst/mpegts/mpegts.h
+ *
+ */
+
 /*
  * TODO
  *