mirror of
https://gitlab.freedesktop.org/pipewire/pipewire
synced 2024-10-06 16:09:43 +00:00
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.
This commit is contained in:
parent
1ba805ac7e
commit
c345d1e11d
|
@ -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
|
||||
|
|
10
doc/input-filter.sh
Executable file
10
doc/input-filter.sh
Executable file
|
@ -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"
|
|
@ -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
|
||||
# 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.
|
||||
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
|
||||
path_prefixes = [
|
||||
meson.source_root() / 'src',
|
||||
meson.source_root() / 'spa' / 'include',
|
||||
meson.source_root(),
|
||||
]
|
||||
|
||||
# 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)
|
||||
|
|
|
@ -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
|
Loading…
Reference in a new issue