wireplumber: improve docs

4 files changed, 139 insertions, 23 deletions

diff --git a/lib/wireplumber/src/audio.c b/lib/wireplumber/src/audio.c
index 15582d7..69683f5 100644
--- a/lib/wireplumber/src/audio.c
+++ b/lib/wireplumber/src/audio.c
@@ -51,6 +51,15 @@ static GParamSpec *astal_wp_audio_properties[ASTAL_WP_AUDIO_N_PROPERTIES] = {
 };
 
 /**
+ *  AstalWpAudio
+ *
+ *  is instanciated by [[email protected]]. An instance of class can only be received there.
+ *
+ *  This is a convinience class and acts as a filter for [[email protected]] to filter for audio
+ * endpoints and devices.
+ */
+
+/**
  * astal_wp_audio_get_speaker:
  * @self: the AstalWpAudio object
  * @id: the id of the endpoint
diff --git a/lib/wireplumber/src/endpoint.c b/lib/wireplumber/src/endpoint.c
index 13979d1..8d5411d 100644
--- a/lib/wireplumber/src/endpoint.c
+++ b/lib/wireplumber/src/endpoint.c
@@ -214,10 +214,28 @@ gboolean astal_wp_endpoint_get_mute(AstalWpEndpoint *self) { return self->mute;
  */
 gdouble astal_wp_endpoint_get_volume(AstalWpEndpoint *self) { return self->volume; }
 
+/**
+ * astal_wp_endpoint_get_description:
+ * @self: the AstalWpEndpoint instance.
+ *
+ * gets the description of this endpoint
+ */
 const gchar *astal_wp_endpoint_get_description(AstalWpEndpoint *self) { return self->description; }
 
+/**
+ * astal_wp_endpoint_get_name:
+ * @self: the AstalWpEndpoint instance.
+ *
+ * gets the name of this endpoint
+ */
 const gchar *astal_wp_endpoint_get_name(AstalWpEndpoint *self) { return self->name; }
 
+/**
+ * astal_wp_endpoint_get_icon:
+ * @self: the AstalWpEndpoint instance.
+ *
+ * gets the icon for this endpoint
+ */
 const gchar *astal_wp_endpoint_get_icon(AstalWpEndpoint *self) { return self->icon; }
 
 gboolean astal_wp_endpoint_get_is_default(AstalWpEndpoint *self) { return self->is_default; }
@@ -521,19 +539,54 @@ static void astal_wp_endpoint_class_init(AstalWpEndpointClass *class) {
     object_class->finalize = astal_wp_endpoint_finalize;
     object_class->get_property = astal_wp_endpoint_get_property;
     object_class->set_property = astal_wp_endpoint_set_property;
-
+    /**
+     * AstalWpEndpoint:id:
+     *
+     * The pipewire id of this endpoint.
+     */
     astal_wp_endpoint_properties[ASTAL_WP_ENDPOINT_PROP_ID] =
         g_param_spec_uint("id", "id", "id", 0, UINT_MAX, 0, G_PARAM_READABLE);
+    /**
+     * AstalWpEndpoint:volume:
+     *
+     * The volume of this endpoint
+     */
     astal_wp_endpoint_properties[ASTAL_WP_ENDPOINT_PROP_VOLUME] =
         g_param_spec_double("volume", "volume", "volume", 0, G_MAXFLOAT, 0, G_PARAM_READWRITE);
+    /**
+     * AstalWpEndpoint:mute:
+     *
+     * The mute state of this endpoint
+     */
     astal_wp_endpoint_properties[ASTAL_WP_ENDPOINT_PROP_MUTE] =
         g_param_spec_boolean("mute", "mute", "mute", TRUE, G_PARAM_READWRITE);
+    /**
+     * AstalWpEndpoint:description:
+     *
+     * The description of this endpoint
+     */
     astal_wp_endpoint_properties[ASTAL_WP_ENDPOINT_PROP_DESCRIPTION] =
         g_param_spec_string("description", "description", "description", NULL, G_PARAM_READABLE);
+    /**
+     * AstalWpEndpoint:name:
+     *
+     * The name of this endpoint
+     */
     astal_wp_endpoint_properties[ASTAL_WP_ENDPOINT_PROP_NAME] =
         g_param_spec_string("name", "name", "name", NULL, G_PARAM_READABLE);
+    /**
+     * AstalWpEndpoint:icon:
+     *
+     * The icon of this endpoint. Note that endpoints do not have icons associated with them in
+     * pipewire, so the icon of the associated device is used instead.
+     */
     astal_wp_endpoint_properties[ASTAL_WP_ENDPOINT_PROP_ICON] = g_param_spec_string(
         "icon", "icon", "icon", "audio-card-symbolic", G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY);
+    /**
+     * AstalWpEndpoint:volume-icon:
+     *
+     * The volume icon of this endpoint
+     */
     astal_wp_endpoint_properties[ASTAL_WP_ENDPOINT_PROP_VOLUME_ICON] = g_param_spec_string(
         "volume-icon", "volume-icon", "volume-icon", "audio-volume-muted", G_PARAM_READABLE);
     /**
@@ -544,10 +597,21 @@ static void astal_wp_endpoint_class_init(AstalWpEndpointClass *class) {
     astal_wp_endpoint_properties[ASTAL_WP_ENDPOINT_PROP_MEDIA_CLASS] =
         g_param_spec_enum("media-class", "media-class", "media-class", ASTAL_WP_TYPE_MEDIA_CLASS, 1,
                           G_PARAM_READABLE);
+    /**
+     * AstalWpEndpoint:is-default:
+     *
+     * Whether this endpoint is the default one used for this media-class. Note that setting this
+     * property to false has no effect.
+     */
     astal_wp_endpoint_properties[ASTAL_WP_ENDPOINT_PROP_DEFAULT] =
-        g_param_spec_boolean("is_default", "is_default", "is_default", FALSE, G_PARAM_READWRITE);
+        g_param_spec_boolean("is-default", "is-default", "is-default", FALSE, G_PARAM_READWRITE);
+    /**
+     * AstalWpEndpoint:lock-channels:
+     *
+     * Whether to lock the channels together or not.
+     */
     astal_wp_endpoint_properties[ASTAL_WP_ENDPOINT_PROP_LOCK_CHANNELS] = g_param_spec_boolean(
-        "lock_channels", "lock_channels", "lock channels", FALSE, G_PARAM_READWRITE);
+        "lock-channels", "lock-channels", "lock channels", FALSE, G_PARAM_READWRITE);
 
     g_object_class_install_properties(object_class, ASTAL_WP_ENDPOINT_N_PROPERTIES,
                                       astal_wp_endpoint_properties);
