audiodecoder: add some documentation

gst-libs/gst/audio/gstaudiodecoder.c

@@ -715,6 +715,27 @@ again:
   return ret;
 }
 
+/**
+ * gst_audio_decoder_finish_frame:
+ * @dec: a #GstAudioDecoder
+ * @buf: decoded data
+ * @frames: number of decoded frames represented by decoded data
+ *
+ * Collects decoded data and pushes it downstream.
+ *
+ * @buf may be NULL in which case the indicated number of frames
+ * are discarded and considered to have produced no output
+ * (e.g. lead-in or setup frames).
+ * Otherwise, source pad caps must be set when it is called with valid
+ * data in @buf.
+ *
+ * Note that a frame received in gst_audio_decoder_handle_frame() may be
+ * invalidated by a call to this function.
+ *
+ * Returns: a #GstFlowReturn that should be escalated to caller (of caller)
+ *
+ * Since: 0.10.36
+ */
 GstFlowReturn
 gst_audio_decoder_finish_frame (GstAudioDecoder * dec, GstBuffer * buf,
     gint frames)

gst-libs/gst/audio/gstaudiodecoder.h

@@ -173,7 +173,9 @@ struct _GstAudioDecoder
  *                  frames as defined by audio format.
  * @handle_frame:   Provides input data (or NULL to clear any remaining data)
  *                  to subclass.  Input data ref management is performed by
- *                  base class, subclass should not care or intervene.
+ *                  base class, subclass should not care or intervene,
+ *                  and input data is only valid until next call to base class,
+ *                  most notably a call to gst_audio_decoder_finish_frame().
  * @flush:          Optional.
  *                  Instructs subclass to clear any codec caches and discard
  *                  any pending samples and not yet returned encoded data.