From 73e7f61d8cd5d757f9d814a540ab2610d0dc7815 Mon Sep 17 00:00:00 2001
From: Wim Taymans <wtaymans@redhat.com>
Date: Tue, 28 Jan 2025 10:11:24 +0100
Subject: [PATCH] modules: add more docs

---
 src/modules/module-client-device.c | 53 ++++++++++++++++++++++++++++++
 src/modules/module-client-node.c   | 14 ++++----
 2 files changed, 60 insertions(+), 7 deletions(-)

diff --git a/src/modules/module-client-device.c b/src/modules/module-client-device.c
index e2450e81b..84b8456b2 100644
--- a/src/modules/module-client-device.c
+++ b/src/modules/module-client-device.c
@@ -16,10 +16,63 @@
 #include "module-client-device/client-device.h"
 
 /** \page page_module_client_device Client Device
+ *
+ * Allow clients to export devices to the PipeWire daemon.
+ *
+ * This module creates an export type for the \ref SPA_TYPE_INTERFACE_Device
+ * interface.
+ *
+ * With \ref pw_core_export(), objects of this type can be exported to the
+ * PipeWire server. All actions performed on the device locally will be visible
+ * to connecteced clients.
+ *
+ * In some cases, it is possible to use this factory directly.
+ * With \ref pw_core_create_object() on the `client-device`
+ * factory will result in a \ref SPA_TYPE_INTERFACE_Device proxy that can be
+ * used to control the server side created \ref pw_impl_device.
+ *
+ * Schematically, the client side \ref spa_device is wrapped in the ClientDevice
+ * proxy and unwrapped by the server side resource so that all actions on the client
+ * side device are reflected on the server side device and server side actions are
+ * reflected in the client.
+ *
+ *\code{.unparsed}
+ *
+ *   client side proxy                            server side resource
+ * .------------------------------.            .----------------------------------.
+ * | SPA_TYPE_INTERFACE_Device    |            |  PW_TYPE_INTERFACE_Device        |
+ * |                              |  IPC       |.--------------------------------.|
+ * |                              | ----->     || SPA_TYPE_INTERFACE_Device      ||
+ * |                              |            |'--------------------------------'|
+ * '------------------------------'            '----------------------------------'
+ *\endcode
  *
  * ## Module Name
  *
  * `libpipewire-module-client-device`
+ *
+ * ## Module Options
+ *
+ * This module has no options.
+ *
+ * ## Properties for the create_object call
+ *
+ * All properties are passed directly to the \ref pw_context_create_device() call.
+ *
+ * ## Example configuration
+ *
+ * The module is usually added to the config file of the main PipeWire daemon and the
+ * clients.
+ *
+ *\code{.unparsed}
+ * context.modules = [
+ * { name = libpipewire-module-client-device }
+ * ]
+ *\endcode
+ *
+ * ## See also
+ *
+ * - `module-spa-device-factory`: make nodes from a factory
  */
 
 #define NAME "client-device"
diff --git a/src/modules/module-client-node.c b/src/modules/module-client-node.c
index fa43b1cd0..dc978084d 100644
--- a/src/modules/module-client-node.c
+++ b/src/modules/module-client-node.c
@@ -21,21 +21,21 @@
  *
  * Allow clients to export processing nodes to the PipeWire daemon.
  *
- * This module creates 2 export types, one for the PW_TYPE_INTERFACE_Node and
- * another for the SPA_TYPE_INTERFACE_Node interfaces.
+ * This module creates 2 export types, one for the \ref PW_TYPE_INTERFACE_Node and
+ * another for the \ref SPA_TYPE_INTERFACE_Node interfaces.
  *
  * With \ref pw_core_export(), objects of these types can be exported to the
  * PipeWire server. All actions performed on the node locally will be visible
  * to connecteced clients and scheduling of the Node will be performed.
  *
- * Objects of the PW_TYPE_INTERFACE_Node interface can be made with
+ * Objects of the \ref PW_TYPE_INTERFACE_Node interface can be made with
  * \ref pw_context_create_node(), for example. You would manually need to create
- * and add an object of the SPA_TYPE_INTERFACE_Node interface. Exporting a
- * SPA_TYPE_INTERFACE_Node directly will first wrap it in a PW_TYPE_INTERFACE_Node
- * interface.
+ * and add an object of the \ref SPA_TYPE_INTERFACE_Node interface. Exporting a
+ * \ref SPA_TYPE_INTERFACE_Node directly will first wrap it in a
+ * \ref PW_TYPE_INTERFACE_Node interface.
  *
  * Usually this module is not used directly but through the \ref pw_stream and
- * \ref pw_filter APIs, which provides API to implement the SPA_TYPE_INTERFACE_Node
+ * \ref pw_filter APIs, which provides API to implement the \ref SPA_TYPE_INTERFACE_Node
  * interface.
  *
  * In some cases, it is possible to use this factory directly (the PipeWire JACK