Documentation function gst_video_encoder_finish_frame and structure GstVideoCodecFrame not enough?

[Martin Maurer]

Hello,

when looking at the documentation of gst_video_encoder_finish_frame

( 
https://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-libs/html/gst-plugins-base-libs-GstVideoEncoder.html#gst-video-encoder-finish-frame 
)

I am missing which information must be filled in which field, what it 
does with this information and which are not needed at all (ignored).
E.g. PTS/DTS/Duration can be filled into frame (GstVideoCodecFrame has 
PTS/DTS/Duration fields),
but also in fields of GstBuffer included in this frame. Seems to be the 
case, that they must be filled into frame and are ignored in buffer.
According to source code there is e.g. a check/handling for 
presentation_frame_number == 0, which seems to be a special case.
Could there be added some description inside the documentation of the 
function what it does?

The function does a lot on timestamps, but what exactly? Why so lot 
cases and very less documentation for the caller?

When looking into documentation of GstVideoCodecFrame

( 
https://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-libs/html/gst-plugins-base-libs-gstvideoutils.html#GstVideoCodecFrame 
)

there is no description of /|decode_frame_number nor of 
|//|/|presentation_frame_number.

What does "ED" and "D" mean in comments after structure elements? 
Something like "encoded data" and "data"?
What does it mean? Do you have an example?

Many thanks!

Best regards,

Martin

|/|/