[lldb] Build the API unittests with -Wdocumentation

[JDevlieghere]

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

[llvmbot]

@llvm/pr-subscribers-lldb

Author: Jonas Devlieghere (JDevlieghere)

Changes

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

---

Full diff: https://github.com/llvm/llvm-project/pull/128893.diff

3 Files Affected:

• (modified) lldb/include/lldb/API/SBSaveCoreOptions.h (+1-1)
• (modified) lldb/unittests/API/CMakeLists.txt (+10)
• (modified) lldb/unittests/API/SBCommandInterpreterTest.cpp (+2-3)

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>

[labath]

A slightly unusual setup, but I sort of like it.