[Lldb-commits] [lldb] [lldb] Build the API unittests with -Wdocumentation (PR #128893)

[Jonas Devlieghere via lldb-commits]

https://github.com/JDevlieghere created https://github.com/llvm/llvm-project/pull/128893

The LLDB SB API headers should be -Wdocumentation clean as they might get included by projects building with -Wdocumentation. Although I'd love for all of LLDB to be clean, we're pretty far removed from that goal. Until that changes, this PR will detect issues in the SB API headers by including all the headers in the unittests (by including LLDB/API.h) and building that with the warning, if the compiler supports it.

rdar://143597614

>From 941fb2b4e928f474dc32c2023ff37952a4034cac Mon Sep 17 00:00:00 2001
From: Jonas Devlieghere <jonas at devlieghere.com>
Date: Wed, 26 Feb 2025 09:17:51 -0600
Subject: [PATCH] [lldb] Build the API unittests with -Wdocumentation

The LLDB SB API headers should be -Wdocumentation clean as they might
get included by projects building with -Wdocumentation. Although I'd
love for all of LLDB to be clean, we're pretty far removed from that
goal. Until that changes, this PR will detect issues in the SB API
headers by including all the headers in the unittests (by including
LLDB/API.h) and building that with the warning, if the compiler supports
it.

rdar://143597614
---
 lldb/include/lldb/API/SBSaveCoreOptions.h       |  2 +-
 lldb/unittests/API/CMakeLists.txt               | 10 ++++++++++
 lldb/unittests/API/SBCommandInterpreterTest.cpp |  5 ++---
 3 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/lldb/include/lldb/API/SBSaveCoreOptions.h b/lldb/include/lldb/API/SBSaveCoreOptions.h
index 7852858f8ade9..c6d2ab6099b3c 100644
--- a/lldb/include/lldb/API/SBSaveCoreOptions.h
+++ b/lldb/include/lldb/API/SBSaveCoreOptions.h
@@ -54,7 +54,7 @@ class LLDB_API SBSaveCoreOptions {
   /// Set the output file path
   ///
   /// \param
-  ///   output_file a \class SBFileSpec object that describes the output file.
+  ///   output_file a \ref SBFileSpec object that describes the output file.
   void SetOutputFile(SBFileSpec output_file);
 
   /// Get the output file spec
diff --git a/lldb/unittests/API/CMakeLists.txt b/lldb/unittests/API/CMakeLists.txt
index 2f066f26d8aaf..52e9a5e991515 100644
--- a/lldb/unittests/API/CMakeLists.txt
+++ b/lldb/unittests/API/CMakeLists.txt
@@ -5,6 +5,16 @@ add_lldb_unittest(APITests
     liblldb
   )
 
+# Build with -Wdocumentation. This relies on the tests including all the API
+# headers through API/LLDB.h.
+check_cxx_compiler_flag("-Wdocumentation"
+                        CXX_SUPPORTS_DOCUMENTATION)
+if (CXX_SUPPORTS_DOCUMENTATION)
+  target_compile_options(APITests
+    PRIVATE -Wdocumentation)
+endif()
+
+
 if(Python3_RPATH)
   set_property(TARGET APITests APPEND PROPERTY BUILD_RPATH "${Python3_RPATH}")
 endif()
diff --git a/lldb/unittests/API/SBCommandInterpreterTest.cpp b/lldb/unittests/API/SBCommandInterpreterTest.cpp
index d3f6ec639162b..941b738e84ac8 100644
--- a/lldb/unittests/API/SBCommandInterpreterTest.cpp
+++ b/lldb/unittests/API/SBCommandInterpreterTest.cpp
@@ -8,9 +8,8 @@
 
 #include "gtest/gtest.h"
 
-#include "lldb/API/SBCommandInterpreter.h"
-#include "lldb/API/SBCommandReturnObject.h"
-#include "lldb/API/SBDebugger.h"
+// Use the umbrella header for -Wdocumentation.
+#include "lldb/API/LLDB.h"
 
 #include <cstring>
 #include <string>