baseparse: Documentation improvements

* Remove references to old functions and methods
* Use proper #ClassName.vmethod() decorator for vmethod

libs/gst/base/gstbaseparse.c

@@ -47,17 +47,17 @@
  *
  * ## Set-up phase
  *
- *  * #GstBaseParse calls @start to inform subclass that data processing is
+ *  * #GstBaseParse calls #GstBaseParseClass.start() to inform subclass
- *    about to start now.
+ *    that data processing is about to start now.
  *
- *  * #GstBaseParse class calls @set_sink_caps to inform the subclass about
+ *  * #GstBaseParse class calls #GstBaseParseClass.set_sink_caps() to
- *    incoming sinkpad caps. Subclass could already set the srcpad caps
+ *    inform the subclass about incoming sinkpad caps. Subclass could
- *    accordingly, but this might be delayed until calling
+ *    already set the srcpad caps accordingly, but this might be delayed
- *    gst_base_parse_finish_frame() with a non-queued frame.
+ *    until calling gst_base_parse_finish_frame() with a non-queued frame.
  *
  *  * At least at this point subclass needs to tell the #GstBaseParse class
- *    how big data chunks it wants to receive (min_frame_size). It can do
+ *    how big data chunks it wants to receive (minimum frame size ). It can
- *    this with gst_base_parse_set_min_frame_size().
+ *    do this with gst_base_parse_set_min_frame_size().
  *
  *  * #GstBaseParse class sets up appropriate data passing mode (pull/push)
  *    and starts to process the data.
@@ -68,24 +68,27 @@
  *    by pulling it from upstream or collecting buffers in an internal
  *    #GstAdapter.
  *
- *  * A buffer of (at least) min_frame_size bytes is passed to subclass with
+ *  * A buffer of (at least) min_frame_size bytes is passed to subclass
- *    @handle_frame. Subclass checks the contents and can optionally
+ *    with #GstBaseParseClass.handle_frame(). Subclass checks the contents
- *    return GST_FLOW_OK along with an amount of data to be skipped to find
+ *    and can optionally return #GST_FLOW_OK along with an amount of data
- *    a valid frame (which will result in a subsequent DISCONT).
+ *    to be skipped to find a valid frame (which will result in a
- *    If, otherwise, the buffer does not hold a complete frame,
+ *    subsequent DISCONT).  If, otherwise, the buffer does not hold a
- *    @handle_frame can merely return and will be called again when additional
+ *    complete frame, #GstBaseParseClass.handle_frame() can merely return
- *    data is available.  In push mode this amounts to an
+ *    and will be called again when additional data is available.  In push
- *    additional input buffer (thus minimal additional latency), in pull mode
+ *    mode this amounts to an additional input buffer (thus minimal
- *    this amounts to some arbitrary reasonable buffer size increase.
+ *    additional latency), in pull mode this amounts to some arbitrary
- *    Of course, gst_base_parse_set_min_frame_size() could also be used if a
+ *    reasonable buffer size increase.
- *    very specific known amount of additional data is required.
+ *
- *    If, however, the buffer holds a complete valid frame, it can pass
+ *    Of course, gst_base_parse_set_min_frame_size() could also be used if
- *    the size of this frame to gst_base_parse_finish_frame().
+ *    a very specific known amount of additional data is required.  If,
- *    If acting as a converter, it can also merely indicate consumed input data
+ *    however, the buffer holds a complete valid frame, it can pass the
- *    while simultaneously providing custom output data.
+ *    size of this frame to gst_base_parse_finish_frame().
- *    Note that baseclass performs some processing (such as tracking
+ *
- *    overall consumed data rate versus duration) for each finished frame,
+ *    If acting as a converter, it can also merely indicate consumed input
- *    but other state is only updated upon each call to @handle_frame
+ *    data while simultaneously providing custom output data.  Note that
+ *    baseclass performs some processing (such as tracking overall consumed
+ *    data rate versus duration) for each finished frame, but other state
+ *    is only updated upon each call to #GstBaseParseClass.handle_frame()
  *    (such as tracking upstream input timestamp).
  *
  *    Subclass is also responsible for setting the buffer metadata
