libdvbv5: add documentation for ATSC EIT.

ATSC EIT is different than the DVB EIT table. Document it, and
be sure that the DVB EIT table will be better described.

Signed-off-by: Mauro Carvalho Chehab <m.chehab@samsung.com>

4 files changed, 139 insertions, 14 deletions

diff --git a/doxygen_libdvbv5.cfg b/doxygen_libdvbv5.cfg
index c717625e..b9481826 100644
--- a/doxygen_libdvbv5.cfg
+++ b/doxygen_libdvbv5.cfg
@@ -753,6 +753,7 @@ INPUT                  = $(SRCDIR)/doc/libdvbv5-index.doc \
 			 $(SRCDIR)/lib/include/libdvbv5/dvb-v5-std.h \
 			 $(SRCDIR)/lib/include/libdvbv5/descriptors.h \
 			 $(SRCDIR)/lib/include/libdvbv5/header.h \
+			 $(SRCDIR)/lib/include/libdvbv5/atsc_eit.h \
 			 $(SRCDIR)/lib/include/libdvbv5/eit.h \
 			 $(SRCDIR)/lib/include/libdvbv5/nit.h \
 			 $(SRCDIR)/lib/include/libdvbv5/pat.h \
diff --git a/lib/include/libdvbv5/atsc_eit.h b/lib/include/libdvbv5/atsc_eit.h
index 5116a3d0..7d0b7289 100644
--- a/lib/include/libdvbv5/atsc_eit.h
+++ b/lib/include/libdvbv5/atsc_eit.h
@@ -18,6 +18,24 @@
  *
  */
 
+/**
+ * @file atsc_eit.h
+ * @brief Provides the table parser for the ATSC EIT (Event Information Table)
+ * @copyright GNU General Public License version 2 (GPLv2)
+ * @author Mauro Carvalho Chehab
+ * @author Andre Roth
+ *
+ * @par Relevant specs
+ * The table described herein is defined at:
+ * - ATSC A/65:2009
+ *
+ * @see
+ * http://www.etherguidesystems.com/help/sdos/atsc/syntax/tablesections/eitks.aspx
+ *
+ * @par Bug Report
+ * Please submit bug reports and patches to linux-media@vger.kernel.org
+ */
+
 #ifndef _ATSC_EIT_H
 #define _ATSC_EIT_H
 
@@ -27,8 +45,39 @@
 
 #include <libdvbv5/atsc_header.h>
 
+/**
+ * @def ATSC_TABLE_EIT
+ *	@brief ATSC EIT table ID for the actual TS
+ */
 #define ATSC_TABLE_EIT        0xCB
 
