docs: standardize GstBin documentation

* Don't mention explicitly that API is MT safe, this implies that
  other API is not. GStreamer API is assumed to be MT safe, thread
  safety should only be explicitly mentioned when API is *not* MT safe

* Don't repeat what annotations are stating with respect to ownership
  transfer, nullability

* Document virtual methods in standalone comments, so that parameters
  can be documented. This is not critical here, as parameters do not
  need annotations / specific documentation, but serves as an up to
  date example

* Document enumeration members in standalone comments, so that their
  Since tag is accounted for by gobject-introspection

* Misc cleanup / typo fixes / addition of links

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

gst/gstbin.c

@@ -19,8 +19,6 @@
  * License along with this library; if not, write to the
  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  * Boston, MA 02110-1301, USA.
- *
- * MT safe.
  */
 
 /**
@@ -363,7 +361,7 @@ gst_bin_class_init (GstBinClass * klass)
 
   /**
    * GstBin::element-added:
-   * @bin: the #GstBin
+   * @self: the #GstBin
    * @element: the #GstElement that was added to the bin
    *
    * Will be emitted after the element was added to the bin.
@@ -374,7 +372,7 @@ gst_bin_class_init (GstBinClass * klass)
       NULL, NULL, G_TYPE_NONE, 1, GST_TYPE_ELEMENT);
   /**
    * GstBin::element-removed:
-   * @bin: the #GstBin
+   * @self: the #GstBin
    * @element: the #GstElement that was removed from the bin
    *
    * Will be emitted after the element was removed from the bin.
@@ -385,11 +383,11 @@ gst_bin_class_init (GstBinClass * klass)
       NULL, NULL, G_TYPE_NONE, 1, GST_TYPE_ELEMENT);
   /**
    * GstBin::deep-element-added:
-   * @bin: the #GstBin
+   * @self: the #GstBin
    * @sub_bin: the #GstBin the element was added to
    * @element: the #GstElement that was added to @sub_bin
    *
-   * Will be emitted after the element was added to sub_bin.
+   * Will be emitted after the element was added to @sub_bin.
    *
    * Since: 1.10
    */
@@ -399,11 +397,11 @@ gst_bin_class_init (GstBinClass * klass)
       NULL, NULL, NULL, G_TYPE_NONE, 2, GST_TYPE_BIN, GST_TYPE_ELEMENT);
   /**
    * GstBin::deep-element-removed:
-   * @bin: the #GstBin
+   * @self: the #GstBin
    * @sub_bin: the #GstBin the element was removed from
    * @element: the #GstElement that was removed from @sub_bin
    *
-   * Will be emitted after the element was removed from sub_bin.
+   * Will be emitted after the element was removed from @sub_bin.
    *
    * Since: 1.10
    */