@@ -96,28 +99,30 @@
  *    duration obtained from configuration (see below), and offset
  *    if meaningful (in pull mode).
  *
- *    Note that @check_valid_frame might receive any small
+ *    Note that #GstBaseParseClass.handle_frame() might receive any small
- *    amount of input data when leftover data is being drained (e.g. at EOS).
+ *    amount of input data when leftover data is being drained (e.g. at
+ *    EOS).
  *
- *  * As part of finish frame processing,
+ *  * As part of finish frame processing, just prior to actually pushing
- *    just prior to actually pushing the buffer in question,
+ *    the buffer in question, it is passed to
- *    it is passed to @pre_push_frame which gives subclass yet one
+ *    #GstBaseParseClass.pre_push_frame() which gives subclass yet one last
- *    last chance to examine buffer metadata, or to send some custom (tag)
+ *    chance to examine buffer metadata, or to send some custom (tag)
  *    events, or to perform custom (segment) filtering.
  *
  *  * During the parsing process #GstBaseParseClass will handle both srcpad
- *    and sinkpad events. They will be passed to subclass if @event or
+ *    and sinkpad events. They will be passed to subclass if
- *    @src_event callbacks have been provided.
+ *    #GstBaseParseClass.event() or #GstBaseParseClass.src_event()
+ *    implementations have been provided.
  *
  * ## Shutdown phase
  *
- * * #GstBaseParse class calls @stop to inform the subclass that data
+ * * #GstBaseParse class calls #GstBaseParseClass.stop() to inform the
- *   parsing will be stopped.
+ *   subclass that data parsing will be stopped.
  *
