From 851a64d8c84f6ee3558bf3376e04490facdea69e Mon Sep 17 00:00:00 2001
From: Peter Hutterer <peter.hutterer@who-t.net>
Date: Fri, 21 May 2021 13:53:19 +1000
Subject: [PATCH] doc: add spa to doxygen output

This requires a helper script: doxygen doesn't differ between static methods
and static inline methods. EXTRACT_STATIC defines whether it parses *any*
static method but we're currently using all C files as input files as well. We
cannot convince doxygen to just parse static inline functions in header files
so for SPA we hack around this: meson passes the spa headers to a shell script
with simply copies those changed to `/* static */ inline void (foo)` and doxygen
then runs on those header files.

The result: we get all spa functions added to your doxygen output at the cost
of a few sed calls.
---
 doc/Doxyfile.in         |  1 +
 doc/meson.build         | 28 +++++++++++++++++++++++++++-
 doc/strip-static.sh     | 18 ++++++++++++++++++
 spa/include/meson.build | 14 ++++++++++++++
 4 files changed, 60 insertions(+), 1 deletion(-)
 create mode 100755 doc/strip-static.sh

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 1d7e666b1..dd5c5bcc5 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -14,6 +14,7 @@ QUIET                  = YES
 WARN_NO_PARAMDOC       = YES
 INPUT                  = @inputs@
 FILE_PATTERNS          = "*.h" "*.c"
+RECURSIVE              = YES
 EXAMPLE_PATH           = "@top_srcdir@/src/tools" \
                          "@top_srcdir@/src/examples"
 
diff --git a/doc/meson.build b/doc/meson.build
index 0fc4d764c..744b0ee81 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -18,6 +18,31 @@ foreach h : pipewire_sources
   inputs += meson.source_root() / 'src' / 'pipewire' / h
 endforeach
 
+# 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.
+# The shell script here basically does a:
+#   cp spa/* builddir/spa/ && sed -i 's/^static//' buildir/spa/**.h
+# The copied files are passed to doxygen as input and they are parsed as
+# normal functions.
+# Because this uses globbing, this target won't rebuild if the headers
+# change but meh.
+spa_header_dirs = []
+sed = find_program('sed', required: false)
+if sed.found()
+  spa_srcdir = meson.source_root() / 'spa' / 'include' / 'spa'
+  spa_dstdir = meson.current_build_dir() / 'spa'
+  spa_strip_static = custom_target(
+    'spa-strip-static',
+    command: [ find_program('strip-static.sh'), spa_srcdir, spa_dstdir ],
+    build_by_default: true,
+    output: 'spa',
+  )
+  spa_header_dirs += spa_dstdir
+else
+  spa_strip_static = []
+endif
+
 extra_docs = [
   'overview.md',
   'design.txt',
@@ -46,7 +71,7 @@ cssfiles = [
   meson.source_root() / 'doc' / 'custom.css'
 ]
 
-doxyfile_conf.set('inputs', ' '.join(inputs))
+doxyfile_conf.set('inputs', ' '.join(inputs + [spa_dstdir]))
 doxyfile_conf.set('cssfiles', ' '.join(cssfiles))
 
 doxyfile = configure_file(input: 'Doxyfile.in',
@@ -62,5 +87,6 @@ html_target = custom_target('pipewire-docs',
                             input: [ doxyfile ] + inputs + cssfiles,
                             output: [ 'html' ],
                             command: [ doxygen, doxyfile ],
+                            depends: spa_strip_static,
                             install: true,
                             install_dir: docdir)
diff --git a/doc/strip-static.sh b/doc/strip-static.sh
new file mode 100755
index 000000000..5b777205b
--- /dev/null
+++ b/doc/strip-static.sh
@@ -0,0 +1,18 @@
+#!/bin/bash
+#
+# Replicates the source tree at $SOURCE to $DEST with any static removed
+# from the file. This allows Doxygen to parse the file and document static
+# inline functions.
+
+SOURCE="$1"
+DEST="$2"
+test -n "$SOURCE" || (echo "Source argument is missing" && exit 1)
+test -n "$DEST" || (echo "Dest argument is missing" && exit 1)
+
+echo "Reading from $SOURCE"
+echo "Copying to $DEST"
+
+mkdir -p "$DEST"
+cp -rf "$SOURCE"/* "$DEST/"
+shopt -s globstar  # proper recursive globbing
+sed -i 's|^static|/* \0 */|' "$DEST"/**/*.h
diff --git a/spa/include/meson.build b/spa/include/meson.build
index 13dbb0b66..0566b025d 100644
--- a/spa/include/meson.build
+++ b/spa/include/meson.build
@@ -1,3 +1,17 @@
+spa_sections = [
+  'buffer',
+  'control',
+  'debug',
+  'graph',
+  'monitor',
+  'node',
+  'param',
+  'pod',
+  'support',
+  'utils',
+]
+
+spa_headers = 'spa'  # used by doxygen
 install_subdir('spa',
   install_dir : get_option('includedir') / spa_name
 )