lib: documentation fixes

lib/wp/core.c

@@ -7,7 +7,8 @@
  */
 
 /**
- * SECTION: WpCore
+ * SECTION: core
+ * @title: Core
  *
  * The core is the central object around which everything operates. It is
  * essential to create a #WpCore before using any other WirePlumber API.

lib/wp/error.c

@@ -7,7 +7,8 @@
  */
 
 /**
- * SECTION: Error
+ * SECTION: error
+ * @title: Error codes
  *
  * Error domain and codes for #GError
  */

lib/wp/iterator.c

@@ -6,6 +6,11 @@
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * SECTION: iterator
+ * @title: Iterator
+ */
+
 #define G_LOG_DOMAIN "wp-iterator"
 
 #include "iterator.h"

lib/wp/metadata.c

@@ -365,7 +365,7 @@ static const WpIteratorMethods metadata_iterator_methods = {
 /**
  * wp_metadata_new_iterator:
  * @self: a metadata object
- * @subject: the metadata subject id, or %PW_ID_ANY
+ * @subject: the metadata subject id, or -1 (PW_ID_ANY)
  *
  * Iterates over metadata items that matches the given @subject. If no
  * constraints are specified, the returned iterator iterates over all the

lib/wp/node.c

@@ -203,7 +203,7 @@ wp_node_class_init (WpNodeClass * klass)
    * @new_state: the new state
    *
    * Emitted when the node changes state. This is only emitted
-   * when %WP_PROXY_FEATURE_INFO is enabled.
+   * when %WP_PIPEWIRE_OBJECT_FEATURE_INFO is enabled.
    */
   signals[SIGNAL_STATE_CHANGED] = g_signal_new (
       "state-changed", G_TYPE_FROM_CLASS (klass),
@@ -681,7 +681,7 @@ wp_impl_node_new_wrap (WpCore * core, struct pw_impl_node * node)
  * @factory_name.
  *
  * To export this node to the PipeWire server, you need to call
- * wp_proxy_augment() requesting %WP_PROXY_FEATURE_BOUND and
+ * wp_object_activate() requesting %WP_PROXY_FEATURE_BOUND and
  * wait for the operation to complete.
  *
  * Returns: (nullable) (transfer full): A new #WpImplNode wrapping the

lib/wp/object-manager.c

@@ -7,7 +7,8 @@
  */
 
 /**
- * SECTION: WpObjectManager
+ * SECTION: object-manager
+ * @title: Object Manager
  *
  * The #WpObjectManager class provides a way to collect a set of objects
  * and be notified when objects that fulfill a certain set of criteria are

lib/wp/properties.c

@@ -7,7 +7,8 @@
  */
 
 /**
- * SECTION: WpProperties
+ * SECTION: properties
+ * @title: PipeWire Properties Dictionary
  *
  * #WpProperties is a data structure that contains string key-value pairs,
  * which are used to send/receive/attach arbitrary properties to PipeWire

lib/wp/session-bin.c

@@ -7,8 +7,8 @@
  */
 
 /**
- * SECTION: WpSessionBin
+ * SECTION: session-bin
- * @title: Session Bin
+ * @title: Session Item Bin
  */
 
 #define G_LOG_DOMAIN "wp-sb"

lib/wp/session-item.c

@@ -7,7 +7,7 @@
  */
 
 /**
- * SECTION: WpSessionItem
+ * SECTION: session-item
  * @title: Session Items
  */
 

lib/wp/si-factory.c

@@ -7,7 +7,7 @@
  */
 
 /**
- * SECTION: WpSiFactory
+ * SECTION: si-factory
  * @title: Session Items Factory
  */
 

lib/wp/si-interfaces.c

@@ -7,8 +7,8 @@
  */
 
 /**
- * SECTION: WpSiInterfaces
+ * SECTION: si-interfaces
- * @title: WpSessionItem Interfaces
+ * @title: Session Item Interfaces
  */
 
 #define G_LOG_DOMAIN "wp-si-interfaces"

lib/wp/spa-pod.c

@@ -6,6 +6,11 @@
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * SECTION: spa-pod
+ * @title: Spa Pod (Plain Old Data)
+ */
+
 #define G_LOG_DOMAIN "wp-spa-pod"
 
 #include "spa-pod.h"
@@ -316,7 +321,7 @@ wp_spa_pod_get_spa_pod (const WpSpaPod *self)
  * If the pod is an object property or a control, this will return the type
  * of the contained value.
  *
- * Returns: the type of the spa pod
+ * Returns: (transfer none): the type of the spa pod
  */
 WpSpaType
 wp_spa_pod_get_spa_type (WpSpaPod *self)
@@ -2220,16 +2225,16 @@ wp_spa_pod_builder_add_property_id (WpSpaPodBuilder *self, guint32 id)
  * wp_spa_pod_builder_add_control:
  * @self: the spa pod builder object
  * @offset: the offset of the control
- * @type_name: the type name of the control
+ * @ctl_type: the type name of the control
  *
  * Adds a control into the builder
  */
 void
 wp_spa_pod_builder_add_control (WpSpaPodBuilder *self, guint32 offset,
-    const char *type_name)
+    const char *ctl_type)
 {
   WpSpaIdValue id = wp_spa_id_value_from_short_name (
-      SPA_TYPE_INFO_Control, type_name);
+      SPA_TYPE_INFO_Control, ctl_type);
   g_return_if_fail (id != NULL);
   spa_pod_builder_control (&self->builder, offset, wp_spa_id_value_number (id));
 }