- * Subclass is responsible for providing pad template caps for
+ * Subclass is responsible for providing pad template caps for source and
- * source and sink pads. The pads need to be named "sink" and "src". It also
+ * sink pads. The pads need to be named "sink" and "src". It also needs to
- * needs to set the fixed caps on srcpad, when the format is ensured (e.g.
+ * set the fixed caps on srcpad, when the format is ensured (e.g.  when
- * when base class calls subclass' @set_sink_caps function).
+ * base class calls subclass' #GstBaseParseClass.set_sink_caps() function).
  *
  * This base class uses %GST_FORMAT_DEFAULT as a meaning of frames. So,
  * subclass conversion routine needs to know that conversion from
@@ -136,9 +141,10 @@
  * * Fixate the source pad caps when appropriate
  * * Inform base class how big data chunks should be retrieved. This is
  *   done with gst_base_parse_set_min_frame_size() function.
- * * Examine data chunks passed to subclass with @handle_frame and pass
+ * * Examine data chunks passed to subclass with
- *   proper frame(s) to gst_base_parse_finish_frame(), and setting src pad
+ *   #GstBaseParseClass.handle_frame() and pass proper frame(s) to
- *   caps and timestamps on frame.
+ *   gst_base_parse_finish_frame(), and setting src pad caps and timestamps
+ *   on frame.
  * * Provide conversion functions
  * * Update the duration information with gst_base_parse_set_duration()
  * * Optionally passthrough using gst_base_parse_set_passthrough()
@@ -148,13 +154,14 @@
  *
  * * In particular, if subclass is unable to determine a duration, but
  *   parsing (or specs) yields a frames per seconds rate, then this can be
- *   provided to #GstBaseParse to enable it to cater for
+ *   provided to #GstBaseParse to enable it to cater for buffer time
- *   buffer time metadata (which will be taken from upstream as much as
+ *   metadata (which will be taken from upstream as much as
  *   possible). Internally keeping track of frame durations and respective
  *   sizes that have been pushed provides #GstBaseParse with an estimated
- *   bitrate. A default @convert (used if not overridden) will then use these
+ *   bitrate. A default #GstBaseParseClass.convert() (used if not
- *   rates to perform obvious conversions.  These rates are also used to
+ *   overridden) will then use these rates to perform obvious conversions.
- *   update (estimated) duration at regular frame intervals.
+ *   These rates are also used to update (estimated) duration at regular
+ *   frame intervals.
  *
  */
 
@@ -655,6 +662,15 @@ gst_base_parse_get_property (GObject * object, guint prop_id, GValue * value,
   }
 }
 
+/**
+ * gst_base_parse_frame_copy:
+ * @frame: a #GstBaseParseFrame
+ *
+ * Copies a #GstBaseParseFrame.
+ *
+ * Returns: A copy of @frame
+ */
+
 GstBaseParseFrame *
 gst_base_parse_frame_copy (GstBaseParseFrame * frame)
 {
@@ -669,6 +685,12 @@ gst_base_parse_frame_copy (GstBaseParseFrame * frame)
   return copy;
 }
 
+/**
+ * gst_base_parse_frame_free:
+ * @frame: A #GstBaseParseFrame
+ *
+ * Frees the provided @frame.
+ */
 void
 gst_base_parse_frame_free (GstBaseParseFrame * frame)
 {
@@ -1651,7 +1673,7 @@ gst_base_parse_src_event_default (GstBaseParse * parse, GstEvent * event)
  * @dest_format: #GstFormat defining the converted format.
  * @dest_value: (out): Pointer where the conversion result will be put.
  *
- * Default implementation of "convert" vmethod in #GstBaseParse class.
+ * Default implementation of #GstBaseParseClass.convert().
  *
  * Returns: %TRUE if conversion was successful.
  */
@@ -3818,11 +3840,11 @@ gst_base_parse_set_average_bitrate (GstBaseParse * parse, guint bitrate)
 /**
  * gst_base_parse_set_min_frame_size:
  * @parse: #GstBaseParse.
- * @min_size: Minimum size of the data that this base class should give to
+ * @min_size: Minimum size in bytes of the data that this base class should
- *            subclass.
+ *       give to subclass.
  *
  * Subclass can use this function to tell the base class that it needs to
- * give at least #min_size buffers.
+ * be given buffers of at least @min_size bytes.
  */
 void
 gst_base_parse_set_min_frame_size (GstBaseParse * parse, guint min_size)
@@ -3930,10 +3952,10 @@ gst_base_parse_set_syncable (GstBaseParse * parse, gboolean syncable)
  * Set if the nature of the format or configuration does not allow (much)
  * parsing, and the parser should operate in passthrough mode (which only
  * applies when operating in push mode). That is, incoming buffers are
- * pushed through unmodified, i.e. no @check_valid_frame or @parse_frame
+ * pushed through unmodified, i.e. no #GstBaseParseClass.handle_frame()
- * callbacks will be invoked, but @pre_push_frame will still be invoked,
+ * will be invoked, but #GstBaseParseClass.pre_push_frame() will still be
- * so subclass can perform as much or as little is appropriate for
+ * invoked, so subclass can perform as much or as little is appropriate for
- * passthrough semantics in @pre_push_frame.
+ * passthrough semantics in #GstBaseParseClass.pre_push_frame().
  */
 void
 gst_base_parse_set_passthrough (GstBaseParse * parse, gboolean passthrough)

libs/gst/base/gstbaseparse.h

@@ -54,9 +54,10 @@ G_BEGIN_DECLS
 /**
  * GST_BASE_PARSE_FLOW_DROPPED:
  *
- * A #GstFlowReturn that can be returned from parse_frame to
+ * A #GstFlowReturn that can be returned from
- * indicate that no output buffer was generated, or from pre_push_frame to
+ * #GstBaseParseClass.handle_frame() to indicate that no output buffer was
- * to forego pushing buffer.
+ * generated, or from #GstBaseParseClass.pre_push_frame() to to forego
+ * pushing buffer.
  */
 #define GST_BASE_PARSE_FLOW_DROPPED     GST_FLOW_CUSTOM_SUCCESS