codecs: mpeg2decoder: fix documentation

Part-of: <https://gitlab.freedesktop.org/gstreamer/gst-plugins-bad/-/merge_requests/1798>

gst-libs/gst/codecs/gstmpeg2decoder.c

@@ -17,7 +17,6 @@
  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  * Boston, MA 02110-1301, USA.
  */
-
 /**
  * SECTION:gstmpeg2decoder
  * @title: GstMpeg2Decoder

gst-libs/gst/codecs/gstmpeg2decoder.h

@@ -35,7 +35,6 @@ G_BEGIN_DECLS
 #define GST_MPEG2_DECODER_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj),GST_TYPE_MPEG2_DECODER,GstMpeg2DecoderClass))
 #define GST_IS_MPEG2_DECODER(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_MPEG2_DECODER))
 #define GST_IS_MPEG2_DECODER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_MPEG2_DECODER))
-#define GST_MPEG2_DECODER_CAST(obj)       ((GstMpeg2Decoder*)obj)
 
 typedef struct _GstMpeg2Decoder GstMpeg2Decoder;
 typedef struct _GstMpeg2DecoderClass GstMpeg2DecoderClass;
@@ -45,6 +44,8 @@ typedef struct _GstMpeg2DecoderPrivate GstMpeg2DecoderPrivate;
  * GstMpeg2Decoder:
  *
  * The opaque #GstMpeg2Decoder data structure.
+ *
+ * Since: 1.20
  */
 struct _GstMpeg2Decoder
 {
@@ -74,6 +75,8 @@ struct _GstMpeg2DecoderClass
    * @seq_ext: a #GstMpegVideoSequenceExt
    *
    * Notifies subclass of SPS update
+   *
+   * Since: 1.20
    */
   gboolean      (*new_sequence)     (GstMpeg2Decoder * decoder,
                                      const GstMpegVideoSequenceHdr * seq,
@@ -90,6 +93,8 @@ struct _GstMpeg2DecoderClass
    * Optional. Called whenever new #GstMpeg2Picture is created.
    * Subclass can set implementation specific user data
    * on the #GstMpeg2Picture via gst_mpeg2_picture_set_user_data()
+   *
+   * Since: 1.20
    */
   gboolean      (*new_picture)      (GstMpeg2Decoder * decoder,
                                      GstVideoCodecFrame * frame,
@@ -121,6 +126,8 @@ struct _GstMpeg2DecoderClass
    *
    * Optional. Called per one #GstMpeg2Picture to notify subclass to prepare
    * decoding process for the #GstMpeg2Picture
+   *
+   * Since: 1.20
    */
   gboolean      (*start_picture)    (GstMpeg2Decoder * decoder,
                                      GstMpeg2Picture * picture,
@@ -136,6 +143,8 @@ struct _GstMpeg2DecoderClass
    *
    * Provides per slice data with parsed slice header and required raw bitstream
    * for subclass to decode it.
+   *
+   * Since: 1.20
    */
   gboolean      (*decode_slice)     (GstMpeg2Decoder * decoder,
                                      GstMpeg2Picture * picture,
@@ -148,6 +157,8 @@ struct _GstMpeg2DecoderClass
    *
    * Optional. Called per one #GstMpeg2Picture to notify subclass to finish
    * decoding process for the #GstMpeg2Picture
+   *
+   * Since: 1.20
    */
   gboolean      (*end_picture)      (GstMpeg2Decoder * decoder,
                                      GstMpeg2Picture * picture);
@@ -160,6 +171,8 @@ struct _GstMpeg2DecoderClass
    *
    * Called with a #GstMpeg2Picture which is required to be outputted.
    * The #GstVideoCodecFrame must be consumed by subclass.
+   *
+   * Since: 1.20
    */
   GstFlowReturn (*output_picture)   (GstMpeg2Decoder * decoder,
                                      GstVideoCodecFrame * frame,

gst-libs/gst/codecs/gstmpeg2picture.c

@@ -49,6 +49,8 @@ _gst_mpeg2_picture_free (GstMpeg2Picture * picture)
  * Create new #GstMpeg2Picture
  *
  * Returns: a new #GstMpeg2Picture
+ *
+ * Since: 1.20
  */
 GstMpeg2Picture *
 gst_mpeg2_picture_new (void)
@@ -80,6 +82,8 @@ gst_mpeg2_picture_new (void)
  *
  * If a @user_data was previously set, then the previous set @notify will be called
  * before the @user_data is replaced.
+ *
+ * Since: 1.20
  */
 void
 gst_mpeg2_picture_set_user_data (GstMpeg2Picture * picture, gpointer user_data,
@@ -102,6 +106,8 @@ gst_mpeg2_picture_set_user_data (GstMpeg2Picture * picture, gpointer user_data,
  * gst_mpeg2_picture_set_user_data() previously.
  *
  * Returns: (transfer none): The previously set user_data
+ *
+ * Since: 1.20
  */
 gpointer
 gst_mpeg2_picture_get_user_data (GstMpeg2Picture * picture)
@@ -109,9 +115,6 @@ gst_mpeg2_picture_get_user_data (GstMpeg2Picture * picture)
   return picture->user_data;
 }
 
-/*******************
- * GstMpeg2Dpb *
- *******************/
 struct _GstMpeg2Dpb
 {
   GstMpeg2Picture *ref_pic_list[2];
@@ -126,6 +129,8 @@ struct _GstMpeg2Dpb
  * Create new #GstMpeg2Dpb
  *
  * Returns: a new #GstMpeg2Dpb
+ *
+ * Since: 1.20
  */
 GstMpeg2Dpb *
 gst_mpeg2_dpb_new (void)
@@ -138,6 +143,8 @@ gst_mpeg2_dpb_new (void)
  * @dpb: a #GstMpeg2Dpb to free
  *
  * Free the @dpb
+ *
+ * Since: 1.20
  */
 void
 gst_mpeg2_dpb_free (GstMpeg2Dpb * dpb)
@@ -160,6 +167,8 @@ gst_mpeg2_dpb_free (GstMpeg2Dpb * dpb)
  * @dpb: a #GstMpeg2Dpb
  *
  * Clear all stored #GstMpeg2Picture
+ *
+ * Since: 1.20
  */
 void
 gst_mpeg2_dpb_clear (GstMpeg2Dpb * dpb)
@@ -204,6 +213,8 @@ _dpb_add_to_reference (GstMpeg2Dpb * dpb, GstMpeg2Picture * pic)
  * @picture: (transfer full): a #GstMpeg2Picture
  *
  * Store the @picture
+ *
+ * Since: 1.20
  */
 void
 gst_mpeg2_dpb_add (GstMpeg2Dpb * dpb, GstMpeg2Picture * picture)
@@ -220,6 +231,16 @@ gst_mpeg2_dpb_add (GstMpeg2Dpb * dpb, GstMpeg2Picture * picture)
   }
 }
 
+/**
+ * gst_mpeg2_dpb_need_bump:
+ * @dpb: a #GstMpeg2Dpb
+ *
+ * Checks if @dbp has a new picture.
+ *
+ * Returns: #TRUE if @dpb needs to be bumped; otherwise, #FALSE
+ *
+ * Since: 1.20
+ */
 gboolean
 gst_mpeg2_dpb_need_bump (GstMpeg2Dpb * dpb)
 {
@@ -280,6 +301,19 @@ gst_mpeg2_dpb_bump (GstMpeg2Dpb * dpb)
   return pic;
 }
 
+/**
+ * gst_mpeg2_dpb_get_neighbours:
+ * @dpb: a #GstMpeg2Dpb
+ * @picture: current #GstMpeg2Picture
+ * @prev_picture_ptr: (transfer none) (out) (nullable): previuous
+ *     #GstMpeg2Picture in @dpb
+ * @next_picture_ptr: (transfer none) (out) (nullable): next
+ *     #GstMpeg2Picture in @dpb
+ *
+ * Gets the neighbours #GstMpeg2Picture of @picture in @dpb.
+ *
+ * Since: 1.20
+ */
 void
 gst_mpeg2_dpb_get_neighbours (GstMpeg2Dpb * dpb,
     GstMpeg2Picture * picture, GstMpeg2Picture ** prev_picture_ptr,

gst-libs/gst/codecs/gstmpeg2picture.h

@@ -26,17 +26,37 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GST_TYPE_MPEG2_PICTURE:
+ *
+ * Since: 1.20
+ */
 #define GST_TYPE_MPEG2_PICTURE      (gst_mpeg2_picture_get_type())
+/**
+ * GST_IS_MPEG2_PICTURE:
+ *
+ * Since: 1.20
+ */
 #define GST_IS_MPEG2_PICTURE(obj)   (GST_IS_MINI_OBJECT_TYPE(obj, GST_TYPE_MPEG2_PICTURE))
+/**
+ * GST_MPEG2_PICTURE:
+ *
+ * Since: 1.20
+ */
 #define GST_MPEG2_PICTURE(obj)      ((GstMpeg2Picture *)obj)
-#define GST_MPEG2_PICTURE_CAST(obj) (GST_MPEG2_PICTURE(obj))
 
 typedef struct _GstMpeg2Slice GstMpeg2Slice;
+typedef struct _GstMpeg2Picture GstMpeg2Picture;
 
+/**
+ * GstMpeg2Slice:
+ *
+ * Since: 1.20
+ */
 struct _GstMpeg2Slice
 {
-  /* The parameter set */
+  /*< private >*/
-  GstMpegVideoQuantMatrixExt *quant_matrix;
+  GstMpegVideoQuantMatrixExt *quant_matrix;   /* The parameter set */
   GstMpegVideoPictureHdr *pic_hdr;
   GstMpegVideoPictureExt *pic_ext;
 
@@ -46,8 +66,11 @@ struct _GstMpeg2Slice
   GstMpegVideoPacket packet;
 };
 
-typedef struct _GstMpeg2Picture GstMpeg2Picture;
+/**
-
+ * GstMpeg2Picture:
+ *
+ * Since: 1.20
+ */
 struct _GstMpeg2Picture
 {
   /*< private >*/
@@ -68,6 +91,14 @@ struct _GstMpeg2Picture
   GDestroyNotify notify;
 };
 
+/**
+ * GST_MPEG2_PICTURE_IS_REF:
+ * @picture: a #GstMpeg2Picture
+ *
+ * Check whether @picture's type is I or P
+ *
+ * Since: 1.20
+ */
 #define GST_MPEG2_PICTURE_IS_REF(picture) \
     (((GstMpeg2Picture *) picture)->type == GST_MPEG_VIDEO_PICTURE_TYPE_I || \
      ((GstMpeg2Picture *) picture)->type == GST_MPEG_VIDEO_PICTURE_TYPE_P)
@@ -115,6 +146,12 @@ void gst_mpeg2_picture_set_user_data (GstMpeg2Picture * picture,
 GST_CODECS_API
 gpointer gst_mpeg2_picture_get_user_data (GstMpeg2Picture * picture);
 
+
+/**
+ * GstMpeg2Dpb:
+ *
+ * Since: 1.20
+ */
 typedef struct _GstMpeg2Dpb GstMpeg2Dpb;
 
 GST_CODECS_API