docs: standardize GstContext, GstControlBinding documentation

* 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

* Mark GstControlBinding ABI field as private

* Misc cleanup / typo fixes / addition of links

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

3 files changed, 70 insertions, 21 deletions

diff --git a/gst/gstcontext.c b/gst/gstcontext.c
index 1e13c89a03..424cbe75c2 100644
--- a/gst/gstcontext.c
+++ b/gst/gstcontext.c
@@ -33,24 +33,25 @@
  *
  * Applications can set a context on a complete pipeline by using
  * gst_element_set_context(), which will then be propagated to all
- * child elements. Elements can handle these in #GstElementClass.set_context()
+ * child elements. Elements can handle these in #GstElementClass::set_context
  * and merge them with the context information they already have.
  *
  * When an element needs a context it will do the following actions in this
  * order until one step succeeds:
+ *
  * 1. Check if the element already has a context
- * 2. Query downstream with GST_QUERY_CONTEXT for the context
- * 3. Query upstream with GST_QUERY_CONTEXT for the context
- * 4. Post a GST_MESSAGE_NEED_CONTEXT message on the bus with the required
+ * 2. Query downstream with %GST_QUERY_CONTEXT for the context
+ * 3. Query upstream with %GST_QUERY_CONTEXT for the context
+ * 4. Post a %GST_MESSAGE_NEED_CONTEXT message on the bus with the required
  *    context types and afterwards check if a usable context was set now
- * 5. Create a context by itself and post a GST_MESSAGE_HAVE_CONTEXT message
+ * 5. Create a context by itself and post a %GST_MESSAGE_HAVE_CONTEXT message
  *    on the bus.
  *
- * Bins will catch GST_MESSAGE_NEED_CONTEXT messages and will set any previously
+ * Bins will catch %GST_MESSAGE_NEED_CONTEXT messages and will set any previously
  * known context on the element that asks for it if possible. Otherwise the
  * application should provide one if it can.
  *
- * #GstContext<!-- -->s can be persistent.
+ * #GstContext can be persistent.
  * A persistent #GstContext is kept in elements when they reach
  * %GST_STATE_NULL, non-persistent ones will be removed.
  * Also, a non-persistent context won't override a previous persistent
@@ -156,7 +157,7 @@ gst_context_init (GstContext * context)
  * @context_type: Context type
  * @persistent: Persistent context
  *
- * Create a new context.
+ * Creates a new context.
  *
  * Returns: (transfer full): The new context.
  *
@@ -189,7 +190,7 @@ gst_context_new (const gchar * context_type, gboolean persistent)
  * gst_context_get_context_type:
  * @context: The #GstContext.
  *
- * Get the type of @context.
+ * Gets the type of @context.
  *
  * Returns: The type of the context.
  *
