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

docs/libs/gst-plugins-bad-libs-docs.sgml

@@ -42,8 +42,14 @@
         <filename>gstreamer-plugins-bad-&GST_API_VERSION;.pc</filename> and adding
         <filename>-lgstmpegts-&GST_API_VERSION;</filename> to the library flags.
       </para>
+      <xi:include href="xml/gstmpegts.xml" />
       <xi:include href="xml/gstmpegtssection.xml" />
       <xi:include href="xml/gstmpegtsdescriptor.xml" />
+      <xi:include href="xml/gst-atsc-section.xml" />
+      <xi:include href="xml/gst-dvb-section.xml" />
+      <xi:include href="xml/gst-atsc-descriptor.xml" />
+      <xi:include href="xml/gst-dvb-descriptor.xml" />
+      <xi:include href="xml/gst-isdb-descriptor.xml" />
     </chapter>
 
     <chapter id="tools">

docs/libs/gst-plugins-bad-libs-sections.txt

@@ -166,17 +166,69 @@ gst_mpeg4_parse_video_packet_header
 <SUBSECTION Private>
 </SECTION>
 
+<SECTION>
+<FILE>gstmpegts</FILE>
+<SUBSECTION Common>
+gst_mpegts_initialize
+</SECTION>
+
 <SECTION>
 <FILE>gstmpegtsdescriptor</FILE>
 <SUBSECTION Common>
 GstMpegTsDescriptor
 GstMpegTsDescriptorType
-GstMpegTsATSCDescriptorType
-GstMpegTsDVBDescriptorType
-GstMpegTsISDBDescriptorType
 GstMpegTsMiscDescriptorType
 gst_mpegts_find_descriptor
 gst_mpegts_parse_descriptors
+<SUBSECTION iso639>
+GstMpegTsISO639LanguageDescriptor
+GstMpegTsIso639AudioType
+gst_mpegts_descriptor_parse_iso_639_language
+gst_mpegts_descriptor_parse_dvb_stream_identifier
+<SUBSECTION logical_channel>
+GstMpegTsLogicalChannel
+GstMpegTsLogicalChannelDescriptor
+gst_mpegts_descriptor_parse_logical_channel
+<SUBSECTION Standard>
+GST_TYPE_MPEG_TS_DVB_CODE_RATE
+GST_TYPE_MPEG_TS_CABLE_OUTER_FEC_SCHEME
+GST_TYPE_MPEG_TS_MODULATION_TYPE
+GST_TYPE_MPEG_TS_SATELLITE_POLARIZATION_TYPE
+GST_TYPE_MPEG_TS_SATELLITE_ROLLOFF
+GST_TYPE_MPEGTS_DESCRIPTOR
+GST_TYPE_MPEG_TS_DVB_SERVICE_TYPE
+GST_TYPE_MPEG_TS_DESCRIPTOR_TYPE
+GST_TYPE_MPEG_TS_ISO639_AUDIO_TYPE
+GST_TYPE_MPEG_TS_ATSC_DESCRIPTOR_TYPE
+GST_TYPE_MPEG_TS_DVB_DESCRIPTOR_TYPE
+GST_TYPE_MPEG_TS_ISDB_DESCRIPTOR_TYPE
+GST_TYPE_MPEG_TS_MISC_DESCRIPTOR_TYPE
+gst_mpegts_descriptor_get_type
+gst_mpeg_ts_cable_outer_fec_scheme_get_type
+gst_mpeg_ts_modulation_type_get_type
+gst_mpeg_ts_satellite_polarization_type_get_type
+gst_mpeg_ts_satellite_rolloff_get_type
+gst_mpeg_ts_dvb_code_rate_get_type
+gst_mpeg_ts_descriptor_type_get_type
+gst_mpeg_ts_atsc_descriptor_type_get_type
+gst_mpeg_ts_dvb_descriptor_type_get_type
+gst_mpeg_ts_isdb_descriptor_type_get_type
+gst_mpeg_ts_misc_descriptor_type_get_type
+gst_mpeg_ts_iso639_audio_type_get_type
+gst_mpeg_ts_dvb_service_type_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gst-atsc-descriptor</FILE>
+GstMpegTsATSCDescriptorType
+<SUBSECTION Standard>
+GST_TYPE_MPEG_TS_ATSC_DESCRIPTOR_TYPE
+gst_mpeg_ts_atsc_descriptor_type_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gst-dvb-descriptor</FILE>
+GstMpegTsDVBDescriptorType
 <SUBSECTION component>
 GstMpegTsComponentDescriptor
 gst_mpegts_descriptor_parse_dvb_component
