From aecb406a962933b49aa8e8a2eb1092c23abcda29 Mon Sep 17 00:00:00 2001
From: Wim Taymans <wtaymans@redhat.com>
Date: Mon, 27 Jan 2025 15:24:42 +0100
Subject: [PATCH] modules: document link-factory context.objects

---
 src/modules/module-link-factory.c | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/src/modules/module-link-factory.c b/src/modules/module-link-factory.c
index 5b02b4aba..6eef97f71 100644
--- a/src/modules/module-link-factory.c
+++ b/src/modules/module-link-factory.c
@@ -20,7 +20,8 @@
  *
  * This module creates a new factory. Clients that can see the factory
  * can use the factory name (`link-factory`) to create new link
- * objects with \ref pw_core_create_object().
+ * objects with \ref pw_core_create_object(). It is also possible to create
+ * objects in the config file.
  *
  * Object of the \ref PW_TYPE_INTERFACE_Link will be created and a proxy
  * to it will be returned.
@@ -90,6 +91,26 @@
  * }
  *\endcode
  *
+ * ## Config objects
+ *
+ * To create an object from the factory, one can use the \ref pw_core_create_object()
+ * method or make an object in the `context.objects` section like:
+ *
+ *\code{.unparsed}
+ * context.objects = [
+ * { factory = link-factory
+ *     args = {
+ *         link.output.node = system
+ *         link.output.port = capture_2
+ *         link.input.node  = my-mic
+ *         link.input.port  = input_FR
+ *     }
+ * }
+ *\endcode
+ *
+ * Note that this only works when the ports that need to be linked are available
+ * at the time the config file is parsed.
+ *
  * ## See also
  *
  * - `pw-link`: a tool to manage port links