lib/wp/spa-type.c

@@ -24,16 +24,21 @@
  * On the top level, there is a list of types like Int, Bool, String, Id, Object.
  * These are called fundamental types (terms borrowed from #GType).
  * Fundamental types can be derived and therefore we can have other types
- * that represent specific enums or objects, for instance.
+ * that represent specific objects, for instance.
  *
- * Enum and flag types are all derived directly from `SPA_TYPE_Id`. These types
+ * Enum and flag types are all represented with `SPA_TYPE_Id`. These types
  * may have a list of possible values that one can select from (enums)
- * or combine (flags). These values are accessed with the #WpSpaIdValue API.
+ * or combine (flags). These values are accessed with the #WpSpaIdTable API.
  *
  * Object types can have fields. All objects always have a special "id" field,
- * whose type can be given by wp_spa_object_type_get_id_type() and optionally,
+ * which is an enum. Its possible values can be given by
- * they can also have other object-specific fields, which are also accessed
+ * wp_spa_type_get_object_id_values_table(). Optionally, objects can also have
- * with the #WpSpaIdValue API.
+ * other object-specific fields, which can be accessed with
+ * wp_spa_type_get_values_table().
+ *
+ * Every object field or enum value is represented by a #WpSpaIdValue. In the
+ * case of object fields, each field can be of a specific type, which is
+ * returned by wp_spa_id_value_get_value_type().
  */
 
 #define G_LOG_DOMAIN "wp-spa-type"
@@ -159,7 +164,8 @@ wp_spa_type_info_find_by_name (const gchar *name)
  *
  * Looks up the type id from a given type name
  *
- * Returns: the corresponding type id or %WP_SPA_TYPE_INVALID if not found
+ * Returns: (transfer none): the corresponding type id or %WP_SPA_TYPE_INVALID
+ *   if not found
  */
 WpSpaType
 wp_spa_type_from_name (const gchar *name)
@@ -172,8 +178,9 @@ wp_spa_type_from_name (const gchar *name)
  * wp_spa_type_parent:
  * @type: a type id
  *
- * Returns: the direct parent type of the given @type; if the type is
+ * Returns: (transfer none): the direct parent type of the given @type; if the
- *   fundamental (i.e. has no parent), the returned type is the same as @type
+ *   type is fundamental (i.e. has no parent), the returned type is the same
+ *   as @type
  */
 WpSpaType
 wp_spa_type_parent (WpSpaType type)
@@ -331,6 +338,18 @@ static const WpIteratorMethods spa_type_info_iterator_methods = {
   .fold = spa_type_info_iterator_fold,
 };
 
+/**
+ * wp_spa_id_table_from_name:
+ * @name: the full name of an id table
+ *
+ * Finds a #WpSpaIdTable given its name. This name can either be the full type
+ * name of an object type, or the name of an enum (which is not(!!) a type).
+ *
+ * For example, "Spa:Pod:Object:Param:Format" and "Spa:Enum:ParamId" are
+ * both valid table names.
+ *
+ * Returns: (nullable): the associated table, or %NULL
+ */
 WpSpaIdTable
 wp_spa_id_table_from_name (const gchar *name)
 {
@@ -362,7 +381,7 @@ wp_spa_id_table_from_name (const gchar *name)
 
 /**
  * wp_spa_id_table_new_iterator:
- * @type: the id table
+ * @table: the id table
  *
  * This function returns an iterator that allows you to iterate through the
  * values associated with this table.
@@ -383,6 +402,13 @@ wp_spa_id_table_new_iterator (WpSpaIdTable table)
   return it;
 }
 
+/**
+ * wp_spa_id_table_find_value:
+ * @table: the id table
+ * @value: a numeric value that is contained in the table
+ *
+ * Returns: (nullable): the #WpSpaIdValue associated with @value, or %NULL
+ */
 WpSpaIdValue
 wp_spa_id_table_find_value (WpSpaIdTable table, guint value)
 {
@@ -397,6 +423,13 @@ wp_spa_id_table_find_value (WpSpaIdTable table, guint value)
   return NULL;
 }
 
+/**
+ * wp_spa_id_table_find_value_from_name:
+ * @table: the id table
+ * @name: the full name of a value that is contained in the table
+ *
+ * Returns: (nullable): the #WpSpaIdValue associated with @name, or %NULL
+ */
 WpSpaIdValue
 wp_spa_id_table_find_value_from_name (WpSpaIdTable table, const gchar * name)
 {
@@ -411,6 +444,13 @@ wp_spa_id_table_find_value_from_name (WpSpaIdTable table, const gchar * name)
   return NULL;
 }
 
+/**
+ * wp_spa_id_table_find_value_from_short_name:
+ * @table: the id table
+ * @short_name: the short name of a value that is contained in the table
+ *
+ * Returns: (nullable): the #WpSpaIdValue associated with @short_name, or %NULL
+ */
 WpSpaIdValue
 wp_spa_id_table_find_value_from_short_name (WpSpaIdTable table,
     const gchar * short_name)
@@ -566,7 +606,7 @@ wp_spa_id_value_short_name (WpSpaIdValue id)
  * `SPA_TYPE_Object`, @table is set to point to the #WpSpaIdTable that contains
  * the possible Id values / object fields.
  *
- * Returns: the value type associated with @id
+ * Returns: (transfer none): the value type associated with @id
  */
 WpSpaType
 wp_spa_id_value_get_value_type (WpSpaIdValue id, WpSpaIdTable * table)
@@ -603,8 +643,8 @@ wp_spa_id_value_get_value_type (WpSpaIdValue id, WpSpaIdTable * table)
  * `SPA_TYPE_Object`, @table is set to point to the #WpSpaIdTable that contains
  * the possible Id values / object fields.
  *
- * Returns: the type that is allowed in the array, if @id represents
+ * Returns: (transfer none): the type that is allowed in the array, if @id
- *   an object field that takes an array as value
+ *   represents an object field that takes an array as value
  */
 WpSpaType
 wp_spa_id_value_array_get_item_type (WpSpaIdValue id, WpSpaIdTable * table)
@@ -671,7 +711,7 @@ wp_spa_dynamic_type_deinit (void)
  * otherwise guaranteed to be kept in memory until wp_spa_dynamic_type_deinit()
  * is called. No memory copy is done by this function.
  *
- * Returns: the new type
+ * Returns: (transfer none): the new type
  */
 WpSpaType
 wp_spa_dynamic_type_register (const gchar *name, WpSpaType parent,

lib/wp/state.c

@@ -7,7 +7,8 @@
  */
 
 /**
- * SECTION: WpState
+ * SECTION: state
+ * @title: State Storage
  *
  * The #WpState class saves and loads properties from a file
  */

lib/wp/transition.c

@@ -7,7 +7,8 @@
  */
 
 /**
- * SECTION: WpTransition
+ * SECTION: transition
+ * @title: Transitions
  *
  * A transition is an asynchronous operation, like #GTask, that contains
  * an internal state machine, where a series of 'steps' are executed in order