diff --git a/gst/gstbin.c b/gst/gstbin.c
index 3cee36ed73..2e63722846 100644
--- a/gst/gstbin.c
+++ b/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
-   * a field named 'message' of type GST_TYPE_MESSAGE that contains the original
+   * source. The structure of the message is named `GstBinForwarded` and contains
+   * 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,
- * or %NULL
+ * Returns: (transfer full) (nullable): a #GstIterator of #GstElement
  */
 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,
- * or %NULL
+ * Returns: (transfer full) (nullable): a #GstIterator of #GstElement
  */
 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,
- * or %NULL
+ * Returns: (transfer full) (nullable): a #GstIterator of #GstElement
  */
 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,
- * or %NULL
+ * Returns: (transfer full) (nullable): a #GstIterator of #GstElement
  */
 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,
- * or %NULL
+ * Returns: (transfer full) (nullable): a #GstIterator of #GstElement
  */
 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
- * elements with a LATENCY event.
+ * Queries @bin for the current latency and reconfigures this latency on all the
+ * 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.
- *
- * MT safe.  Caller owns returned value.
+ * of #GstElement.
  *
  * Returns: (transfer full) (nullable): a #GstIterator of #GstElement
- *     for all elements in the bin implementing the given interface,
- *     or %NULL
+ *     for all elements in the bin implementing the given interface
  */
 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.
- *
- * MT safe. Caller owns returned value.
+ * #GstElement.
  *
  * Returns: (transfer full) (nullable): a #GstIterator of #GstElement
- *     for all elements in the bin with the given element factory name,
- *     or %NULL.
+ *     for all elements in the bin with the given element factory name
  *
  * Since: 1.18
  */
diff --git a/gst/gstbin.h b/gst/gstbin.h
index 0a2c3458a8..029213075c 100644
--- a/gst/gstbin.h
+++ b/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,
- * and (un)set using GST_OBJECT_FLAG_SET () and GST_OBJECT_FLAG_UNSET ().
+ * 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().
  */
 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
- * update the list of children in the bin.
+ * Subclasses can override #GstBinClass::add_element and #GstBinClass::remove_element
+ * to update the list of children in the bin.
  *
- * The @handle_message method can be overridden to implement custom
- * message handling.  @handle_message takes ownership of the message, just like
- * #gst_element_post_message.
+ * The #GstBinClass::handle_message method can be overridden to implement custom
+ * message handling. handle_message takes ownership of the message, just like
+ * 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 >*/
diff --git a/gst/gstutils.c b/gst/gstutils.c
index daec476a6e..50754b96b3 100644
--- a/gst/gstutils.c
+++ b/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)