doc: make Doxygen to show only symbols defined in headers

Make Doxygen data structure etc. lists less cluttered by hiding
non-public stuff.

Add a Doxygen input filter that marks symbols declared in C files
private, so that they won't appear in the output unless the symbol is
also declared in a header.

The "spa static inline" hack is then also not needed any more.

doc/Doxyfile.in

@@ -6,6 +6,9 @@ JAVADOC_AUTOBRIEF      = YES
 TAB_SIZE               = 8
 OPTIMIZE_OUTPUT_FOR_C  = YES
 EXTRACT_ALL            = YES
+EXTRACT_STATIC         = YES
+FULL_PATH_NAMES        = YES
+STRIP_FROM_PATH        = @path_prefixes@
 SHOW_INCLUDE_FILES     = NO
 GENERATE_TODOLIST      = NO
 GENERATE_TESTLIST      = NO
@@ -14,6 +17,7 @@ QUIET                  = YES
 WARN_NO_PARAMDOC       = YES
 HAVE_DOT               = @HAVE_DOT@
 INPUT                  = @inputs@
+FILTER_PATTERNS        = "*.c=@c_input_filter@"
 FILE_PATTERNS          = "*.h" "*.c"
 RECURSIVE              = YES
 EXAMPLE_PATH           = "@top_srcdir@/src/tools" \
@@ -23,7 +27,9 @@ EXAMPLE_PATH           = "@top_srcdir@/src/tools" \
 REFERENCED_BY_RELATION = YES
 REFERENCES_RELATION    = YES
 IGNORE_PREFIX          = pw_ \
-                         PW_
+                         PW_ \
+                         spa_ \
+                         SPA_
 GENERATE_TREEVIEW      = YES
 SEARCHENGINE           = NO
 GENERATE_LATEX         = NO

doc/input-filter.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+#
+# Doxygen input filter that adds \privatesection to all files,
+# and removes macros.
+#
+# This is used for .c files, and causes Doxygen to not include
+# any symbols from them, unless they also appeared in a header file.
+#
+echo -n "/** \privatesection */ "
+sed -e 's/#define.*//' < "$1"

doc/meson.build

@@ -25,31 +25,14 @@ endforeach
 foreach h : media_session_sources
   inputs += meson.source_root() / 'src' / 'media-session' / h
 endforeach
+inputs += meson.source_root() / 'spa' / 'include' / 'spa'
 inputs += meson.source_root() / 'test' / 'pwtest.h'
 
-# SPA headers use static inline functions. Doxygen doesn't extract those
+path_prefixes = [
-# unless we have EXTRACT_STATIC set - but we don't want it to extract
+  meson.source_root() / 'src',
-# everything in the rest of the tree.
+  meson.source_root() / 'spa' / 'include',
-# The shell script here basically does a:
+  meson.source_root(),
-#   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.
-sed = find_program('sed', required: false)
-summary({'sed (for SPA docs)': sed.found()}, bool_yn: true, section: 'Optional programs')
-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',
-  )
-else
-  spa_strip_static = []
-endif
 
 # Note: order here is how doxygen will expose the pages in the sidebar
 extra_docs = [
@@ -94,8 +77,10 @@ cssfiles = [
   meson.source_root() / 'doc' / 'custom.css'
 ]
 
-doxyfile_conf.set('inputs', ' '.join(inputs + [spa_dstdir]))
+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 = configure_file(input: 'Doxyfile.in',
                           output: 'Doxyfile',
@@ -110,6 +95,5 @@ html_target = custom_target('pipewire-docs',
                             input: [ doxyfile ] + inputs + cssfiles,
                             output: [ 'html' ],
                             command: [ doxygen, doxyfile ],
-                            depends: spa_strip_static,
                             install: true,
                             install_dir: docdir)

doc/strip-static.sh

@@ -1,18 +0,0 @@
-#!/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