Re: [RFC] doc: updating doxy-api-index.md and doxy-api.conf.in

[Bruce Richardson <bruce.richardson@intel.com>]

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)