diff --git a/gst/gstcapsfeatures.c b/gst/gstcapsfeatures.c
index d6d0b1e68b..3e02a8cc88 100644
--- a/gst/gstcapsfeatures.c
+++ b/gst/gstcapsfeatures.c
@@ -40,8 +40,8 @@
  *
  * Examples for caps features would be the requirement of a specific #GstMemory
  * types or the requirement of having a specific #GstMeta on the buffer. Features
- * are given as a string of the format "memory:GstMemoryTypeName" or
- * "meta:GstMetaAPIName".
+ * are given as a string of the format `memory:GstMemoryTypeName` or
+ * `meta:GstMetaAPIName`.
  *
  * Since: 1.2
  */
@@ -171,8 +171,6 @@ gst_caps_feature_name_is_valid (const gchar * feature)
  *
  * Creates a new, empty #GstCapsFeatures.
  *
- * Free-function: gst_caps_features_free
- *
  * Returns: (transfer full): a new, empty #GstCapsFeatures
  *
  * Since: 1.2
@@ -200,8 +198,6 @@ gst_caps_features_new_empty (void)
  * to any other #GstCapsFeatures but caps with these are
  * unfixed.
  *
- * Free-function: gst_caps_features_free
- *
  * Returns: (transfer full): a new, ANY #GstCapsFeatures
  *
  * Since: 1.2
@@ -225,8 +221,6 @@ gst_caps_features_new_any (void)
  * Creates a new #GstCapsFeatures with the given features.
  * The last argument must be %NULL.
  *
- * Free-function: gst_caps_features_free
- *
  * Returns: (transfer full): a new, empty #GstCapsFeatures
  *
  * Since: 1.2
@@ -253,8 +247,6 @@ gst_caps_features_new (const gchar * feature1, ...)
  *
  * Creates a new #GstCapsFeatures with the given features.
  *
- * Free-function: gst_caps_features_free
- *
  * Returns: (transfer full): a new, empty #GstCapsFeatures
  *
  * Since: 1.2
@@ -284,8 +276,6 @@ gst_caps_features_new_valist (const gchar * feature1, va_list varargs)
  * Creates a new #GstCapsFeatures with the given features.
  * The last argument must be 0.
  *
- * Free-function: gst_caps_features_free
- *
  * Returns: (transfer full): a new, empty #GstCapsFeatures
  *
  * Since: 1.2
@@ -312,8 +302,6 @@ gst_caps_features_new_id (GQuark feature1, ...)
  *
  * Creates a new #GstCapsFeatures with the given features.
  *
- * Free-function: gst_caps_features_free
- *
  * Returns: (transfer full): a new, empty #GstCapsFeatures
  *
  * Since: 1.2
@@ -343,7 +331,7 @@ gst_caps_features_new_id_valist (GQuark feature1, va_list varargs)
  * Sets the parent_refcount field of #GstCapsFeatures. This field is used to
  * determine whether a caps features is mutable or not. This function should only be
  * called by code implementing parent objects of #GstCapsFeatures, as described in
- * the MT Refcounting section of the design documents.
+ * [the MT refcounting design document](additional/design/MT-refcounting.md).
  *
  * Returns: %TRUE if the parent refcount could be set.
  *
