From f181232a618857e15e2ee9851c31dd1816444f4e Mon Sep 17 00:00:00 2001
From: Peter Hutterer <peter.hutterer@who-t.net>
Date: Thu, 24 Jun 2021 14:06:30 +1000
Subject: [PATCH] doc: add the documentation infrastructure for pipewire
 modules

All empty pages for now but at least this makes them show up in the
documentation.
---
 doc/meson.build                        |  9 ++++++
 doc/pipewire-modules.dox               | 40 ++++++++++++++++++++++++++
 src/modules/meson.build                | 24 ++++++++++++++++
 src/modules/module-access.c            |  3 ++
 src/modules/module-adapter.c           |  2 ++
 src/modules/module-client-device.c     |  3 ++
 src/modules/module-client-node.c       |  3 ++
 src/modules/module-echo-cancel.c       |  3 ++
 src/modules/module-filter-chain.c      |  4 +++
 src/modules/module-link-factory.c      |  3 ++
 src/modules/module-loopback.c          |  3 ++
 src/modules/module-metadata.c          |  3 ++
 src/modules/module-portal.c            |  3 ++
 src/modules/module-profiler.c          |  3 ++
 src/modules/module-protocol-native.c   |  3 ++
 src/modules/module-protocol-pulse.c    |  3 ++
 src/modules/module-protocol-simple.c   |  3 ++
 src/modules/module-pulse-tunnel.c      |  3 ++
 src/modules/module-rt.c                |  3 ++
 src/modules/module-rtkit.c             |  3 ++
 src/modules/module-session-manager.c   |  3 ++
 src/modules/module-zeroconf-discover.c |  3 ++
 22 files changed, 130 insertions(+)
 create mode 100644 doc/pipewire-modules.dox

diff --git a/doc/meson.build b/doc/meson.build
index 603dc353a..0df31ff80 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -17,8 +17,16 @@ endforeach
 foreach h : pipewire_sources
   inputs += meson.source_root() / 'src' / 'pipewire' / h
 endforeach
+foreach h : module_sources
+  inputs += meson.source_root() / 'src' / 'modules' / h
+endforeach
 inputs += meson.source_root() / 'test' / 'pwtest.h'
 
+find = find_program('find', required: false)
+if find.found()
+
+endif
+
 # SPA headers use static inline functions. Doxygen doesn't extract those
 # unless we have EXTRACT_STATIC set - but we don't want it to extract
 # everything in the rest of the tree.
