[NUT-devel] [nut]: r261 - trunk/libnut/libnut.h

[ods15]

Author: ods15
Date: Tue Nov 21 18:52:14 2006
New Revision: 261

Modified:
   trunk/libnut/libnut.h

Log:
better documentation of nut_info_field_t


Modified: trunk/libnut/libnut.h
==============================================================================
--- trunk/libnut/libnut.h	(original)
+++ trunk/libnut/libnut.h	Tue Nov 21 18:52:14 2006
@@ -75,12 +75,12 @@
 
 /// Single info field struct
 typedef struct {
-	char type[7];      ///< NULL-terminated string. "v"=integer value, "s"=signed integer value, "r"=fraction rational, "t"=timestamp
+	char type[7];      ///< NULL-terminated string
 	char name[65];     ///< NULL-terminated string. Name of info field
-	int64_t val;       ///< used in types "v", "s", "r", "t", and is the length of #data in bytes in other types.
-	int den;           ///< used in type=="r", #val is the numerator.
-	nut_timebase_t tb; ///< used in type=="t". This is the timebase, and #val is the timestamp in this timebase.
-	uint8_t * data;    ///< Value of binary data. \b Must be NULL if carries no data. \note This data is not NULL terminated!
+	int64_t val;       ///< Meaning of value defined by #type
+	int den;           ///< Used if #type is "r". #val is the numerator
+	nut_timebase_t tb; ///< Used if #type is "t"
+	uint8_t * data;    ///< Used if #type is non-numeric
 } nut_info_field_t;
 
 /// Single info packet struct
@@ -268,6 +268,59 @@
  * The example shown is if fps is 23.976 (24000/1001). Timebase is the opposite of fps.
  */
 
+/*! \struct nut_info_field_t
+ * \par Example:
+ * \code
+ * char * text = "The Foobar Adventure";
+ * nut_info_field_t title = {
+ * 	.type = "UTF-8",
+ * 	.name = "Title",
+ * 	.val = strlen(text),
+ * 	.data = text,
+ * };
+ *
+ * nut_info_field_t rational = {
+ * 	.type = "r",
+ * 	.name = "X-Value close to Pi",
+ * 	.val = 355,
+ * 	.den = 113,
+ * };
+ * \endcode
+ */
+
+/*! \var char nut_info_field_t::type[7]
+ * Type of field value
+ * - "v" - Integer value
+ * - "s" - Signed integer value
+ * - "r" - Fraction rational
+ * - "t" - Timestamp
+ * - "UTF-8" - UTF-8 coded string
+ * - Other - Binary data
+ */
+
+/*! \var int64_t nut_info_field_t::val
+ * - "v" - Integer value
+ * - "s" - Integer value
+ * - "r" - Numerator of fraction
+ * - "t" - Integer timestamp in timebase #tb
+ * - Other: Length of #data in bytes
+ *
+ * In the case of UTF-8 string, length of #data \b must \b not contain the
+ * terminating NUL (U+0000).
+ */
+
+/*! \var nut_timebase_t nut_info_field_t::tb
+ * In the case of muxer, values of #tb \b must be identical to the
+ * timebase of one of the streams.
+ */
+
+/*! \var uint8_t * nut_info_field_t::data
+ * Even in the case of UTF-8 string, this data is \b not NULL terminated.
+ *
+ * For muxer, this value \b must be NULL if info field carries no binary
+ * data.
+ */
+
 /*!
  * \var int nut_frame_table_input_t::flag
  *