@@ -201,44 +253,17 @@ gst_mpegts_descriptor_parse_dvb_network_name
 <SUBSECTION service>
 GstMpegTsDVBServiceType
 gst_mpegts_descriptor_parse_dvb_service
-<SUBSECTION iso639>
-GstMpegTsISO639LanguageDescriptor
-GstMpegTsIso639AudioType
-gst_mpegts_descriptor_parse_iso_639_language
-gst_mpegts_descriptor_parse_dvb_stream_identifier
-<SUBSECTION logical_channel>
-GstMpegTsLogicalChannel
-GstMpegTsLogicalChannelDescriptor
-gst_mpegts_descriptor_parse_logical_channel
 <SUBSECTION Standard>
-GST_TYPE_MPEG_TS_DVB_CODE_RATE
+GST_TYPE_MPEG_TSDVB_CODE_RATE
-GST_TYPE_MPEG_TS_CABLE_OUTER_FEC_SCHEME
+gst_mpeg_tsdvb_code_rate_get_type
-GST_TYPE_MPEG_TS_MODULATION_TYPE
+</SECTION>
-GST_TYPE_MPEG_TS_SATELLITE_POLARIZATION_TYPE
+
-GST_TYPE_MPEG_TS_SATELLITE_ROLLOFF
+<SECTION>
-GST_TYPE_MPEGTS_DESCRIPTOR
+<FILE>gst-isdb-descriptor</FILE>
-GST_TYPE_MPEG_TS_DVB_SERVICE_TYPE
+GstMpegTsISDBDescriptorType
-GST_TYPE_MPEG_TS_DESCRIPTOR_TYPE
+<SUBSECTION Standard>
-GST_TYPE_MPEG_TS_ISO639_AUDIO_TYPE
-GST_TYPE_MPEG_TS_RUNNING_STATUS
-GST_TYPE_MPEG_TS_ATSC_DESCRIPTOR_TYPE
-GST_TYPE_MPEG_TS_DVB_DESCRIPTOR_TYPE
 GST_TYPE_MPEG_TS_ISDB_DESCRIPTOR_TYPE
-GST_TYPE_MPEG_TS_MISC_DESCRIPTOR_TYPE
-gst_mpegts_descriptor_get_type
-gst_mpeg_ts_cable_outer_fec_scheme_get_type
-gst_mpeg_ts_modulation_type_get_type
-gst_mpeg_ts_satellite_polarization_type_get_type
-gst_mpeg_ts_satellite_rolloff_get_type
-gst_mpeg_ts_dvb_code_rate_get_type
-gst_mpeg_ts_descriptor_type_get_type
-gst_mpeg_ts_atsc_descriptor_type_get_type
-gst_mpeg_ts_dvb_descriptor_type_get_type
 gst_mpeg_ts_isdb_descriptor_type_get_type
-gst_mpeg_ts_misc_descriptor_type_get_type
-gst_mpeg_ts_iso639_audio_type_get_type
-gst_mpeg_ts_running_status_get_type
-gst_mpeg_ts_dvb_service_type_get_type
 </SECTION>
 
 <SECTION>
@@ -247,8 +272,6 @@ gst_mpeg_ts_dvb_service_type_get_type
 GST_MPEGTS_SECTION_TYPE
 GstMpegTsSection
 GstMpegTsSectionTableID
-GstMpegTsSectionATSCTableID
-GstMpegTsSectionDVBTableID
 GstMpegTsSectionType
 gst_message_new_mpegts_section
 gst_message_parse_mpegts_section
@@ -263,64 +286,83 @@ GstMpegTsPMT
 GstMpegTsPMTStream
 GstMpegTsStreamType
 gst_mpegts_section_get_pmt
