On Tue, Jun 30, 2026 at 06:10:59PM +0200, Thomas Monjalon wrote:
> Hello,
>
> 30/06/2026 11:03, Marat Khalili:
> > I noticed that a few header files contain docstring-like comments but are
> > not
> > present in doc/api/doxy-api-index.md and/or (fewer) in
> > doc/api/doxy-api.conf.in
> > There seem to be no checks anywhere in the process that would make sure
> > these
> > index files are updated. Do we even care, or is it unsupported legacy? If
> > we do
> > care, would a check or an automatic generation fix be more promising?
>
> Some internal files have doxygen comments, not sure why,
> probably to run Doxygen manually on these files.
>
> In the scope of our public documentation,
> the goal was to document all and only public API.
>
> If you see some public API not referenced, it is a bug.
> And yes a script to check this may be useful.
>
Something like this could work as a quick check that all public headers are
getting indexed. Doesn't help with verifying that all contents within the
files have comments, but maybe its an easy start point:
diff --git a/drivers/meson.build b/drivers/meson.build
index 4d95604ecd..5a9ba68d54 100644
--- a/drivers/meson.build
+++ b/drivers/meson.build
@@ -278,6 +278,23 @@ foreach subpath:subdirs
dpdk_headers += headers
dpdk_drivers_headers += driver_sdk_headers
+ # On Linux, best-effort check that public headers are named correctly
+ # and that the driver directory is referenced in the Doxygen config so
+ # that its API gets indexed.
+ if is_linux and meson.version().version_compare('>= 0.59.0') and
headers.length() > 0
+ foreach h:headers
+ hname = fs.name(h)
+ if not hname.startswith('rte_')
+ warning('drivers/@0@: public header "@1@" does not start
with "rte_"'.format(drv_path, hname))
+ endif
+ endforeach
+ if run_command('grep', '-qF', '@TOPDIR@/drivers/' + drv_path,
+ dpdk_source_root / 'doc' / 'api' / 'doxy-api.conf.in',
+ check: false).returncode() != 0
+ warning('drivers/@0@: has public headers but not listed in
doxy-api.conf.in'.format(drv_path))
+ endif
+ endif
+
if headers.length() > 0
dpdk_includes += include_directories(drv_path)
endif
diff --git a/lib/meson.build b/lib/meson.build
index af5c160cb8..d897b2c73a 100644
--- a/lib/meson.build
+++ b/lib/meson.build
@@ -209,6 +209,23 @@ foreach l:libraries
dpdk_indirect_headers += indirect_headers
dpdk_drivers_headers += driver_sdk_headers
+ # On Linux, best-effort check that public headers are named correctly
+ # and that the library directory is referenced in the Doxygen config so
+ # that its API gets indexed.
+ if is_linux and meson.version().version_compare('>= 0.59.0') and
headers.length() > 0
+ foreach h:headers
+ hname = fs.name(h)
+ if not (hname.startswith('rte_') or hname.startswith('cmdline'))
+ warning('lib/@0@: public header "@1@" does not start with
"rte_" or "cmdline"'.format(l, hname))
+ endif
+ endforeach
+ if run_command('grep', '-qF', '@TOPDIR@/lib/' + l,
+ dpdk_source_root / 'doc' / 'api' / 'doxy-api.conf.in',
+ check: false).returncode() != 0
+ warning('lib/@0@: has public headers but not listed in
doxy-api.conf.in'.format(l))
+ endif
+ endif
+
libname = 'rte_' + name
includes += include_directories(l)
dpdk_includes += include_directories(l)
