docs: standardize GstCapsFeatures, GstChildProxy 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 * Document virtual methods in standalone comments, in order to properly annotate them * Don't repeat what annotations are stating with respect to ownership transfer, nullability * Misc cleanup / typo fixes / addition of links Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/755>
2024-06-02 05:49:40 +00:00 · 2021-02-11 16:04:01 +01:00 · 2021-02-11 16:04:01 +01:00 · c53ea138c6
parent 3f5042d74e
commit c53ea138c6
3 changed files with 70 additions and 51 deletions
--- 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.
 *
--- 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
     *
--- 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 >*/