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

diff --git a/docs/libs/gst-plugins-bad-libs-docs.sgml b/docs/libs/gst-plugins-bad-libs-docs.sgml
index 3a8d994..66c4dee 100644 (file)
--- a/docs/libs/gst-plugins-bad-libs-docs.sgml
+++ b/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">

diff --git a/docs/libs/gst-plugins-bad-libs-sections.txt b/docs/libs/gst-plugins-bad-libs-sections.txt
index 91ab28d..5c5d8d4 100644 (file)
--- a/docs/libs/gst-plugins-bad-libs-sections.txt
+++ b/docs/libs/gst-plugins-bad-libs-sections.txt
@@ -167,40 +167,19 @@ gst_mpeg4_parse_video_packet_header
 </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 component>
-GstMpegTsComponentDescriptor
-gst_mpegts_descriptor_parse_dvb_component
-<SUBSECTION extended_event>
-GstMpegTsExtendedEventItem
-GstMpegTsExtendedEventDescriptor
-gst_mpegts_descriptor_parse_dvb_extended_event
-<SUBSECTION satellite_delivery>
-GstMpegTsSatelliteDeliverySystemDescriptor
-GstMpegTsDVBCodeRate
-GstMpegTsModulationType
-GstMpegTsSatellitePolarizationType
-GstMpegTsSatelliteRolloff
-gst_mpegts_descriptor_parse_satellite_delivery_system
-<SUBSECTION cable_delivery>
-GstMpegTsCableDeliverySystemDescriptor
-GstMpegTsCableOuterFECScheme
-gst_mpegts_descriptor_parse_cable_delivery_system
-<SUBSECTION short_event>
-gst_mpegts_descriptor_parse_dvb_short_event
-gst_mpegts_descriptor_parse_dvb_network_name
-<SUBSECTION service>
-GstMpegTsDVBServiceType
-gst_mpegts_descriptor_parse_dvb_service
 <SUBSECTION iso639>
 GstMpegTsISO639LanguageDescriptor
 GstMpegTsIso639AudioType
@@ -220,7 +199,6 @@ 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_RUNNING_STATUS
 GST_TYPE_MPEG_TS_ATSC_DESCRIPTOR_TYPE
 GST_TYPE_MPEG_TS_DVB_DESCRIPTOR_TYPE
 GST_TYPE_MPEG_TS_ISDB_DESCRIPTOR_TYPE
@@ -237,18 +215,63 @@ 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>
+<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
+<SUBSECTION extended_event>
+GstMpegTsExtendedEventItem
+GstMpegTsExtendedEventDescriptor
+gst_mpegts_descriptor_parse_dvb_extended_event
+<SUBSECTION satellite_delivery>
+GstMpegTsSatelliteDeliverySystemDescriptor
+GstMpegTsDVBCodeRate
+GstMpegTsModulationType
+GstMpegTsSatellitePolarizationType
+GstMpegTsSatelliteRolloff
+gst_mpegts_descriptor_parse_satellite_delivery_system
+<SUBSECTION cable_delivery>
+GstMpegTsCableDeliverySystemDescriptor
+GstMpegTsCableOuterFECScheme
+gst_mpegts_descriptor_parse_cable_delivery_system
+<SUBSECTION short_event>
+gst_mpegts_descriptor_parse_dvb_short_event
+gst_mpegts_descriptor_parse_dvb_network_name
+<SUBSECTION service>
+GstMpegTsDVBServiceType
+gst_mpegts_descriptor_parse_dvb_service
+<SUBSECTION Standard>
+GST_TYPE_MPEG_TSDVB_CODE_RATE
+gst_mpeg_tsdvb_code_rate_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gst-isdb-descriptor</FILE>
+GstMpegTsISDBDescriptorType
+<SUBSECTION Standard>
+GST_TYPE_MPEG_TS_ISDB_DESCRIPTOR_TYPE
+gst_mpeg_ts_isdb_descriptor_type_get_type
+</SECTION>
+
+<SECTION>
 <FILE>gstmpegtssection</FILE>
 <SUBSECTION section>
 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 BAT>
-GstMpegTsBAT
-GstMpegTsBATStream
+<SUBSECTION TSDT>
+gst_mpegts_section_get_tsdt
 <SUBSECTION CAT>
 gst_mpegts_section_get_cat
-<SUBSECTION EIT>
-GstMpegTsEIT
-GstMpegTsEITEvent
-GstMpegTsRunningStatus
-gst_mpegts_section_get_eit
+<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 SDT>
 GstMpegTsSDT
 GstMpegTsSDTService
 gst_mpegts_section_get_sdt
-GstMpegTsTOT
+<SUBSECTION EIT>
+GstMpegTsEIT
+GstMpegTsEITEvent
+GstMpegTsRunningStatus
+gst_mpegts_section_get_eit
+<SUBSECTION TDT>
 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_mpeg_ts_section_atsc_table_id_get_type
+GST_TYPE_MPEG_TS_SECTION_DVB_TABLE_ID
+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

diff --git a/gst-libs/gst/mpegts/gst-dvb-descriptor.c b/gst-libs/gst/mpegts/gst-dvb-descriptor.c
index 00cc92d..17b2845 100644 (file)
--- 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 0af814c..9fdde7c 100644 (file)
--- 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 fe3d09f..9e3cea0 100644 (file)
--- 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 465d614..af85631 100644 (file)
--- 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 9850b30..f890b0a 100644 (file)
--- 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 233f3aa..2ac27b1 100644 (file)
--- 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 339444b..1cded52 100644 (file)
--- 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
  *