docs: reformat and cleanup GstBin SECTION comment

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/747>

diff --git a/gst/gstbin.c b/gst/gstbin.c
index b0326f40d4acf04bd49020ee0456f39434a645db..3cee36ed73c1853c9cce828d7113b8d0cc5f98d7 100644 (file)
--- a/gst/gstbin.c
+++ b/gst/gstbin.c
@@ -56,75 +56,82 @@
  * the bin. Likewise the #GstBin::element-removed signal is fired whenever an
  * element is removed from the bin.
  *
- * ## Notes
- *
  * A #GstBin internally intercepts every #GstMessage posted by its children and
  * implements the following default behaviour for each of them:
  *
- * * GST_MESSAGE_EOS: This message is only posted by sinks in the PLAYING
+ * * %GST_MESSAGE_EOS: This message is only posted by sinks in the PLAYING
  * state. If all sinks posted the EOS message, this bin will post and EOS
  * message upwards.
  *
- * * GST_MESSAGE_SEGMENT_START: Just collected and never forwarded upwards.
- * The messages are used to decide when all elements have completed playback
- * of their segment.
+ * * %GST_MESSAGE_SEGMENT_START: Just collected and never forwarded upwards.
+ *   The messages are used to decide when all elements have completed playback
+ *   of their segment.
+ *
+ * * %GST_MESSAGE_SEGMENT_DONE: Is posted by #GstBin when all elements that posted
+ *   a SEGMENT_START have posted a SEGMENT_DONE.
+ *
+ * * %GST_MESSAGE_DURATION_CHANGED: Is posted by an element that detected a change
+ *   in the stream duration. The duration change is posted to the
+ *   application so that it can refetch the new duration with a duration
+ *   query.
+ *
+ *   Note that these messages can be posted before the bin is prerolled, in which
+ *   case the duration query might fail.
+ *
+ *   Note also that there might be a discrepancy (due to internal buffering/queueing)
+ *   between the stream being currently displayed and the returned duration query.
  *
- * * GST_MESSAGE_SEGMENT_DONE: Is posted by #GstBin when all elements that posted
- * a SEGMENT_START have posted a SEGMENT_DONE.
+ *   Applications might want to also query for duration (and changes) by
+ *   listening to the %GST_MESSAGE_STREAM_START message, signaling the active start
+ *   of a (new) stream.
  *
- * * GST_MESSAGE_DURATION_CHANGED: Is posted by an element that detected a change
- * in the stream duration. The duration change is posted to the
- * application so that it can refetch the new duration with a duration
- * query. Note that these messages can be posted before the bin is
- * prerolled, in which case the duration query might fail. Note also that
- * there might be a discrepancy (due to internal buffering/queueing) between the
- * stream being currently displayed and the returned duration query.
- * Applications might want to also query for duration (and changes) by
- * listening to the GST_MESSAGE_STREAM_START message, signaling the active start
- * of a (new) stream.
+ * * %GST_MESSAGE_CLOCK_LOST: This message is posted by an element when it
+ *   can no longer provide a clock.
  *
- * * GST_MESSAGE_CLOCK_LOST: This message is posted by an element when it
- * can no longer provide a clock. The default bin behaviour is to
- * check if the lost clock was the one provided by the bin. If so and
- * the bin is currently in the PLAYING state, the message is forwarded to
- * the bin parent.
- * This message is also generated when a clock provider is removed from
- * the bin. If this message is received by the application, it should
- * PAUSE the pipeline and set it back to PLAYING to force a new clock
- * distribution.
+ *   The default bin behaviour is to check if the lost clock was the one provided
+ *   by the bin. If so and the bin is currently in the PLAYING state, the message
+ *   is forwarded to the bin parent.
  *
- * * GST_MESSAGE_CLOCK_PROVIDE: This message is generated when an element
- * can provide a clock. This mostly happens when a new clock
- * provider is added to the bin. The default behaviour of the bin is to
- * mark the currently selected clock as dirty, which will perform a clock
- * recalculation the next time the bin is asked to provide a clock.
- * This message is never sent tot the application but is forwarded to
- * the parent of the bin.
+ *   This message is also generated when a clock provider is removed from
+ *   the bin. If this message is received by the application, it should
+ *   PAUSE the pipeline and set it back to PLAYING to force a new clock
+ *   distribution.
+ *
+ * * %GST_MESSAGE_CLOCK_PROVIDE: This message is generated when an element
+ *   can provide a clock. This mostly happens when a new clock
+ *   provider is added to the bin.
+ *
+ *   The default behaviour of the bin is to mark the currently selected clock as
+ *   dirty, which will perform a clock recalculation the next time the bin is
+ *   asked to provide a clock.
+ *
+ *   This message is never sent to the application but is forwarded to
+ *   the parent of the bin.
  *
  * * OTHERS: posted upwards.
  *
  * A #GstBin implements the following default behaviour for answering to a
  * #GstQuery:
  *
- * * GST_QUERY_DURATION: The bin will forward the query to all sink
- * elements contained within and will return the maximum value.
- * If no sinks are available in the bin, the query fails.
+ * * %GST_QUERY_DURATION: The bin will forward the query to all sink
+ *   elements contained within and will return the maximum value.
+ *   If no sinks are available in the bin, the query fails.
  *
- * * GST_QUERY_POSITION:The query is sent to all sink elements in the bin and the
- * MAXIMUM of all values is returned. If no sinks are available in the bin,
- * the query fails.
+ * * %GST_QUERY_POSITION: The query is sent to all sink elements in the bin and the
+ *   MAXIMUM of all values is returned. If no sinks are available in the bin,
+ *   the query fails.
  *
- * * OTHERS:the query is forwarded to all sink elements, the result
- * of the first sink that answers the query successfully is returned. If no
- * sink is in the bin, the query fails.
+ * * OTHERS: the query is forwarded to all sink elements, the result
+ *   of the first sink that answers the query successfully is returned. If no
+ *   sink is in the bin, the query fails.
  *
  * A #GstBin will by default forward any event sent to it to all sink
- * (#GST_EVENT_TYPE_DOWNSTREAM) or source (#GST_EVENT_TYPE_UPSTREAM) elements
+ * ( %GST_EVENT_TYPE_DOWNSTREAM ) or source ( %GST_EVENT_TYPE_UPSTREAM ) elements
  * depending on the event type.
+ *
  * If all the elements return %TRUE, the bin will also return %TRUE, else %FALSE
  * is returned. If no elements of the required type are in the bin, the event
  * handler will return %TRUE.
- *
  */
 
 #include "gst_private.h"