codecparsers: h264parse: improve documentation commentary

https://bugzilla.gnome.org/show_bug.cgi?id=775306

1 files changed, 31 insertions, 26 deletions

diff --git a/gst-libs/gst/codecparsers/gsth264parser.c b/gst-libs/gst/codecparsers/gsth264parser.c
index bc844165c..f3485ae33 100644
--- a/gst-libs/gst/codecparsers/gsth264parser.c
+++ b/gst-libs/gst/codecparsers/gsth264parser.c
@@ -32,19 +32,20 @@
  * @short_description: Convenience library for h264 video
  * bitstream parsing.
  *
- * It offers you bitstream parsing in AVC mode or not. To identify Nals in a bitstream and
- * parse its headers, you should call:
+ * It offers bitstream parsing in both AVC (length-prefixed) and Annex B
+ * (0x000001 start code prefix) format. To identify a NAL unit in a bitstream
+ * and parse its headers, first call:
  * <itemizedlist>
  *   <listitem>
- *      #gst_h264_parser_identify_nalu to identify the following nalu in not AVC bitstreams
+ *      #gst_h264_parser_identify_nalu to identify a NAL unit in an Annex B type bitstream
  *   </listitem>
  *   <listitem>
- *      #gst_h264_parser_identify_nalu_avc to identify the nalu in AVC bitstreams
+ *      #gst_h264_parser_identify_nalu_avc to identify a NAL unit in an AVC type bitstream
  *   </listitem>
  * </itemizedlist>
  *
- * Then, depending on the #GstH264NalUnitType of the newly parsed #GstH264NalUnit, you should
- * call the differents functions to parse the structure:
+ * The following functions are then available for parsing the structure of the
+ * #GstH264NalUnit, depending on the #GstH264NalUnitType:
  * <itemizedlist>
  *   <listitem>
  *      From #GST_H264_NAL_SLICE to #GST_H264_NAL_SLICE_IDR: #gst_h264_parser_parse_slice_hdr
@@ -63,12 +64,14 @@
  *   </listitem>
  * </itemizedlist>
  *
- * Note: You should always call gst_h264_parser_parse_nal if you don't actually need
- * #GstH264NalUnitType to be parsed for your personnal use, in order to guarantee that the
- * #GstH264NalParser is always up to date.
+ * One of these functions *must* be called on every NAL unit in the bitstream,
+ * in order to keep the internal structures of the #GstH264NalParser up to
+ * date. It is legal to call #gst_h264_parser_parse_nal on NAL units of any
+ * type, if no special parsing of the current NAL unit is required by the
+ * application.
  *
  * For more details about the structures, look at the ITU-T H.264 and ISO/IEC 14496-10 – MPEG-4
- * Part 10 specifications, you can download them from:
+ * Part 10 specifications, available at:
  *
  * <itemizedlist>
  *   <listitem>
@@ -1333,12 +1336,13 @@ gst_h264_parser_identify_nalu_unchecked (GstH264NalParser * nalparser,
 /**
  * gst_h264_parser_identify_nalu:
  * @nalparser: a #GstH264NalParser
- * @data: The data to parse
- * @offset: the offset from which to parse @data
+ * @data: The data to parse, containing an Annex B coded NAL unit
+ * @offset: the offset in @data from which to parse the NAL unit
  * @size: the size of @data
- * @nalu: The #GstH264NalUnit where to store parsed nal headers
+ * @nalu: The #GstH264NalUnit to store the identified NAL unit in
  *
- * Parses @data and fills @nalu from the next nalu data from @data
+ * Parses the headers of an Annex B coded NAL unit from @data and puts the
+ * result into @nalu.
  *
  * Returns: a #GstH264ParserResult
  */
@@ -1383,13 +1387,14 @@ beach:
 /**
  * gst_h264_parser_identify_nalu_avc:
  * @nalparser: a #GstH264NalParser
- * @data: The data to parse, must be the beging of the Nal unit
- * @offset: the offset from which to parse @data
+ * @data: The data to parse, containing an AVC coded NAL unit
+ * @offset: the offset in @data from which to parse the NAL unit
  * @size: the size of @data
  * @nal_length_size: the size in bytes of the AVC nal length prefix.
- * @nalu: The #GstH264NalUnit where to store parsed nal headers
+ * @nalu: The #GstH264NalUnit to store the identified NAL unit in
  *
- * Parses @data and sets @nalu.
+ * Parses the headers of an AVC coded NAL unit from @data and puts the result
+ * into @nalu.
  *
  * Returns: a #GstH264ParserResult
  */
@@ -1470,7 +1475,7 @@ gst_h264_parser_parse_nal (GstH264NalParser * nalparser, GstH264NalUnit * nalu)
  * @sps: The #GstH264SPS to fill.
  * @parse_vui_params: Whether to parse the vui_params or not
  *
- * Parses @data, and fills the @sps structure.
+ * Parses @nalu containing a Sequence Parameter Set, and fills @sps.
  *
  * Returns: a #GstH264ParserResult
  */
@@ -2009,11 +2014,10 @@ error:
  * @nalu: The #GST_H264_NAL_PPS #GstH264NalUnit to parse
  * @pps: The #GstH264PPS to fill.
  *
- * Parses @data, and fills the @pps structure.
+ * Parses @nalu containing a Picture Parameter Set, and fills @pps.
  *
- * The resulting @pps data structure shall be deallocated with the
- * gst_h264_pps_clear() function when it is no longer needed, or prior
- * to parsing a new PPS NAL unit.
+ * The resulting @pps data structure must be deallocated by the caller using
+ * gst_h264_pps_clear().
  *
  * Returns: a #GstH264ParserResult
  */
@@ -2054,12 +2058,12 @@ gst_h264_pps_clear (GstH264PPS * pps)
 /**
  * gst_h264_parser_parse_slice_hdr:
  * @nalparser: a #GstH264NalParser
- * @nalu: The #GST_H264_NAL_SLICE #GstH264NalUnit to parse
+ * @nalu: The #GST_H264_NAL_SLICE to #GST_H264_NAL_SLICE_IDR #GstH264NalUnit to parse
  * @slice: The #GstH264SliceHdr to fill.
  * @parse_pred_weight_table: Whether to parse the pred_weight_table or not
  * @parse_dec_ref_pic_marking: Whether to parse the dec_ref_pic_marking or not
  *
- * Parses @data, and fills the @slice structure.
+ * Parses @nalu containing a coded slice, and fills @slice.
  *
  * Returns: a #GstH264ParserResult
  */
@@ -2286,7 +2290,8 @@ gst_h264_sps_clear (GstH264SPS * sps)
  * @nalu: The #GST_H264_NAL_SEI #GstH264NalUnit to parse
  * @messages: The GArray of #GstH264SEIMessage to fill. The caller must free it when done.
  *
- * Parses @data, create and fills the @messages array.
+ * Parses @nalu containing one or more Supplementary Enhancement Information messages,
+ * and allocates and fills the @messages array.
  *
  * Returns: a #GstH264ParserResult
  */