+/**
+ * @struct atsc_table_eit_event
+ * @brief ATSC EIT event table
+ *
+ * @param event_id	an uniquelly (inside a service ID) event ID
+ * @param one		Always '1'
+ * @param title_length	title length. Zero means no title
+ * @param duration	duration in seconds
+ * @param etm		Extended Text Message location
+ * @param one2		Always '1'
+ * @param descriptor	pointer to struct descriptor
+ * @param next		pointer to struct next
+ * @param source_id	source id (obtained from ATSC header)
+ * @param start		event start (in struct tm format)
+ *
+ * This structure is used to store the original ATSC EIT event table,
+ * converting the integer fields to the CPU endianness, and converting the
+ * timestamps to a way that it is better handled on Linux.
+ *
+ * The undocumented parameters are used only internally by the API and/or
+ * are fields that are reserved. They shouldn't be used, as they may change
+ * on future API releases.
+ *
+ * Everything after atsc_table_eit_event::descriptor (including it) won't
+ * be bit-mapped to the data parsed from the MPEG TS. So, metadata are added
+ * there.
+ */
 struct atsc_table_eit_event {
 	union {
 		uint16_t bitfield;
@@ -54,6 +103,20 @@ struct atsc_table_eit_event {
 	uint16_t source_id;
 } __attribute__((packed));
 
+/**
+ * @union atsc_table_eit_desc_length
+ * @brief ATSC EIT descriptor length
+ *
+ * @param desc_length	descriptor length
+ *
+ * This structure is used to store the original ATSC EIT event table,
+ * converting the integer fields to the CPU endianness, and converting the
+ * timestamps to a way that it is better handled on Linux.
+ *
+ * The undocumented parameters are used only internally by the API and/or
+ * are fields that are reserved. They shouldn't be used, as they may change
+ * on future API releases.
+ */
 union atsc_table_eit_desc_length {
 	uint16_t bitfield;
 	struct {
@@ -62,12 +125,32 @@ union atsc_table_eit_desc_length {
 	} __attribute__((packed));
 } __attribute__((packed));
 
+/**
+ * @struct atsc_table_eit
+ * @brief ATSC EIT table
+ *
+ * @param events	events
+ * @param event	pointer to struct event
+ *
+ * This structure is used to store the original ATSC EIT table,
+ * converting the integer fields to the CPU endianness.
+ *
+ * Everything after atsc_table_eit::event (including it) won't
+ * be bit-mapped to the data parsed from the MPEG TS. So, metadata are added
+ * there.
+ */
 struct atsc_table_eit {
 	ATSC_HEADER();
 	uint8_t events;
 	struct atsc_table_eit_event *event;
 } __attribute__((packed));
 
+/**
+ * @brief Macro used to find event on an ATSC EIT table
+ *
+ * @param _event	event to seek
+ * @param _eit		pointer to struct atsc_table_eit_event
+ */
 #define atsc_eit_event_foreach(_event, _eit) \
 	for( struct atsc_table_eit_event *_event = _eit->event; _event; _event = _event->next ) \
 
@@ -77,9 +160,47 @@ struct dvb_v5_fe_parms;
 extern "C" {
 #endif
 
-ssize_t atsc_table_eit_init (struct dvb_v5_fe_parms *parms, const uint8_t *buf, ssize_t buflen, struct atsc_table_eit **table);
-void atsc_table_eit_free(struct atsc_table_eit *eit);
-void atsc_table_eit_print(struct dvb_v5_fe_parms *parms, struct atsc_table_eit *eit);
+/**
+ * @brief Initializes and parses ATSC EIT table
+ *
+ * @param parms	struct dvb_v5_fe_parms pointer to the opened device
+ * @param buf buffer containing the EIT raw data
+ * @param buflen length of the buffer
+ * @param table pointer to struct atsc_table_eit to be allocated and filled
+ *
+ * This function allocates an ATSC EIT table and fills the fields inside
+ * the struct. It also makes sure that all fields will follow the CPU
+ * endianness. Due to that, the content of the buffer may change.
+ *
+ * @return On success, it returns the size of the allocated struct.
+ *	   A negative value indicates an error.
+ */
+ssize_t atsc_table_eit_init(struct dvb_v5_fe_parms *parms, const uint8_t *buf,
+			    ssize_t buflen, struct atsc_table_eit **table);
+
+/**
+ * @brief Frees all data allocated by the ATSC EIT table parser
+ *
+ * @param table pointer to struct atsc_table_eit to be freed
+ */
+void atsc_table_eit_free(struct atsc_table_eit *table);
+
+/**
+ * @brief Prints the content of the ATSC EIT table
+ *
+ * @param parms	struct dvb_v5_fe_parms pointer to the opened device
+ * @param table pointe to struct atsc_table_eit
+ */
+void atsc_table_eit_print(struct dvb_v5_fe_parms *parms,
+			  struct atsc_table_eit *table);
+
+/**
+ * @brief Converts an ATSC EIT formatted timestamp into struct tm
+ *
+ * @param start_time	event on ATSC EIT time format
+ * @param tm		pointer to struct tm where the converted timestamp will
+ *			be stored.
+ */
 void atsc_time(const uint32_t start_time, struct tm *tm);
 
 #ifdef __cplusplus
diff --git a/lib/include/libdvbv5/eit.h b/lib/include/libdvbv5/eit.h
index 8f824e73..16e978ea 100644
--- a/lib/include/libdvbv5/eit.h
+++ b/lib/include/libdvbv5/eit.h
@@ -21,7 +21,7 @@
 
 /**
  * @file eit.h
- * @brief Provides the table parser for EIT (Event Information Table)
+ * @brief Provides the table parser for the DVB EIT (Event Information Table)
  * @copyright GNU General Public License version 2 (GPLv2)
  * @author Mauro Carvalho Chehab
  * @author Andre Roth
@@ -30,6 +30,9 @@
  * The table described herein is defined at:
  * - ETSI EN 300 468
  *
+ * @see
+ * http://www.etherguidesystems.com/Help/SDOs/dvb/syntax/tablesections/EIT.aspx
+ *
  * @par Bug Report
  * Please submit bug reports and patches to linux-media@vger.kernel.org
  */
@@ -45,15 +48,15 @@
 
 /**
  * @def DVB_TABLE_EIT
- *	@brief EIT table ID for the actual TS
+ *	@brief DVB EIT table ID for the actual TS
  * @def DVB_TABLE_EIT_OTHER
- *	@brief EIT table ID for other TS
+ *	@brief DVB EIT table ID for other TS
  * @def DVB_TABLE_EIT_PID
- *	@brief EIT Program ID
+ *	@brief DVB EIT Program ID
  * @def DVB_TABLE_EIT_SCHEDULE
- *	@brief Start table ID for the EIT schedule data on the actual TS
+ *	@brief Start table ID for the DVB EIT schedule data on the actual TS
  * @def DVB_TABLE_EIT_SCHEDULE_OTHER
- *	@brief Start table ID for the EIT schedule data on other TS
+ *	@brief Start table ID for the DVB EIT schedule data on other TS
  */
 #define DVB_TABLE_EIT        0x4E
 #define DVB_TABLE_EIT_OTHER  0x4F
@@ -140,7 +143,7 @@ struct dvb_table_eit {
 } __attribute__((packed));
 
 /**
- * @brief Macro used to find event on a EIT table
+ * @brief Macro used to find event on a DVB EIT table
  *
  * @param _event	event to seek
  * @param _eit		pointer to struct dvb_table_eit_event
@@ -163,7 +166,7 @@ extern "C" {
  * @param parms	struct dvb_v5_fe_parms pointer to the opened device
  * @param buf buffer containing the EIT raw data
  * @param buflen length of the buffer
- * @param table pointer to struct dvb_table_pat to be allocated and filled
+ * @param table pointer to struct dvb_table_eit to be allocated and filled
  *
  * This function allocates an EIT table and fills the fields inside
  * the struct. It also makes sure that all fields will follow the CPU
@@ -176,14 +179,14 @@ ssize_t dvb_table_eit_init (struct dvb_v5_fe_parms *parms, const uint8_t *buf,
 			    ssize_t buflen, struct dvb_table_eit **table);
 
 /**
- * @brief Frees all data allocated by the EIT table parser
+ * @brief Frees all data allocated by the DVB EIT table parser
  *
  * @param table pointer to struct dvb_table_eit to be freed
  */
 void dvb_table_eit_free(struct dvb_table_eit *table);
 
 /**
- * @brief Prints the content of the EIT table
+ * @brief Prints the content of the DVB EIT table
  *
  * @param parms	struct dvb_v5_fe_parms pointer to the opened device
  * @param table pointe to struct dvb_table_eit
diff --git a/lib/include/libdvbv5/vct.h b/lib/include/libdvbv5/vct.h
index 9b69aa0e..4b9e03b6 100644
--- a/lib/include/libdvbv5/vct.h
+++ b/lib/include/libdvbv5/vct.h
@@ -28,7 +28,7 @@
  *
  * @par Relevant specs
  * The table described herein is defined at:
- * - ATSC A/65:2009 spec
+ * - ATSC A/65:2009
  *
  * @see http://www.etherguidesystems.com/help/sdos/atsc/syntax/tablesections/TVCT.aspx
  * @see http://www.etherguidesystems.com/help/sdos/atsc/syntax/tablesections/CVCT.aspx