diff --git a/lib/wireplumber/src/video.c b/lib/wireplumber/src/video.c
index 00cdd82..175a007 100644
--- a/lib/wireplumber/src/video.c
+++ b/lib/wireplumber/src/video.c
@@ -48,13 +48,24 @@ static GParamSpec *astal_wp_video_properties[ASTAL_WP_VIDEO_N_PROPERTIES] = {
 };
 
 /**
+ *  AstalWpVideo
+ *
+ *  is instanciated by [[email protected]]. An instance of class can only be received there.
+ *
+ *  This is a convinience class and acts as a filter for [[email protected]] to filter for video
+ * endpoints and devices.
+ */
+
+/**
  * astal_wp_video_get_source:
  * @self: the AstalWpVideo object
  * @id: the id of the endpoint
  *
+ * the source with the given id
+ *
  * Returns: (transfer none) (nullable): the source with the given id
  */
-AstalWpEndpoint *astal_wp_video_get_speaker(AstalWpVideo *self, guint id) {
+AstalWpEndpoint *astal_wp_video_get_source(AstalWpVideo *self, guint id) {
     AstalWpVideoPrivate *priv = astal_wp_video_get_instance_private(self);
 
     AstalWpEndpoint *endpoint = astal_wp_wp_get_endpoint(priv->wp, id);
@@ -68,6 +79,8 @@ AstalWpEndpoint *astal_wp_video_get_speaker(AstalWpVideo *self, guint id) {
  * @self: the AstalWpVideo object
  * @id: the id of the endpoint
  *
+ * the sink with the given id
+ *
  * Returns: (transfer none) (nullable): the sink with the given id
  */
 AstalWpEndpoint *astal_wp_video_get_sink(AstalWpVideo *self, guint id) {
@@ -84,6 +97,8 @@ AstalWpEndpoint *astal_wp_video_get_sink(AstalWpVideo *self, guint id) {
  * @self: the AstalWpVideo object
  * @id: the id of the endpoint
  *
+ * the stream with the given id
+ *
  * Returns: (transfer none) (nullable): the stream with the given id
  */
 AstalWpEndpoint *astal_wp_video_get_stream(AstalWpVideo *self, guint id) {
@@ -100,6 +115,8 @@ AstalWpEndpoint *astal_wp_video_get_stream(AstalWpVideo *self, guint id) {
  * @self: the AstalWpVideo object
  * @id: the id of the endpoint
  *
+ * the recorder with the given id
+ *
  * Returns: (transfer none) (nullable): the recorder with the given id
  */
 AstalWpEndpoint *astal_wp_video_get_recorder(AstalWpVideo *self, guint id) {
@@ -116,6 +133,8 @@ AstalWpEndpoint *astal_wp_video_get_recorder(AstalWpVideo *self, guint id) {
  * @self: the AstalWpVideo object
  * @id: the id of the device
  *
+ * the device with the given id
+ *
  * Returns: (transfer none) (nullable): the device with the given id
  */
 AstalWpDevice *astal_wp_video_get_device(AstalWpVideo *self, guint id) {
@@ -130,6 +149,8 @@ AstalWpDevice *astal_wp_video_get_device(AstalWpVideo *self, guint id) {
  * astal_wp_video_get_sources:
  * @self: the AstalWpVideo object
  *
+ * a list containing the video sources
+ *
  * Returns: (transfer container) (nullable) (type GList(AstalWpEndpoint)): a GList containing the
  * video sources
  */
@@ -151,6 +172,8 @@ GList *astal_wp_video_get_sources(AstalWpVideo *self) {
  * astal_wp_video_get_sinks
  * @self: the AstalWpVideo object
  *
+ * a list containing the video sinks
+ *
  * Returns: (transfer container) (nullable) (type GList(AstalWpEndpoint)): a GList containing the
  * video sinks
  */
@@ -172,6 +195,8 @@ GList *astal_wp_video_get_sinks(AstalWpVideo *self) {
  * astal_wp_video_get_recorders:
  * @self: the AstalWpVideo object
  *
+ * a list containing the video recorders
+ *
  * Returns: (transfer container) (nullable) (type GList(AstalWpEndpoint)): a GList containing the
  * video recorders
  */
@@ -193,6 +218,8 @@ GList *astal_wp_video_get_recorders(AstalWpVideo *self) {
  * astal_wp_video_get_streams:
  * @self: the AstalWpVideo object
  *
+ * a list containing the video streams
+ *
  * Returns: (transfer container) (nullable) (type GList(AstalWpEndpoint)): a GList containing the
  * video streams
  */
@@ -214,7 +241,9 @@ GList *astal_wp_video_get_streams(AstalWpVideo *self) {
  * astal_wp_video_get_devices:
  * @self: the AstalWpAudio object
  *
- * Returns: (transfer container) (nullable) (type GList(AstalWpVideo)): a GList containing the
+ * a list containing the devices
+ *
+ * Returns: (transfer container) (nullable) (type GList(AstalWpDevice)): a GList containing the
  * devices
  */
 GList *astal_wp_video_get_devices(AstalWpVideo *self) {
diff --git a/lib/wireplumber/src/wireplumber.c b/lib/wireplumber/src/wireplumber.c
index f1fa516..cc3aa82 100644
--- a/lib/wireplumber/src/wireplumber.c
+++ b/lib/wireplumber/src/wireplumber.c
@@ -66,10 +66,20 @@ static GParamSpec *astal_wp_wp_properties[ASTAL_WP_WP_N_PROPERTIES] = {
 };
 
 /**
+ * AstalWpWp
+ *
+ * manages the connection to wireplumber. Usually you don't want to use this class directly, but use
+ * the [[email protected]] or [[email protected]] instead.
+ *
+ */
+
+/**
  * astal_wp_wp_get_endpoint:
  * @self: the AstalWpWp object
  * @id: the id of the endpoint
  *
+ * the endpoint with the given id
+ *
  * Returns: (transfer none) (nullable): the endpoint with the given id
  */
 AstalWpEndpoint *astal_wp_wp_get_endpoint(AstalWpWp *self, guint id) {
@@ -83,6 +93,8 @@ AstalWpEndpoint *astal_wp_wp_get_endpoint(AstalWpWp *self, guint id) {
  * astal_wp_wp_get_endpoints:
  * @self: the AstalWpWp object
  *
+ * a GList containing all endpoints
+ *
  * Returns: (transfer container) (nullable) (type GList(AstalWpEndpoint)): a GList containing the
  * endpoints
  */
@@ -96,6 +108,8 @@ GList *astal_wp_wp_get_endpoints(AstalWpWp *self) {
  * @self: the AstalWpWp object
  * @id: the id of the device
  *
+ * the device with the given id
+ *
  * Returns: (transfer none) (nullable): the device with the given id
  */
 AstalWpDevice *astal_wp_wp_get_device(AstalWpWp *self, guint id) {
@@ -109,6 +123,8 @@ AstalWpDevice *astal_wp_wp_get_device(AstalWpWp *self, guint id) {
  * astal_wp_wp_get_devices:
  * @self: the AstalWpWp object
  *
+ * the GList containing the devices
+ *
  * Returns: (transfer container) (nullable) (type GList(AstalWpDevice)): a GList containing the
  * devices
  */
@@ -120,6 +136,8 @@ GList *astal_wp_wp_get_devices(AstalWpWp *self) {
 /**
  * astal_wp_wp_get_audio
  *
+ * gets the [[email protected]] object
+ *
  * Returns: (nullable) (transfer none): gets the audio object
  */
 AstalWpAudio *astal_wp_wp_get_audio(AstalWpWp *self) { return self->audio; }
@@ -127,6 +145,8 @@ AstalWpAudio *astal_wp_wp_get_audio(AstalWpWp *self) { return self->audio; }
 /**
  * astal_wp_wp_get_video
  *
+ * gets the video object
+ *
  * Returns: (nullable) (transfer none): gets the video object
  */
 AstalWpVideo *astal_wp_wp_get_video(AstalWpWp *self) { return self->video; }
@@ -134,6 +154,8 @@ AstalWpVideo *astal_wp_wp_get_video(AstalWpWp *self) { return self->video; }
 /**
  * astal_wp_wp_get_default_speaker
  *
+ * gets the default speaker object
+ *
  * Returns: (nullable) (transfer none): gets the default speaker object
  */
 AstalWpEndpoint *astal_wp_wp_get_default_speaker(AstalWpWp *self) { return self->default_speaker; }
@@ -141,6 +163,8 @@ AstalWpEndpoint *astal_wp_wp_get_default_speaker(AstalWpWp *self) { return self-
 /**
  * astal_wp_wp_get_default_microphone
  *
+ * gets the default microphone object
+ *
  * Returns: (nullable) (transfer none): gets the default microphone object
  */
 AstalWpEndpoint *astal_wp_wp_get_default_microphone(AstalWpWp *self) {
@@ -218,20 +242,6 @@ static void astal_wp_wp_set_property(GObject *object, guint property_id, const G
 }
 
 static void astal_wp_wp_object_added(AstalWpWp *self, gpointer object) {
-    // print pipewire properties
-    // WpIterator *iter = wp_pipewire_object_new_properties_iterator(WP_PIPEWIRE_OBJECT(object));
-    // GValue item = G_VALUE_INIT;
-    // const gchar *key, *value;
-    //
-    // g_print("\n\n");
-    // while (wp_iterator_next (iter, &item)) {
-    //     WpPropertiesItem *pi = g_value_get_boxed (&item);
-    //     key = wp_properties_item_get_key (pi);
-    //     value = wp_properties_item_get_value (pi);
-    //     g_print("%s: %s\n", key, value);
-    //     g_value_unset(&item);
-    // }
-
     AstalWpWpPrivate *priv = astal_wp_wp_get_instance_private(self);
 
     if (WP_IS_NODE(object)) {
@@ -329,6 +339,8 @@ static void astal_wp_wp_plugin_loaded(WpObject *obj, GAsyncResult *result, Astal
 /**
  * astal_wp_wp_get_default
  *
+ * gets the default wireplumber object.
+ *
  * Returns: (nullable) (transfer none): gets the default wireplumber object.
  */
 AstalWpWp *astal_wp_wp_get_default() {
@@ -342,6 +354,8 @@ AstalWpWp *astal_wp_wp_get_default() {
 /**
  * astal_wp_get_default_wp
  *
+ * gets the default wireplumber object.
+ *
  * Returns: (nullable) (transfer none): gets the default wireplumber object.
  */
 AstalWpWp *astal_wp_get_default_wp() { return astal_wp_wp_get_default(); }
@@ -457,21 +471,21 @@ static void astal_wp_wp_class_init(AstalWpWpClass *class) {
     /**
      * AstalWpWp:endpoints: (type GList(AstalWpEndpoint)) (transfer container)
      *
-     * A list of AstalWpEndpoint objects
+     * A list of [[email protected]] objects
      */
     astal_wp_wp_properties[ASTAL_WP_WP_PROP_ENDPOINTS] =
         g_param_spec_pointer("endpoints", "endpoints", "endpoints", G_PARAM_READABLE);
     /**
      * AstalWpWp:devices: (type GList(AstalWpDevice)) (transfer container)
      *
-     * A list of AstalWpDevice objects
+     * A list of [[email protected]] objects
      */
     astal_wp_wp_properties[ASTAL_WP_WP_PROP_DEVICES] =
         g_param_spec_pointer("devices", "devices", "devices", G_PARAM_READABLE);
     /**
      * AstalWpWp:default-speaker:
      *
-     * The AstalWndpoint object representing the default speaker
+     * The [[email protected]] representing the default speaker
      */
     astal_wp_wp_properties[ASTAL_WP_WP_PROP_DEFAULT_SPEAKER] =
         g_param_spec_object("default-speaker", "default-speaker", "default-speaker",
@@ -479,7 +493,7 @@ static void astal_wp_wp_class_init(AstalWpWpClass *class) {
     /**
      * AstalWpWp:default-microphone:
      *
-     * The AstalWndpoint object representing the default speaker
+     * The [[email protected]] representing the default speaker
      */
     astal_wp_wp_properties[ASTAL_WP_WP_PROP_DEFAULT_MICROPHONE] =
         g_param_spec_object("default-microphone", "default-microphone", "default-microphone",