@@ -380,8 +368,6 @@ gst_caps_features_set_parent_refcount (GstCapsFeatures * features,
  *
  * Duplicates a #GstCapsFeatures and all its values.
  *
- * Free-function: gst_caps_features_free
- *
  * Returns: (transfer full): a new #GstCapsFeatures.
  *
  * Since: 1.2
@@ -434,15 +420,14 @@ gst_caps_features_free (GstCapsFeatures * features)
  * Converts @features to a human-readable string representation.
  *
  * For debugging purposes its easier to do something like this:
- * |[<!-- language="C" -->
+ *
+ * ``` C
  * GST_LOG ("features is %" GST_PTR_FORMAT, features);
- * ]|
+ * ```
+ *
  * This prints the features in human readable form.
  *
- * Free-function: g_free
- *
  * Returns: (transfer full): a pointer to string allocated by g_malloc().
- *     g_free() after usage.
  *
  * Since: 1.2
  */
@@ -489,11 +474,8 @@ priv_gst_caps_features_append_to_gstring (const GstCapsFeatures * features,
  *
  * Creates a #GstCapsFeatures from a string representation.
  *
- * Free-function: gst_caps_features_free
- *
  * Returns: (transfer full) (nullable): a new #GstCapsFeatures or
- *     %NULL when the string could not be parsed. Free with
- *     gst_caps_features_free() after use.
+ *     %NULL when the string could not be parsed.
  *
  * Since: 1.2
  */
@@ -649,7 +631,7 @@ gst_caps_features_get_nth_id (const GstCapsFeatures * features, guint i)
  * @features: a #GstCapsFeatures.
  * @feature: a feature
  *
- * Check if @features contains @feature.
+ * Checks if @features contains @feature.
  *
  * Returns: %TRUE if @features contains @feature.
  *
@@ -671,7 +653,7 @@ gst_caps_features_contains (const GstCapsFeatures * features,
  * @features: a #GstCapsFeatures.
  * @feature: a feature
  *
- * Check if @features contains @feature.
+ * Checks if @features contains @feature.
  *
  * Returns: %TRUE if @features contains @feature.
  *
@@ -705,7 +687,7 @@ gst_caps_features_contains_id (const GstCapsFeatures * features, GQuark feature)
  * @features1: a #GstCapsFeatures.
  * @features2: a #GstCapsFeatures.
  *
- * Check if @features1 and @features2 are equal.
+ * Checks if @features1 and @features2 are equal.
  *
  * Returns: %TRUE if @features1 and @features2 are equal.
  *
@@ -751,7 +733,7 @@ gst_caps_features_is_equal (const GstCapsFeatures * features1,
  * gst_caps_features_is_any:
  * @features: a #GstCapsFeatures.
  *
- * Check if @features is %GST_CAPS_FEATURES_ANY.
+ * Checks if @features is %GST_CAPS_FEATURES_ANY.
  *
  * Returns: %TRUE if @features is %GST_CAPS_FEATURES_ANY.
  *
diff --git a/gst/gstchildproxy.c b/gst/gstchildproxy.c
index 9ac97d3cad..9abedbba80 100644
--- a/gst/gstchildproxy.c
+++ b/gst/gstchildproxy.c
@@ -35,9 +35,9 @@
  * By implementing this interface the child properties can be accessed from the
  * parent element by using gst_child_proxy_get() and gst_child_proxy_set().
  *
- * Property names are written as "child-name::property-name". The whole naming
- * scheme is recursive. Thus "child1::child2::property" is valid too, if
- * "child1" and "child2" implement the #GstChildProxy interface.
+ * Property names are written as `child-name::property-name`. The whole naming
+ * scheme is recursive. Thus `child1::child2::property` is valid too, if
+ * `child1` and `child2` implement the #GstChildProxy interface.
  */
 
 #include "gst_private.h"
@@ -110,9 +110,7 @@ gst_child_proxy_default_get_child_by_name (GstChildProxy * parent,
  * #GObjects, this methods needs to be overridden.
  *
  * Returns: (transfer full) (nullable): the child object or %NULL if
- *     not found. Unref after usage.
- *
- * MT safe.
+ *     not found.
  */
 GObject *
 gst_child_proxy_get_child_by_name (GstChildProxy * parent, const gchar * name)
@@ -137,9 +135,7 @@ gst_child_proxy_get_child_by_name (GstChildProxy * parent, const gchar * name)
  * Fetches a child by its number.
  *
  * Returns: (transfer full) (nullable): the child object or %NULL if
- *     not found (index too high). Unref after usage.
- *
- * MT safe.
+ *     not found (index too high).
  */
 GObject *
 gst_child_proxy_get_child_by_index (GstChildProxy * parent, guint index)
@@ -163,8 +159,6 @@ gst_child_proxy_get_child_by_index (GstChildProxy * parent, guint index)
  * Gets the number of child objects this parent contains.
  *
  * Returns: the number of child objects
- *
- * MT safe.
  */
 guint
 gst_child_proxy_get_children_count (GstChildProxy * parent)
@@ -192,11 +186,9 @@ gst_child_proxy_get_children_count (GstChildProxy * parent)
  *
  * Looks up which object and #GParamSpec would be effected by the given @name.
  *
- * MT safe.
- *
  * Returns: %TRUE if @target and @pspec could be found. %FALSE otherwise. In that
  * case the values for @pspec and @target are not modified. Unref @target after
- * usage. For plain GObjects @target is the same as @object.
+ * usage. For plain #GObject @target is the same as @object.
  */
 gboolean
 gst_child_proxy_lookup (GstChildProxy * object, const gchar * name,
@@ -484,7 +476,7 @@ gst_child_proxy_set (GstChildProxy * object, const gchar * first_property_name,
  * @child: the newly added child
  * @name: the name of the new child
  *
- * Emits the "child-added" signal.
+ * Emits the #GstChildProxy::child-added signal.
  */
 void
 gst_child_proxy_child_added (GstChildProxy * parent, GObject * child,
@@ -499,7 +491,7 @@ gst_child_proxy_child_added (GstChildProxy * parent, GObject * child,
  * @child: the removed child
  * @name: the name of the old child
  *
- * Emits the "child-removed" signal.
+ * Emits the #GstChildProxy::child-removed signal.
  */
 void
 gst_child_proxy_child_removed (GstChildProxy * parent, GObject * child,
@@ -527,7 +519,7 @@ gst_child_proxy_base_init (gpointer g_class)
     /* create interface signals and properties here. */
     /**
      * GstChildProxy::child-added:
-     * @child_proxy: the #GstChildProxy
+     * @self: the #GstChildProxy
      * @object: the #GObject that was added
      * @name: the name of the new child
      *
@@ -541,7 +533,7 @@ gst_child_proxy_base_init (gpointer g_class)
 
     /**
      * GstChildProxy::child-removed:
-     * @child_proxy: the #GstChildProxy
+     * @self: the #GstChildProxy
      * @object: the #GObject that was removed
      * @name: the name of the old child
      *
diff --git a/gst/gstchildproxy.h b/gst/gstchildproxy.h
index 57e30124d5..47444fcbcb 100644
--- a/gst/gstchildproxy.h
+++ b/gst/gstchildproxy.h
@@ -44,9 +44,6 @@ typedef struct _GstChildProxyInterface GstChildProxyInterface;
 /**
  * GstChildProxyInterface:
  * @parent: parent interface type.
- * @get_child_by_name:  virtual method to fetch the child by name
- * @get_child_by_index: virtual method to fetch the child by index
- * @get_children_count: virtual method to get the children count
  *
  * #GstChildProxy interface.
  */
@@ -55,12 +52,60 @@ struct _GstChildProxyInterface
   GTypeInterface parent;
 
   /* methods */
+
+  /**
+   * #GstChildProxyInterface::get_child_by_name:
+   * @parent: the #GstChildProxy
+   * @name: the name of the child to fetch
+   *
+   * Fetch a child object by name
+   *
+   * Returns: (transfer full) (nullable): the child object
+   */
   GObject * (*get_child_by_name)  (GstChildProxy * parent, const gchar * name);
+
+  /**
+   * #GstChildProxyInterface::get_child_by_index:
+   * @parent: the #GstChildProxy
+   * @index: the index of the child to fetch
+   *
+   * Fetch a child object by index
+   *
+   * Returns: (transfer full) (nullable): the child object
+   */
   GObject * (*get_child_by_index) (GstChildProxy * parent, guint index);
+
+  /**
+   * #GstChildProxyInterface::get_children_count:
+   * @parent: the #GstChildProxy
+   *
+   * Get the number of children in @parent
+   *
+   * Returns: the number of children
+   */
   guint     (*get_children_count) (GstChildProxy * parent);
+
   /*< private >*/
   /* signals */
+
+  /**
+   * #GstChildProxyInterface::child_added:
+   * @parent: the #GstChildProxy
+   * @child: the child object
+   * @name: the name of the child object
+   *
+   * Called when @child is added to @parent
+   */
   void      (*child_added)        (GstChildProxy * parent, GObject * child, const gchar * name);
+
+  /**
+   * #GstChildProxyInterface::child_removed:
+   * @parent: the #GstChildProxy
+   * @child: the child object
+   * @name: the name of the child object
+   *
+   * Called when @child is removed from @parent
+   */
   void      (*child_removed)      (GstChildProxy * parent, GObject * child, const gchar * name);
 
   /*< private >*/