@@ -50,6 +58,7 @@ extra_docs = [
   'pipewire-design.dox',
   'pipewire-daemon.dox',
   'pipewire-library.dox',
+  'pipewire-modules.dox',
   'pipewire-tools.dox',
   'pipewire-session-manager.dox',
   'pipewire-objects-design.dox',
diff --git a/doc/pipewire-modules.dox b/doc/pipewire-modules.dox
new file mode 100644
index 000000000..e51e733a9
--- /dev/null
+++ b/doc/pipewire-modules.dox
@@ -0,0 +1,40 @@
+/**
+
+\page page_pipewire_modules PipeWire Modules
+
+A PipeWire module is effectively a client provided in a `.so` file that
+shares the \ref pw_context with the loading entity. Usually modules are
+loaded when they are listed in the configuration files.
+
+A module's entry point is the `pipewire__module_init` function, see \ref
+PIPEWIRE_SYMBOL_MODULE_INIT.
+
+\code
+int pipewire__module_init(struct pw_impl_module *module, const char *args).`
+\endcode
+
+
+List of known modules:
+
+- \subpage page_module_access
+- \subpage page_module_adapter
+- \subpage page_module_client_device
+- \subpage page_module_client_node
+- \subpage page_module_echo_cancel
+- \subpage page_module_filter_chain
+- \subpage page_module_link_factory
+- \subpage page_module_loopback
+- \subpage page_module_metadata
+- \subpage page_module_portal
+- \subpage page_module_profiler
+- \subpage page_module_protocol_native
+- \subpage page_module_protocol_pulse
+- \subpage page_module_protocol_simple
+- \subpage page_module_pulse_tunnel
+- \subpage page_module_rt
+- \subpage page_module_rtkit
+- \subpage page_module_session_manager
+- \subpage page_module_zeroconf_discover
+
+
+*/
diff --git a/src/modules/meson.build b/src/modules/meson.build
index 9e02b95bf..154723e6c 100644
--- a/src/modules/meson.build
+++ b/src/modules/meson.build
@@ -1,5 +1,29 @@
 subdir('spa')
 
+# The list of "main" source files for modules, the ones that have the
+# doxygen documentation
+module_sources = [
+  'module-access.c',
+  'module-adapter.c',
+  'module-client-device.c',
+  'module-client-node.c',
+  'module-echo-cancel.c',
+  'module-filter-chain.c',
+  'module-link-factory.c',
+  'module-loopback.c',
+  'module-metadata.c',
+  'module-portal.c',
+  'module-profiler.c',
+  'module-protocol-native.c',
+  'module-protocol-pulse.c',
+  'module-protocol-simple.c',
+  'module-pulse-tunnel.c',
+  'module-rt.c',
+  'module-rtkit.c',
+  'module-session-manager.c',
+  'module-zeroconf-discover.c',
+]
+
 pipewire_module_access = shared_library('pipewire-module-access', [ 'module-access.c' ],
   include_directories : [configinc, spa_inc],
   install : true,
diff --git a/src/modules/module-access.c b/src/modules/module-access.c
index 0bd5a39cb..2dc8136ca 100644
--- a/src/modules/module-access.c
+++ b/src/modules/module-access.c
@@ -46,6 +46,9 @@
 #include <pipewire/impl.h>
 #include <pipewire/private.h>
 
+/** \page page_module_access PipeWire Module: Access
+ */
+
 #define NAME "access"
 
 #define MODULE_USAGE	"[ access.force=flatpak ] "		\
diff --git a/src/modules/module-adapter.c b/src/modules/module-adapter.c
index 9cc5691f8..a9e92e003 100644
--- a/src/modules/module-adapter.c
+++ b/src/modules/module-adapter.c
@@ -38,6 +38,8 @@
 #include "modules/spa/spa-node.h"
 #include "module-adapter/adapter.h"
 
+/** \page page_module_adapter PipeWire Module: Adapter
+ */
 #define NAME "adapter"
 
 #define FACTORY_USAGE	SPA_KEY_FACTORY_NAME"=<factory-name> " \
diff --git a/src/modules/module-client-device.c b/src/modules/module-client-device.c
index ec122949e..378e5715c 100644
--- a/src/modules/module-client-device.c
+++ b/src/modules/module-client-device.c
@@ -37,6 +37,9 @@
 
 #define NAME "client-device"
 
+/** \page page_module_client_device PipeWire Module: Client Device
+ */
+
 static const struct spa_dict_item module_props[] = {
 	{ PW_KEY_MODULE_AUTHOR, "Wim Taymans <wim.taymans@gmail.com>" },
 	{ PW_KEY_MODULE_DESCRIPTION, "Allow clients to create and control remote devices" },
diff --git a/src/modules/module-client-node.c b/src/modules/module-client-node.c
index 471a1c814..2a481e4f1 100644
--- a/src/modules/module-client-node.c
+++ b/src/modules/module-client-node.c
@@ -36,6 +36,9 @@
 #include "module-client-node/v0/client-node.h"
 #include "module-client-node/client-node.h"
 
+/** \page page_module_client_node PipeWire Module: Client Node
+ */
+
 #define NAME "client-node"
 
 static const struct spa_dict_item module_props[] = {
diff --git a/src/modules/module-echo-cancel.c b/src/modules/module-echo-cancel.c
index 980e5c7bc..6c1801644 100644
--- a/src/modules/module-echo-cancel.c
+++ b/src/modules/module-echo-cancel.c
@@ -56,6 +56,9 @@
 
 #include "module-echo-cancel/echo-cancel.h"
 
+/** \page page_module_echo_cancel PipeWire Module: Echo Cancel
+ */
+
 #define NAME "echo-cancel"
 /* Hopefully this is enough for any combination of AEC engine and resampler
  * input requirement for rate matching */
diff --git a/src/modules/module-filter-chain.c b/src/modules/module-filter-chain.c
index 45e0b2898..3803a71a2 100644
--- a/src/modules/module-filter-chain.c
+++ b/src/modules/module-filter-chain.c
@@ -48,6 +48,10 @@
 
 #define NAME "filter-chain"
 
+/**
+ * \page page_module_filter_chain PipeWire Module: Filter-Chain
+ *
+ */
 static const struct spa_dict_item module_props[] = {
 	{ PW_KEY_MODULE_AUTHOR, "Wim Taymans <wim.taymans@gmail.com>" },
 	{ PW_KEY_MODULE_DESCRIPTION, "Create filter chain streams" },
diff --git a/src/modules/module-link-factory.c b/src/modules/module-link-factory.c
index f1619c66b..a6f47bdd6 100644
--- a/src/modules/module-link-factory.c
+++ b/src/modules/module-link-factory.c
@@ -34,6 +34,9 @@
 
 #include <pipewire/impl.h>
 
+/** \page page_module_link_factory PipeWire Module: Link Factory
+ */
+
 #define NAME "link-factory"
 
 #define FACTORY_USAGE	PW_KEY_LINK_OUTPUT_NODE"=<output-node> "	\
diff --git a/src/modules/module-loopback.c b/src/modules/module-loopback.c
index 19011bf0d..d379398df 100644
--- a/src/modules/module-loopback.c
+++ b/src/modules/module-loopback.c
@@ -42,6 +42,9 @@
 #include <pipewire/impl.h>
 #include <pipewire/extensions/profiler.h>
 
+/** \page page_module_loopback PipeWire Module: Loopback
+ */
+
 #define NAME "loopback"
 
 static const struct spa_dict_item module_props[] = {
diff --git a/src/modules/module-metadata.c b/src/modules/module-metadata.c
index c529cdd00..b431e71f8 100644
--- a/src/modules/module-metadata.c
+++ b/src/modules/module-metadata.c
@@ -34,6 +34,9 @@
 #include <pipewire/impl.h>
 #include <pipewire/extensions/metadata.h>
 
+/** \page page_module_metadata PipeWire Module: Metadata
+ */
+
 #define NAME "metadata"
 
 static const struct spa_dict_item module_props[] = {
diff --git a/src/modules/module-portal.c b/src/modules/module-portal.c
index db742f5b1..83649f6d6 100644
--- a/src/modules/module-portal.c
+++ b/src/modules/module-portal.c
@@ -45,6 +45,9 @@
 #include "pipewire/utils.h"
 #include "pipewire/private.h"
 
+/** \page page_module_portal PipeWire Module: Portal
+ */
+
 #define NAME "portal"
 
 struct impl {
diff --git a/src/modules/module-profiler.c b/src/modules/module-profiler.c
index 8ca0850c8..188f15ecf 100644
--- a/src/modules/module-profiler.c
+++ b/src/modules/module-profiler.c
@@ -41,6 +41,9 @@
 #include <pipewire/impl.h>
 #include <pipewire/extensions/profiler.h>
 
+/** \page page_module_profiler PipeWire Module: Profiler
+ */
+
 #define NAME "profiler"
 
 #define TMP_BUFFER		(16 * 1024)
diff --git a/src/modules/module-protocol-native.c b/src/modules/module-protocol-native.c
index 0dbace733..5aa88b852 100644
--- a/src/modules/module-protocol-native.c
+++ b/src/modules/module-protocol-native.c
@@ -64,6 +64,9 @@
 #include <spa/debug/pod.h>
 #include <spa/debug/types.h>
 
+/** \page page_module_protocol_native PipeWire Module: Protocol Native
+ */
+
 #define NAME "protocol-native"
 
 #ifndef UNIX_PATH_MAX
diff --git a/src/modules/module-protocol-pulse.c b/src/modules/module-protocol-pulse.c
index 189960c2f..55ed4c4ad 100644
--- a/src/modules/module-protocol-pulse.c
+++ b/src/modules/module-protocol-pulse.c
@@ -38,6 +38,9 @@
 
 #include "module-protocol-pulse/pulse-server.h"
 
+/** \page page_module_protocol_pulse PipeWire Module: Protocol Pulse
+ */
+
 #define NAME "protocol-pulse"
 
 #define MODULE_USAGE	PW_PROTOCOL_PULSE_USAGE
diff --git a/src/modules/module-protocol-simple.c b/src/modules/module-protocol-simple.c
index d4f059bf7..38ba69541 100644
--- a/src/modules/module-protocol-simple.c
+++ b/src/modules/module-protocol-simple.c
@@ -49,6 +49,9 @@
 
 #include <pipewire/impl.h>
 
+/** \page page_module_protocol_simple PipeWire Module: Protocol Simple
+ */
+
 #define NAME "protocol-simple"
 
 #define DEFAULT_PORT 4711
diff --git a/src/modules/module-pulse-tunnel.c b/src/modules/module-pulse-tunnel.c
index 1998b5718..1247b2ef2 100644
--- a/src/modules/module-pulse-tunnel.c
+++ b/src/modules/module-pulse-tunnel.c
@@ -51,6 +51,9 @@
 
 #include <pulse/pulseaudio.h>
 
+/** \page page_module_pulse_tunnel PipeWire Module: Pulse Tunnel
+ */
+
 #define NAME "pulse-tunnel"
 
 #define MODULE_USAGE	"[ remote.name=<remote> ] "				\
diff --git a/src/modules/module-rt.c b/src/modules/module-rt.c
index 8e9add101..c866abdb7 100644
--- a/src/modules/module-rt.c
+++ b/src/modules/module-rt.c
@@ -38,6 +38,9 @@
 
 #include "config.h"
 
+/** \page page_module_rt PipeWire Module: RT
+ */
+
 #define DEFAULT_NICE_LEVEL -11
 #define DEFAULT_RT_PRIO 88
 #define DEFAULT_RT_TIME_SOFT 200000
diff --git a/src/modules/module-rtkit.c b/src/modules/module-rtkit.c
index 93f1178e5..1ebdb698f 100644
--- a/src/modules/module-rtkit.c
+++ b/src/modules/module-rtkit.c
@@ -45,6 +45,9 @@
 
 #include <pipewire/impl.h>
 
+/** \page page_module_rtkit PipeWire Module: RTKit
+ */
+
 #define DEFAULT_NICE_LEVEL	-11
 #define DEFAULT_RT_PRIO		88
 #define DEFAULT_RT_TIME_SOFT	200000
diff --git a/src/modules/module-session-manager.c b/src/modules/module-session-manager.c
index f9f8c983f..982285368 100644
--- a/src/modules/module-session-manager.c
+++ b/src/modules/module-session-manager.c
@@ -27,6 +27,9 @@
 
 #include <pipewire/impl.h>
 
+/** \page page_module_session_manager PipeWire Module: Session Manager
+ */
+
 /* client-endpoint.c */
 int client_endpoint_factory_init(struct pw_impl_module *module);
 /* client-session.c */
diff --git a/src/modules/module-zeroconf-discover.c b/src/modules/module-zeroconf-discover.c
index 3aeccaa57..5cb4e814d 100644
--- a/src/modules/module-zeroconf-discover.c
+++ b/src/modules/module-zeroconf-discover.c
@@ -46,6 +46,9 @@
 
 #include "module-zeroconf-discover/avahi-poll.h"
 
+/** \page page_module_zeroconf_discover PipeWire Module: Zeroconf Discover
+ */
+
 #define NAME "zeroconf-discover"
 
 #define MODULE_USAGE	" "