+<SUBSECTION TSDT>
+gst_mpegts_section_get_tsdt
+<SUBSECTION CAT>
+gst_mpegts_section_get_cat
+<SUBSECTION Standard>
+GST_TYPE_MPEG_TS_SECTION_TABLE_ID
+GST_TYPE_MPEG_TS_SECTION_TYPE
+GST_TYPE_MPEG_TS_SECTION_DVB_TABLE_ID
+GST_MPEGTS_SECTION
+GST_TYPE_MPEG_TS_STREAM_TYPE
+GST_TYPE_MPEGTS_PMT
+GST_TYPE_MPEGTS_PMT_STREAM
+GST_TYPE_MPEGTS_SECTION
+gst_mpeg_ts_section_table_id_get_type
+gst_mpeg_ts_section_type_get_type
+gst_mpegts_pmt_get_type
+gst_mpegts_pmt_stream_get_type
+gst_mpegts_section_get_type
+gst_mpeg_ts_stream_type_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gst-atsc-section</FILE>
+GstMpegTsSectionATSCTableID
+<SUBSECTION Standard>
+GST_TYPE_MPEG_TS_SECTION_ATSC_TABLE_ID
+gst_mpeg_ts_section_atsc_table_id_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gst-dvb-section</FILE>
+GstMpegTsSectionDVBTableID
+<SUBSECTION NIT>
+GstMpegTsNIT
+GstMpegTsNITStream
+gst_mpegts_section_get_nit
 <SUBSECTION BAT>
 GstMpegTsBAT
 GstMpegTsBATStream
-<SUBSECTION CAT>
+<SUBSECTION SDT>
-gst_mpegts_section_get_cat
+GstMpegTsSDT
+GstMpegTsSDTService
+gst_mpegts_section_get_sdt
 <SUBSECTION EIT>
 GstMpegTsEIT
 GstMpegTsEITEvent
 GstMpegTsRunningStatus
 gst_mpegts_section_get_eit
-<SUBSECTION NIT>
+<SUBSECTION TDT>
-GstMpegTsNIT
-GstMpegTsNITStream
-gst_mpegts_section_get_nit
-<SUBSECTION SDT>
-GstMpegTsSDT
-GstMpegTsSDTService
-gst_mpegts_section_get_sdt
-GstMpegTsTOT
 gst_mpegts_section_get_tdt
+<SUBSECTION TOT>
+GstMpegTsTOT
 gst_mpegts_section_get_tot
-gst_mpegts_section_get_tsdt
 <SUBSECTION Standard>
-GST_TYPE_MPEG_TS_SECTION_TABLE_ID
-GST_TYPE_MPEG_TS_SECTION_TYPE
-GST_TYPE_MPEG_TS_SECTION_ATSC_TABLE_ID
-GST_TYPE_MPEG_TS_SECTION_DVB_TABLE_ID
-GST_MPEGTS_SECTION
-GST_TYPE_MPEG_TS_STREAM_TYPE
 GST_TYPE_MPEGTS_BAT
 GST_TYPE_MPEGTS_EIT
 GST_TYPE_MPEGTS_EIT_EVENT
 GST_TYPE_MPEGTS_NIT
 GST_TYPE_MPEGTS_NIT_STREAM
-GST_TYPE_MPEGTS_PMT
-GST_TYPE_MPEGTS_PMT_STREAM
 GST_TYPE_MPEGTS_SDT
 GST_TYPE_MPEGTS_SDT_SERVICE
-GST_TYPE_MPEGTS_SECTION
 GST_TYPE_MPEGTS_TOT
-gst_mpeg_ts_section_table_id_get_type
+GST_TYPE_MPEG_TS_SECTION_DVB_TABLE_ID
-gst_mpeg_ts_section_atsc_table_id_get_type
+GST_TYPE_MPEG_TS_RUNNING_STATUS
+gst_mpeg_ts_running_status_get_type
 gst_mpeg_ts_section_dvb_table_id_get_type
-gst_mpeg_ts_section_type_get_type
 gst_mpegts_bat_get_type
 gst_mpegts_eit_event_get_type
 gst_mpegts_eit_get_type
 gst_mpegts_nit_get_type
 gst_mpegts_nit_stream_get_type
-gst_mpegts_pmt_get_type
-gst_mpegts_pmt_stream_get_type
 gst_mpegts_sdt_get_type
 gst_mpegts_sdt_service_get_type
-gst_mpegts_section_get_type
 gst_mpegts_tot_get_type
-gst_mpeg_ts_stream_type_get_type
 </SECTION>
 
+
 <SECTION>
 <FILE>gstphotography</FILE>
 GST_PHOTOGRAPHY_AUTOFOCUS_DONE

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
  *

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,

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
  *

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
+ * @descriptors: (element-type GstMpegTsDescriptor): the global descriptors
- * @streams: (element-type GstMpegTsNITStream) the streams
+ * @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;

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
  *

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,

gst-libs/gst/mpegts/gstmpegtssection.c

@@ -35,14 +35,32 @@
 #include "mpegts.h"
 #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
  *