@@ -413,10 +411,10 @@ gst_bin_class_init (GstBinClass * klass)
       NULL, NULL, NULL, G_TYPE_NONE, 2, GST_TYPE_BIN, GST_TYPE_ELEMENT);
   /**
    * GstBin::do-latency:
-   * @bin: the #GstBin
+   * @self: the #GstBin
    *
    * Will be emitted when the bin needs to perform latency calculations. This
-   * signal is only emitted for toplevel bins or when async-handling is
+   * signal is only emitted for toplevel bins or when #GstBin:async-handling is
    * enabled.
    *
    * Only one signal handler is invoked. If no signals are connected, the
@@ -440,8 +438,8 @@ gst_bin_class_init (GstBinClass * klass)
    * state of individual elements, for example.
    *
    * The messages are converted to an ELEMENT message with the bin as the
-   * source. The structure of the message is named 'GstBinForwarded' and contains
+   * source. The structure of the message is named `GstBinForwarded` and contains
-   * a field named 'message' of type GST_TYPE_MESSAGE that contains the original
+   * a field named `message` of type %GST_TYPE_MESSAGE that contains the original
    * forwarded message.
    */
   g_object_class_install_property (gobject_class, PROP_MESSAGE_FORWARD,
@@ -1416,13 +1414,11 @@ had_parent:
  * @bin: a #GstBin
  * @flags: the #GstElementFlags to suppress
  *
- * Suppress the given flags on the bin. #GstElementFlags of a
+ * Suppresses the given flags on the bin. #GstElementFlags of a
  * child element are propagated when it is added to the bin.
  * When suppressed flags are set, those specified flags will
  * not be propagated to the bin.
  *
- * MT safe.
- *
  * Since: 1.10
  */
 void
@@ -1442,10 +1438,6 @@ gst_bin_set_suppressed_flags (GstBin * bin, GstElementFlags flags)
  * gst_bin_get_suppressed_flags:
  * @bin: a #GstBin
  *
- * Return the suppressed flags of the bin.
- *
- * MT safe.
- *
  * Returns: the bin's suppressed #GstElementFlags.
  *
  * Since: 1.10
@@ -1527,8 +1519,6 @@ gst_bin_deep_element_removed_func (GstBin * bin, GstBin * sub_bin,
  * > with gst_element_set_state(), or use gst_element_sync_state_with_parent().
  * > The bin or pipeline will not take care of this for you.
  *
- * MT safe.
- *
  * Returns: %TRUE if the element could be added, %FALSE if
  * the bin does not want to accept the element.
  */
@@ -1880,8 +1870,6 @@ not_in_bin:
  * If the element's pads are linked to other pads, the pads will be unlinked
  * before the element is removed from the bin.
  *
- * MT safe.
- *
  * Returns: %TRUE if the element could be removed, %FALSE if
  * the bin does not want to remove the element.
  */
@@ -1924,10 +1912,7 @@ no_function:
  *
  * Gets an iterator for the elements in this bin.
  *
- * MT safe.  Caller owns returned value.
+ * Returns: (transfer full) (nullable): a #GstIterator of #GstElement
- *
- * Returns: (transfer full) (nullable): a #GstIterator of #GstElement,
- * or %NULL
  */
 GstIterator *
 gst_bin_iterate_elements (GstBin * bin)
@@ -1965,10 +1950,7 @@ iterate_child_recurse (GstIterator * it, const GValue * item)
  * Gets an iterator for the elements in this bin.
  * This iterator recurses into GstBin children.
  *
- * MT safe.  Caller owns returned value.
+ * Returns: (transfer full) (nullable): a #GstIterator of #GstElement
- *
- * Returns: (transfer full) (nullable): a #GstIterator of #GstElement,
- * or %NULL
  */
 GstIterator *
 gst_bin_iterate_recurse (GstBin * bin)
@@ -2023,10 +2005,7 @@ sink_iterator_filter (const GValue * vchild, GValue * vbin)
  * Gets an iterator for all elements in the bin that have the
  * #GST_ELEMENT_FLAG_SINK flag set.
  *
- * MT safe.  Caller owns returned value.
+ * Returns: (transfer full) (nullable): a #GstIterator of #GstElement
- *
- * Returns: (transfer full) (nullable): a #GstIterator of #GstElement,
- * or %NULL
  */
 GstIterator *
 gst_bin_iterate_sinks (GstBin * bin)
@@ -2084,10 +2063,7 @@ src_iterator_filter (const GValue * vchild, GValue * vbin)
  * Gets an iterator for all elements in the bin that have the
  * #GST_ELEMENT_FLAG_SOURCE flag set.
  *
- * MT safe.  Caller owns returned value.
+ * Returns: (transfer full) (nullable): a #GstIterator of #GstElement
- *
- * Returns: (transfer full) (nullable): a #GstIterator of #GstElement,
- * or %NULL
  */
 GstIterator *
 gst_bin_iterate_sources (GstBin * bin)
@@ -2477,10 +2453,7 @@ gst_bin_sort_iterator_new (GstBin * bin)
  * This function is used internally to perform the state changes
  * of the bin elements and for clock selection.
  *
- * MT safe.  Caller owns returned value.
+ * Returns: (transfer full) (nullable): a #GstIterator of #GstElement
- *
- * Returns: (transfer full) (nullable): a #GstIterator of #GstElement,
- * or %NULL
  */
 GstIterator *
 gst_bin_iterate_sorted (GstBin * bin)
@@ -2753,13 +2726,13 @@ failed:
  * gst_bin_recalculate_latency:
  * @bin: a #GstBin
  *
- * Query @bin for the current latency using and reconfigures this latency to all the
+ * Queries @bin for the current latency and reconfigures this latency on all the
- * elements with a LATENCY event.
+ * elements using a LATENCY event.
  *
  * This method is typically called on the pipeline when a #GST_MESSAGE_LATENCY
  * is posted on the bus.
  *
- * This function simply emits the 'do-latency' signal so any custom latency
+ * This function simply emits the #GstBin::do-latency signal so any custom latency
  * calculations will be performed.
  *
  * Returns: %TRUE if the latency could be queried and reconfigured.
@@ -4417,12 +4390,8 @@ compare_name (const GValue * velement, const gchar * name)
  * Gets the element with the given name from a bin. This
  * function recurses into child bins.
  *
- * Returns %NULL if no element with the given name is found in the bin.
- *
- * MT safe.  Caller owns returned reference.
- *
  * Returns: (transfer full) (nullable): the #GstElement with the given
- * name, or %NULL
+ * name
  */
 GstElement *
 gst_bin_get_by_name (GstBin * bin, const gchar * name)
@@ -4460,13 +4429,8 @@ gst_bin_get_by_name (GstBin * bin, const gchar * name)
  * Gets the element with the given name from this bin. If the
  * element is not found, a recursion is performed on the parent bin.
  *
- * Returns %NULL if:
- * - no element with the given name is found in the bin
- *
- * MT safe.  Caller owns returned reference.
- *
  * Returns: (transfer full) (nullable): the #GstElement with the given
- * name, or %NULL
+ * name
  */
 GstElement *
 gst_bin_get_by_name_recurse_up (GstBin * bin, const gchar * name)
@@ -4519,8 +4483,6 @@ compare_interface (const GValue * velement, GValue * interface)
  * all elements that implement the interface, use
  * gst_bin_iterate_all_by_interface(). This function recurses into child bins.
  *
- * MT safe.  Caller owns returned reference.
- *
  * Returns: (transfer full) (nullable): A #GstElement inside the bin
  * implementing the interface
  */
@@ -4563,13 +4525,10 @@ gst_bin_get_by_interface (GstBin * bin, GType iface)
  * Looks for all elements inside the bin that implements the given
  * interface. You can safely cast all returned elements to the given interface.
  * The function recurses inside child bins. The iterator will yield a series
- * of #GstElement that should be unreffed after use.
+ * of #GstElement.
- *
- * MT safe.  Caller owns returned value.
  *
  * Returns: (transfer full) (nullable): a #GstIterator of #GstElement
- *     for all elements in the bin implementing the given interface,
+ *     for all elements in the bin implementing the given interface
- *     or %NULL
  */
 GstIterator *
 gst_bin_iterate_all_by_interface (GstBin * bin, GType iface)
@@ -4613,13 +4572,10 @@ compare_factory_names (const GValue * velement, GValue * factory_name_val)
  *
  * Looks for all elements inside the bin with the given element factory name.
  * The function recurses inside child bins. The iterator will yield a series of
- * #GstElement that should be unreffed after use.
+ * #GstElement.
- *
- * MT safe. Caller owns returned value.
  *
  * Returns: (transfer full) (nullable): a #GstIterator of #GstElement
- *     for all elements in the bin with the given element factory name,
+ *     for all elements in the bin with the given element factory name
- *     or %NULL.
  *
  * Since: 1.18
  */

gst/gstbin.h

@@ -40,22 +40,41 @@ G_BEGIN_DECLS
 
 /**
  * GstBinFlags:
- * @GST_BIN_FLAG_NO_RESYNC: don't resync a state change when elements are
- *             added or linked in the bin (Since: 1.0.5)
- * @GST_BIN_FLAG_STREAMS_AWARE: Indicates whether the bin can handle elements
- *             that add/remove source pads at any point in time without
- *             first posting a no-more-pads signal (Since: 1.10)
  * @GST_BIN_FLAG_LAST: the last enum in the series of flags for bins.
  * Derived classes can use this as first value in a list of flags.
  *
  * GstBinFlags are a set of flags specific to bins. Most are set/used
- * internally. They can be checked using the GST_OBJECT_FLAG_IS_SET () macro,
+ * internally. They can be checked using the GST_OBJECT_FLAG_IS_SET() macro,
- * and (un)set using GST_OBJECT_FLAG_SET () and GST_OBJECT_FLAG_UNSET ().
+ * and (un)set using GST_OBJECT_FLAG_SET() and GST_OBJECT_FLAG_UNSET().
  */
 typedef enum {
+  /**
+   * GST_BIN_FLAG_NO_RESYNC:
+   *
+   * Don't resync a state change when elements are added or linked in the bin
+   *
+   * Since: 1.0.5
+   */
   GST_BIN_FLAG_NO_RESYNC	= (GST_ELEMENT_FLAG_LAST << 0),
+
+  /**
+   * GST_BIN_FLAG_STREAMS_AWARE:
+   *
+   * Indicates whether the bin can handle elements that add/remove source pads
+   * at any point in time without first posting a no-more-pads signal.
+   *
+   * Since: 1.10
+   */
   GST_BIN_FLAG_STREAMS_AWARE	= (GST_ELEMENT_FLAG_LAST << 1),
+
   /* padding */
+
+  /**
+   * GST_BIN_FLAG_LAST:
+   *
+   * The last enum in the series of flags for bins. Derived classes can use this
+   * as first value in a list of flags.
+   */
   GST_BIN_FLAG_LAST		= (GST_ELEMENT_FLAG_LAST << 5)
 } GstBinFlags;
 
@@ -85,7 +104,7 @@ typedef struct _GstBinPrivate GstBinPrivate;
  * GST_BIN_CHILDREN:
  * @bin: a #GstBin
  *
- * Gets the list with children in a bin.
+ * Gets the list of children in a bin.
  */
 #define GST_BIN_CHILDREN(bin)		(GST_BIN_CAST(bin)->children)
 /**
@@ -141,22 +160,15 @@ struct _GstBin {
 /**
  * GstBinClass:
  * @parent_class: bin parent class
- * @add_element: method to add an element to a bin
- * @remove_element: method to remove an element from a bin
- * @handle_message: method to handle a message from the children
- * @deep_element_added: method called when an element was added somewhere
- *     in the bin hierarchy
- * @deep_element_removed: method called when an element was removed somewhere
- *     in the bin hierarchy
  *
- * Subclasses can override the @add_element and @remove_element to
+ * Subclasses can override #GstBinClass::add_element and #GstBinClass::remove_element
- * update the list of children in the bin.
+ * to update the list of children in the bin.
  *
- * The @handle_message method can be overridden to implement custom
+ * The #GstBinClass::handle_message method can be overridden to implement custom
- * message handling.  @handle_message takes ownership of the message, just like
+ * message handling. handle_message takes ownership of the message, just like
- * #gst_element_post_message.
+ * gst_element_post_message().
  *
- * The @deep_element_added vfunc will be called when a new element has been
+ * #GstBinClass::deep_element_added will be called when a new element has been
  * added to any bin inside this bin, so it will also be called if a new child
  * was added to a sub-bin of this bin. #GstBin implementations that override
  * this message should chain up to the parent class implementation so the
@@ -169,14 +181,57 @@ struct _GstBinClass {
   GThreadPool  *pool; /* deprecated */
 
   /* signals */
+
+  /**
+   * GstBinClass::element_added:
+   * @bin: the #GstBin
+   * @child: the element that was added
+   *
+   * Method called when an element was added to the bin.
+   */
   void		(*element_added)	(GstBin *bin, GstElement *child);
+
+  /**
+   * GstBinClass::element_removed:
+   * @bin: the #GstBin
+   * @child: the element that was removed
+   *
+   * Method called when an element was removed from the bin.
+   */
   void		(*element_removed)	(GstBin *bin, GstElement *child);
 
   /*< public >*/
   /* virtual methods for subclasses */
+
+  /**
+   * GstBinClass::add_element:
+   * @bin: the #GstBin
+   * @element: the element to be added
+   *
+   * Method to add an element to the bin.
+   *
+   * Returns: %TRUE if the @element was added
+   */
   gboolean	(*add_element)		(GstBin *bin, GstElement *element);
+
+  /**
+   * GstBinClass::remove_element:
+   * @bin: the #GstBin
+   * @element: the element to be removed
+   *
+   * Method to remove an element from the bin.
+   *
+   * Returns: %TRUE if the @element was removed
+   */
   gboolean	(*remove_element)	(GstBin *bin, GstElement *element);
 
+  /**
+   * GstBinClass::handle_message:
+   * @bin: the #GstBin
+   * @message: the message to be handled
+   *
+   * Method to handle a message from the children.
+   */
   void		(*handle_message)	(GstBin *bin, GstMessage *message);
 
   /*< private >*/
@@ -185,7 +240,25 @@ struct _GstBinClass {
 
   /*< public >*/
   /* signal */
+
+  /**
+   * GstBinClass::deep_element_added:
+   * @bin: the top level #GstBin
+   * @sub_bin: the #GstBin to which the element was added
+   * @child: the element that was added
+   *
+   * Method called when an element was added somewhere in the bin hierarchy.
+   */
   void          (*deep_element_added)   (GstBin *bin, GstBin *sub_bin, GstElement *child);
+
+  /**
+   * GstBinClass::deep_element_removed:
+   * @bin: the top level #GstBin
+   * @sub_bin: the #GstBin from which the element was removed
+   * @child: the element that was removed
+   *
+   * Method called when an element was removed somewhere in the bin hierarchy.
+   */
   void          (*deep_element_removed) (GstBin *bin, GstBin *sub_bin, GstElement *child);
 
   /*< private >*/

gst/gstutils.c

@@ -2716,7 +2716,7 @@ gst_bin_add_many (GstBin * bin, GstElement * element_1, ...)
  * @element_1: (transfer none): the first #GstElement to remove from the bin
  * @...: (transfer none): %NULL-terminated list of elements to remove from the bin
  *
- * Remove a list of elements from a bin. This function is equivalent
+ * Removes a list of elements from a bin. This function is equivalent
  * to calling gst_bin_remove() with each member of the list.
  */
 void
@@ -3295,7 +3295,7 @@ element_find_unlinked_pad (GstElement * element, GstPadDirection direction)
  * pad when it is not needed any longer.
  *
  * Returns: (transfer full) (nullable): unlinked pad of the given
- * direction, %NULL.
+ * direction.
  */
 GstPad *
 gst_bin_find_unlinked_pad (GstBin * bin, GstPadDirection direction)