@@ -228,7 +229,7 @@ gst_context_has_context_type (const GstContext * context,
  * gst_context_get_structure:
  * @context: The #GstContext.
  *
- * Access the structure of the context.
+ * Accesses the structure of the context.
  *
  * Returns: (transfer none): The structure of the context. The structure is
  * still owned by the context, which means that you should not modify it,
@@ -248,7 +249,7 @@ gst_context_get_structure (const GstContext * context)
  * gst_context_writable_structure:
  * @context: The #GstContext.
  *
- * Get a writable version of the structure.
+ * Gets a writable version of the structure.
  *
  * Returns: The structure of the context. The structure is still
  * owned by the context, which means that you should not free it and
@@ -270,7 +271,7 @@ gst_context_writable_structure (GstContext * context)
  * gst_context_is_persistent:
  * @context: The #GstContext.
  *
- * Check if @context is persistent.
+ * Checks if @context is persistent.
  *
  * Returns: %TRUE if the context is persistent.
  *
diff --git a/gst/gstcontrolbinding.c b/gst/gstcontrolbinding.c
index db1d4b4238..83caa5138e 100644
--- a/gst/gstcontrolbinding.c
+++ b/gst/gstcontrolbinding.c
@@ -24,7 +24,7 @@
  * @title: GstControlBinding
  * @short_description: attachment for control source sources
  *
- * A base class for value mapping objects that attaches control sources to gobject
+ * A base class for value mapping objects that attaches control sources to #GObject
  * properties. Such an object is taking one or more #GstControlSource instances,
  * combines them and maps the resulting value to the type and value range of the
  * bound property.
@@ -244,7 +244,7 @@ gst_control_binding_get_property (GObject * object, guint prop_id,
  * @last_sync: the last time this was called
  *
  * Sets the property of the @object, according to the #GstControlSources that
- * handle them and for the given timestamp.
+ * handles it and for the given timestamp.
  *
  * If this function fails, it is most likely the application developers fault.
  * Most probably the control sources are not setup correctly.
@@ -313,7 +313,7 @@ gst_control_binding_get_value (GstControlBinding * binding,
  * @values: (array length=n_values): array to put control-values in
  *
  * Gets a number of values for the given controlled property starting at the
- * requested time. The array @values need to hold enough space for @n_values of
+ * requested time. The array @values needs to hold enough space for @n_values of
  * the same type as the objects property's type.
  *
  * This function is useful if one wants to e.g. draw a graph of the control
@@ -482,7 +482,7 @@ gst_control_binding_set_disabled (GstControlBinding * binding,
  * gst_control_binding_is_disabled:
  * @binding: the control binding
  *
- * Check if the control binding is disabled.
+ * Checks if the control binding is disabled.
  *
  * Returns: %TRUE if the binding is inactive
  */
diff --git a/gst/gstcontrolbinding.h b/gst/gstcontrolbinding.h
index a0f28ce95b..e357669943 100644
--- a/gst/gstcontrolbinding.h
+++ b/gst/gstcontrolbinding.h
@@ -56,6 +56,7 @@ typedef void (* GstControlBindingConvert) (GstControlBinding *binding, gdouble s
 
 /**
  * GstControlBinding:
+ * @parent: the parent structure
  * @name: name of the property of this binding
  * @pspec: #GParamSpec for this property
  *
@@ -79,8 +80,10 @@ struct _GstControlBinding {
 
   union {
     struct {
+      /*< private >*/
       GstControlBindingPrivate *priv;
     } abi;
+    /*< private >*/
     gpointer _gst_reserved[GST_PADDING];
   } ABI;
 };
@@ -88,11 +91,6 @@ struct _GstControlBinding {
 /**
  * GstControlBindingClass:
  * @parent_class: Parent class
- * @sync_values: implementation for updating the target values
- * @get_value: implementation to fetch a single control-value
- * @get_value_array: implementation to fetch a series of control-values
- * @get_g_value_array: implementation to fetch a series of control-values
- *                     as g_values
  *
  * The class structure of #GstControlBinding.
  */
@@ -102,9 +100,59 @@ struct _GstControlBindingClass
   GstObjectClass parent_class;
 
   /*< public >*/
+
+  /**
+   * GstControlBindingClass::sync_values:
+   * @binding: the control binding
+   * @object: the object that has controlled properties
+   * @timestamp: the time that should be processed
+   * @last_sync: the last time this was called
+   *
+   * Update the target values
+   *
+   * Returns: %TRUE if the controller value could be applied to the object
+   * property, %FALSE otherwise
+   */
   gboolean (* sync_values) (GstControlBinding *binding, GstObject *object, GstClockTime timestamp, GstClockTime last_sync);
+
+  /**
+   * GstControlBindingClass::get_value:
+   * @binding: the control binding
+   * @timestamp: the time the control-change should be read from
+   *
+   * Fetch a single control-value
+   *
+   * Returns: (nullable): the GValue of the property at the given time,
+   * or %NULL if the property isn't controlled.
+   */
   GValue * (* get_value) (GstControlBinding *binding, GstClockTime timestamp);
+
+  /**
+   * GstControlBindingClass::get_value_array:
+   * @binding: the control binding
+   * @timestamp: the time that should be processed
+   * @interval: the time spacing between subsequent values
+   * @n_values: the number of values
+   * @values: (array length=n_values): array to put control-values in
+   *
+   * Fetch a series of control-values
+   *
+   * Returns: %TRUE if the given array could be filled, %FALSE otherwise
+   */
   gboolean (* get_value_array) (GstControlBinding *binding, GstClockTime timestamp,GstClockTime interval, guint n_values, gpointer values);
+
+  /**
+   * GstControlBindingClass::get_g_value_array:
+   * @binding: the control binding
+   * @timestamp: the time that should be processed
+   * @interval: the time spacing between subsequent values
+   * @n_values: the number of values
+   * @values: (array length=n_values): array to put control-values in
+   *
+   * Fetch a series of control-values as g_values
+   *
+   * Returns: %TRUE if the given array could be filled, %FALSE otherwise
+   */
   gboolean (* get_g_value_array) (GstControlBinding *binding, GstClockTime timestamp,GstClockTime interval, guint n_values, GValue *values);
 
   /*< private >*/