codecparsers: h264: Update the documentation

Fix a few error.
Document missing parts.
Add links to the specifications

1 files changed, 65 insertions, 27 deletions

diff --git a/gst-libs/gst/codecparsers/gsth264parser.c b/gst-libs/gst/codecparsers/gsth264parser.c
index 869aa6122..36f2ee4ad 100644
--- a/gst-libs/gst/codecparsers/gsth264parser.c
+++ b/gst-libs/gst/codecparsers/gsth264parser.c
@@ -32,25 +32,52 @@
  * @short_description: Convenience library for h264 video
  * bitstream parsing.
  *
- * It offers you basic parsing in AVC mode or not. Tp identify Nals in a bitstream and
- * parse its basic headers, you should call:
+ * It offers you bitstream parsing in AVC mode or not. To identify Nals in a bitstream and
+ * parse its headers, you should call:
  * <itemizedlist>
  *   <listitem>
- *      gst_h264_parser_identify_nalu to identify the following nalu in not AVC bitstreams
+ *      #gst_h264_parser_identify_nalu to identify the following nalu in not AVC bitstreams
  *   </listitem>
  *   <listitem>
- *      gst_h264_parser_identify_nalu_avc to identify the following nalu in AVC bitstreams
+ *      #gst_h264_parser_identify_nalu_avc to identify the nalu in AVC bitstreams
  *   </listitem>
  * </itemizedlist>
  *
  * Then, depending on the #GstH264NalUnitType of the newly parsed #GstH264NalUnit, you should
- * call the differents functions to parse the struct.
+ * call the differents functions to parse the structure:
+ * <itemizedlist>
+ *   <listitem>
+ *      From #GST_H264_NAL_SLICE to #GST_H264_NAL_SLICE_IDR: #gst_h264_parser_parse_slice_hdr
+ *   </listitem>
+ *   <listitem>
+ *      #GST_H264_NAL_SEI: #gst_h264_parser_parse_sei
+ *   </listitem>
+ *   <listitem>
+ *      #GST_H264_NAL_SPS: #gst_h264_parser_parse_sps
+ *   </listitem>
+ *   <listitem>
+ *      #GST_H264_NAL_PPS: #gst_h264_parser_parse_pps
+ *   </listitem>
+ *   <listitem>
+ *      Any other: #gst_h264_parser_parse_nal
+ *   </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. This, to guarantee that the
+ * #GstH264NalUnitType to be parsed for your personnal use, in order to guarantee that the
  * #GstH264NalParser is always up to date.
  *
- * For more details about the structures, look at the ISO specifications.
+ * 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:
+ *
+ * <itemizedlist>
+ *   <listitem>
+ *     ITU-T H.264: http://www.itu.int/rec/T-REC-H.264
+ *   </listitem>
+ *   <listitem>
+ *     ISO/IEC 14496-10: http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=56538
+ *   </listitem>
+ * </itemizedlist>
  */
 
 #ifdef HAVE_CONFIG_H
@@ -1090,7 +1117,8 @@ error:
 /**
  * gst_h264_nal_parser_new:
  *
- * Creates a nez #GstH264NalParser
+ * Creates a new #GstH264NalParser. It should be freed with
+ * gst_h264_nal_parser_free after use.
  *
  * Returns: a new #GstH264NalParser
  */
@@ -1110,11 +1138,11 @@ gst_h264_nal_parser_new (void)
  * gst_h264_parser_identify_nalu:
  * @nalparser: a #GstH264NalParser
  * @data: The data to parse
- * @offset: the offset from which to parse  @data
+ * @offset: the offset from which to parse @data
  * @size: the size of @data
  * @nalu: The #GstH264NalUnit where to store parsed nal headers
  *
- * Parses the buffer and set @nalu from the next nalu data from @data
+ * Parses @data and fills @nalu from the next nalu data from @data
  *
  * Returns: a #GstH264ParserResult
  */
