[PATCH v4 1/7] doc: detect ignored public headers

Some public headers were omitted from doc/api/doxy-api-index.md and/or
doc/api/doxy-api.conf.in. Add checks to meson configuration, with
exceptions, detecting and warning about these.

Suggested-by: Bruce Richardson <[email protected]>
Signed-off-by: Marat Khalili <[email protected]>
---
 drivers/meson.build | 21 +++++++++++++++++++++
 lib/meson.build     | 27 +++++++++++++++++++++++++++
 meson.build         | 28 ++++++++++++++++++++++++++++
 3 files changed, 76 insertions(+)

diff --git a/drivers/meson.build b/drivers/meson.build
index 102a8262e588..a3e6ebc26bc2 100644
--- a/drivers/meson.build
+++ b/drivers/meson.build
@@ -287,6 +287,27 @@ foreach subpath:subdirs
         dpdk_headers += headers
         dpdk_drivers_headers += driver_sdk_headers
 
+        if check_docs and headers.length() > 0
+            foreach h:headers
+                hname = fs.name(h)
+                if not hname.startswith('rte_')
+                    warning('public header @0@ name does not start with "rte_"'.format(h))
+                endif
+                is_ignored = false
+                foreach ig:doc_ignored_header_suffixes
+                    is_ignored = is_ignored or ('/' + hname).endswith(ig)
+                endforeach
+                if not is_ignored and hname not in doc_indexed_headers
+                    warning('public header @0@ is not listed in @1@'.format(h, doc_index_path))
+                endif
+            endforeach
+            doc_dir = 'drivers/' + drv_path
+            if doc_dir not in doc_built_dirs
+                warning('public header directory @0@ is not listed in @1@'.format(doc_dir,
+                    doc_build_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 af5c160cb800..8c974477c651 100644
--- a/lib/meson.build
+++ b/lib/meson.build
@@ -209,6 +209,33 @@ foreach l:libraries
     dpdk_indirect_headers += indirect_headers
     dpdk_drivers_headers += driver_sdk_headers
 
+    if check_docs and headers.length() > 0
+        foreach h:headers
+            hname = fs.name(h)
+            if not (hname.startswith('rte_') or hname.startswith('cmdline'))
+                warning('public header @0@ name does not start with "rte_" or "cmdline"'.format(h))
+            endif
+            is_ignored = false
+            foreach ig:doc_ignored_header_suffixes
+                is_ignored = is_ignored or ('/' + hname).endswith(ig)
+            endforeach
+            if not is_ignored and hname not in doc_indexed_headers
+                warning('public header @0@ is not listed in @1@'.format(h, doc_index_path))
+            endif
+        endforeach
+        if l == 'eal'
+            doc_dirs = ['lib/eal/include', 'lib/eal/include/generic']
+        else
+            doc_dirs = ['lib/' + l]
+        endif
+        foreach d:doc_dirs
+            if d not in doc_built_dirs
+                warning('public header directory @0@ is not listed in @1@'.format(d,
+                    doc_build_path))
+            endif
+        endforeach
+    endif
+
     libname = 'rte_' + name
     includes += include_directories(l)
     dpdk_includes += include_directories(l)
diff --git a/meson.build b/meson.build
index b01010ffa076..d22f0d4b57bf 100644
--- a/meson.build
+++ b/meson.build
@@ -88,6 +88,34 @@ if is_linux
     global_inc += include_directories('kernel/linux')
 endif
 
+# on linux, try to check that documentation sources are correctly built and indexed
+check_docs = is_linux and meson.version().version_compare('>= 0.60.0')
+
+if check_docs
+    doc_build_path = 'doc/api/doxy-api.conf.in'
+    doc_build_file = dpdk_source_root / doc_build_path
+    doc_built_dirs = run_command('sed', '--regexp-extended', '--quiet',
+        # Extract and print the file path immediately following @TOPDIR@/ .
+        's#^(INPUT *=)? *@TOPDIR@/([^ ]*)( .*|\\\\|)$#\\2#p',
+        doc_build_file, check: true).stdout().strip('\n').split('\n')
+
+    doc_index_path = 'doc/api/doxy-api-index.md'
+    doc_index_file = dpdk_source_root / doc_index_path
+    doc_indexed_headers = run_command('sed', '--regexp-extended', '--quiet',
+        # Extract and print the (@ref ...) contents.
+        's#^.*\\(@ref ([^)]*)\\).*$#\\1#p',
+        doc_index_file, check: true).stdout().strip('\n').split('\n')
+
+    # Suffixes of the headers that don't have to be indexed;
+    # full name is matched if the entry starts with a slash.
+    doc_ignored_header_suffixes = [
+            '/rte_os.h',
+            '/rte_trace_point_register.h',
+            '_trace.h',
+            '_trace_fp.h',
+    ]
+endif
+
 # build libs and drivers
 subdir('lib')
 subdir('drivers')
-- 
2.43.0