modules: add some more docs

src/modules/module-client-node.c

@@ -18,10 +18,77 @@
 #include "module-client-node/client-node.h"
 
 /** \page page_module_client_node Client Node
+ *
+ * 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.
+ *
+ * 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
+ * \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.
+ *
+ * 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
+ * interface.
+ *
+ * In some cases, it is possible to use this factory directly (the PipeWire JACK
+ * implementation does this). With \ref pw_core_create_object() on the `client-node`
+ * factory will result in a \ref PW_TYPE_INTERFACE_ClientNode proxy that can be
+ * used to control the server side created \ref pw_impl_node.
+ *
+ * Schematically, the client side \ref pw_impl_node is wrapped in the ClientNode
+ * proxy and unwrapped by the server side resource so that all actions on the client
+ * side node are reflected on the server side node and server side actions are
+ * reflected in the client.
+ *
+ *\code{.unparsed}
+ *
+ *   client side proxy                            server side resource
+ * .------------------------------.            .----------------------------------.
+ * | PW_TYPE_INTERFACE_ClientNode |            |  PW_TYPE_INTERFACE_Node          |
+ * |.----------------------------.|  IPC       |.--------------------------------.|
+ * || PW_TYPE_INTERFACE_Node     || ----->     || SPA_TYPE_INTERFACE_Node        ||
+ * ||.--------------------------.||            ||.------------------------------.||
+ * ||| SPA_TYPE_INTERFACE_Node  |||            ||| PW_TYPE_INTERFACE_ClientNode |||
+ * |||                          |||            |||                              |||
+ * ||'--------------------------'||            ||'------------------------------'||
+ * |'----------------------------'|            |'--------------------------------'|
+ * '------------------------------'            '----------------------------------'
+ *\endcode
  *
  * ## Module Name
  *
  * `libpipewire-module-client-node`
+ *
+ * ## Module Options
+ *
+ * This module has no options.
+ *
+ * ## Properties for the create_object call
+ *
+ * All properties are passed directly to the \ref pw_context_create_node() 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-node }
+ * ]
+ *\endcode
+ *
+ * ## See also
+ *
+ * - `module-spa-node-factory`: make nodes from a factory
  */
 
 #define NAME "client-node"

src/modules/module-metadata.c

@@ -18,21 +18,22 @@
 
 /** \page page_module_metadata Metadata
  *
- * Allows clients to create a metadata store.
+ * Allows clients to export a metadata store to the PipeWire server.
  *
- * Both the client and the server need to load this module for the metadata to be
- * useful.
+ * Both the client and the server need to load this module for the metadata
+ * to be exported.
  *
  * This module creates a new factory and a new export type for the
  * \ref PW_TYPE_INTERFACE_Metadata interface.
  *
  * A client will first create an implementation of the PW_TYPE_INTERFACE_Metadata
  * interface with \ref pw_context_create_metadata(), for example. With the
- * \ref pw_core_export(), this module will create a server size resource to expose
+ * \ref pw_core_export(), this module will create a server side resource to expose
  * the metadata implementation to other clients. Modifications done by the client
  * on the local metadata interface will be visible to all PipeWire clients.
  *
- * It is also possible to create metadata in the config file.
+ * It is also possible to use the factory to create metadata in the current
+ * processes using a config file fragment.
  *
  * As an argument to the create_object call, a set of properties will
  * control the name of the metadata and some initial values.
@@ -72,7 +73,7 @@
  *
  *\code{.unparsed}
  * context.modules = [
- * { name = libpipewire-metadata }
+ * { name = libpipewire-module-metadata }
  * ]
  *\endcode