[lldb] Enable SWIG Doxygen Translation #147617
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Enable SWIG support for translating Doxygen comments found in interface and header files into a target language's normal documentation language. This feature was introduced in SWIG 4.0 and currently only supports Python (and Java). Hand-written documentation still takes precedence.
JDevlieghere
requested review from
DavidSpickett,
bulbazord,
labath and
medismailben
|
@llvm/pr-subscribers-lldb Author: Jonas Devlieghere (JDevlieghere) ChangesEnable SWIG support for translating Doxygen comments found in interface and header files into a target language's normal documentation language. This feature was introduced in SWIG 4.0 and currently only supports Python (and Java). Hand-written documentation still takes precedence. Full diff: https://github.com/llvm/llvm-project/pull/147617.diff 1 Files Affected:
diff --git a/lldb/bindings/python/CMakeLists.txt b/lldb/bindings/python/CMakeLists.txt
index 69306a384e0b1..ef6def3f26872 100644
--- a/lldb/bindings/python/CMakeLists.txt
+++ b/lldb/bindings/python/CMakeLists.txt
@@ -14,6 +14,7 @@ add_custom_command(
DEPENDS lldb-sbapi-dwarf-enums
COMMAND ${SWIG_EXECUTABLE}
${SWIG_COMMON_FLAGS}
+ -doxygen
-I${CMAKE_CURRENT_SOURCE_DIR}
${SWIG_EXTRA_FLAGS}
-outdir ${CMAKE_CURRENT_BINARY_DIR}
|
JDevlieghere
added a commit
to JDevlieghere/llvm-project
that referenced
this pull request
Jul 9, 2025
Despite our best efforts, improved documentation of the public API remains a common request amongst its users. We have the Docstrings files in the bindings directory, but coverage and quality varies greatly by class. I've noticed that we a bunch of Doxygen comments throughout LLDB, but relatively few in the SB API, which might be explained by the aforementioned Docstrings files. With llvm#147617, we can leverage the Doxygen documentation to automatically generate Pydoc documentation for the Python bindings using SWIG. Going forward, I'd like to invest in the Doxygen documentation for the public API. This PR is a first step in that direction. The Doxygen comments will benefit both C++ and Python clients. Additionally, the compiler (through the -Wdocumentation flag) can help catch quality and correctness issues.
labath
approved these changes
Jul 9, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Enable SWIG support for translating Doxygen comments found in interface and header files into a target language's normal documentation language. This feature was introduced in SWIG 4.0 and currently only supports Python (and Java). Hand-written documentation still takes precedence.
SWIG documentation: https://www.swig.org/Doc4.0/Doxygen.html