From cd94eff5f212925aa99a98c12f2e14b3173e2f0e Mon Sep 17 00:00:00 2001
From: Pauli Virtanen <pav@iki.fi>
Date: Sat, 2 Oct 2021 22:22:59 +0300
Subject: [PATCH] doc: add Doxygen filter that adds docs to struct *method
 macros

Add an input filter that tries to link e.g.

 #define pw_core_add_listener(...) pw_core_method(c,add_listener,...)

to the corresponding declaration in struct pw_core_methods.
---
 doc/Doxyfile.in       |  2 +-
 doc/input-filter-h.sh | 14 ++++++++++++++
 doc/meson.build       |  1 +
 3 files changed, 16 insertions(+), 1 deletion(-)
 create mode 100755 doc/input-filter-h.sh

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 0164a3c91..a3b156f5c 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -17,7 +17,7 @@ QUIET                  = YES
 WARN_NO_PARAMDOC       = YES
 HAVE_DOT               = @HAVE_DOT@
 INPUT                  = @inputs@
-FILTER_PATTERNS        = "*.c=@c_input_filter@"
+FILTER_PATTERNS        = "*.c=@c_input_filter@" "*.h=@h_input_filter@"
 FILE_PATTERNS          = "*.h" "*.c"
 RECURSIVE              = YES
 EXAMPLE_PATH           = "@top_srcdir@/src/tools" \
diff --git a/doc/input-filter-h.sh b/doc/input-filter-h.sh
new file mode 100755
index 000000000..54b806821
--- /dev/null
+++ b/doc/input-filter-h.sh
@@ -0,0 +1,14 @@
+#!/bin/bash
+#
+# Doxygen input filter, which tries to fix documentation of callback
+# method macros.
+#
+# This is used for .h files.
+#
+
+# Add \sa and \copydoc for (struct *methods) callback macros.
+# #define pw_core_add_listener(...) pw_core_method(c,add_listener,...) -> add \sa and \copydoc
+# #define spa_system_read(...) spa_system_method_r(c,read,...) -> add \sa and \copydoc
+sed -e 's@^\(#define .*[[:space:]]\)\(.*_method\)\((.,[[:space:]]*\)\([a-z_]\+\)\(.*)[[:space:]]*\)$@\1\2\3\4\5 /**< \\copydoc \2s.\4\n\n\\sa \2s.\4 */@;' \
+    -e 's@^\(#define .*[[:space:]]\)\(.*_method\)\(_[rvs](.,[[:space:]]*\)\([a-z_]\+\)\(.*)[[:space:]]*\)$@\1\2\3\4\5 /**< \\copydoc \2s.\4\n\n\\sa \2s.\4 */@;' \
+< "$1"
diff --git a/doc/meson.build b/doc/meson.build
index a0316b6f9..1d469c5a4 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -81,6 +81,7 @@ doxyfile_conf.set('inputs', ' '.join(inputs))
 doxyfile_conf.set('cssfiles', ' '.join(cssfiles))
 doxyfile_conf.set('path_prefixes', ' '.join(path_prefixes))
 doxyfile_conf.set('c_input_filter', meson.source_root() / 'doc' / 'input-filter.sh')
+doxyfile_conf.set('h_input_filter', meson.source_root() / 'doc' / 'input-filter-h.sh')
 
 doxyfile = configure_file(input: 'Doxyfile.in',
                           output: 'Doxyfile',