@@ -1180,12 +1208,14 @@ gst_h264_parser_identify_nalu (GstH264NalParser * nalparser,
 
 /**
  * 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
  * @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
  *
- * Parses the data and sets @nalu from @data.
+ * Parses @data and sets @nalu.
  *
  * Returns: a #GstH264ParserResult
  */
@@ -1221,6 +1251,17 @@ gst_h264_parser_identify_nalu_avc (GstH264NalParser * nalparser,
   return GST_H264_PARSER_OK;
 }
 
+/**
+ * gst_h264_parser_parse_nal:
+ * @nalparser: a #GstH264NalParser
+ * @nalu: The #GstH264NalUnit to parse
+ *
+ * This function should be called in the case you don't need to
+ * parse a specific structure. It is necessary to do so to make
+ * sure @nalparser is up to date.
+ *
+ * Returns: a #GstH264ParserResult
+ */
 GstH264ParserResult
 gst_h264_parser_parse_nal (GstH264NalParser * nalparser, GstH264NalUnit * nalu)
 {
@@ -1242,10 +1283,10 @@ gst_h264_parser_parse_nal (GstH264NalParser * nalparser, GstH264NalUnit * nalu)
  * gst_h264_parser_parse_sps:
  * @nalparser: a #GstH264NalParser
  * @nalu: The #GST_H264_NAL_SPS #GstH264NalUnit you want to parse
- * @slice: The #GstH264SPS to set.
+ * @slice: The #GstH264SPS to fill.
  * @parse_vui_params: Whether to parse the vui_params or not
  *
- * Parses the @data, and sets the @sps.
+ * Parses @data, and fills the @sps structure.
  *
  * Returns: a #GstH264ParserResult
  */
@@ -1270,10 +1311,10 @@ gst_h264_parser_parse_sps (GstH264NalParser * nalparser, GstH264NalUnit * nalu,
 /**
  * gst_h264_parse_sps:
  * @nalu: The #GST_H264_NAL_SPS #GstH264NalUnit you want to parse
- * @slice: The #GstH264SPS to set.
+ * @sps: The #GstH264SPS to fill.
  * @parse_vui_params: Whether to parse the vui_params or not
  *
- * Parses the @data, and sets the @sps.
+ * Parses @data, and fills the @sps structure.
  *
  * Returns: a #GstH264ParserResult
  */
@@ -1441,12 +1482,10 @@ error:
 /**
  * gst_h264_parse_pps:
  * @nalparser: a #GstH264NalParser
- * @data: the data to parse
- * @size: the size of @data
  * @nalu: The #GST_H264_NAL_PPS #GstH264NalUnit you want to parse
- * @slice: The #GstH264PPS to set.
+ * @pps: The #GstH264PPS to fill.
  *
- * Parses the @data, and sets the @pps.
+ * Parses @data, and fills the @pps structure.
  *
  * Returns: a #GstH264ParserResult
  */
@@ -1572,12 +1611,10 @@ error:
 /**
  * gst_h264_parser_parse_pps:
  * @nalparser: a #GstH264NalParser
- * @data: the data to parse
- * @size: the size of @data
  * @nalu: The #GST_H264_NAL_PPS #GstH264NalUnit you want to parse
- * @slice: The #GstH264PPS to set.
+ * @pps: The #GstH264PPS to fill.
  *
- * Parses the @data, and sets the @pps.
+ * Parses @data, and fills the @pps structure.
  *
  * Returns: a #GstH264ParserResult
  */
@@ -1599,12 +1636,13 @@ gst_h264_parser_parse_pps (GstH264NalParser * nalparser,
 
 /**
  * gst_h264_parser_parse_slice_hdr:
+ * @nalparser: a #GstH264NalParser
  * @nalu: The #GST_H264_NAL_SLICE #GstH264NalUnit you want to parse
- * @slice: The #GstH264SliceHdr to set.
+ * @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 the @data, and sets the @slice.
+ * Parses @data, and fills the @slice structure.
  *
  * Returns: a #GstH264ParserResult
  */
@@ -1777,9 +1815,9 @@ error:
  * gst_h264_parser_parse_sei:
  * @nalparser: a #GstH264NalParser
  * @nalu: The #GST_H264_NAL_SEI #GstH264NalUnit you want to parse
- * @slice: The #GstH264SEIMessage to set.
+ * @sei: The #GstH264SEIMessage to fill.
  *
- * Parses the @data, and sets the @pps.
+ * Parses @data, and fills the @sei structures.
  *
  * Returns: a #GstH264ParserResult
  */