Qt Creator help/documentation file for Clang

[kwk]

Summary

In D2967 I've proposed a change to generate a Qt Compressed Help file for the LLVM source code.

As a consequence, this change brings the same capabilities to Clang while reusing these two variables:

LLVM_ENABLE_DOXYGEN_QT_HELP
LLVM_DOXYGEN_QHELPGENERATOR_PATH

and adding

CLANG_DOXYGEN_QCH_FILENAME="org.llvm.clang.qch"
CLANG_DOXYGEN_QHP_NAMESPACE="org.llvm.clang"
CLANG_DOXYGEN_QHP_CUST_FILTER_NAME="Clang ${CLANG_VERSION}"
CLANG_DOXYGEN_QHP_CUST_FILTER_ATTRS="Clang,${CLANG_VERSION}"

Regards,
Konrad

[gribozavr]

Please document these build parameters somewhere.

[kwk]

Here's a screenshot of how the generated documentation file org.llvm.clang.qch looks like in Qt Creator. Here,

{F46626}

[kwk]

docs/doxygen.cfg.in

753–761

These comment lines for GENERATE_ECLIPSEHELP are not needed. I accidentally committed them.

[kwk]

Hi gribozavr,

in which place shall I document the build variables? The options and variables I've added all have a descriptions string that shows up in in the cmake-gui command.

I ran this command:

find . -name "CMakeLists.txt" | xargs rgrep "CLANG_[A-Z0-9_]*" -o --no-filename | sort | uniq -c | sort -n

to get this list of CLANG_* identifiers from the CMakeLists.txt files:

 1 CLANG_DOC_QCH_FILENAME
 1 CLANG_DOC_QHELPGENERATOR_PATH
 1 CLANG_DOC_QHP_NAMESPACE
 1 CLANG_GENERATE_QHP
 1 CLANG_RESOURCE_DIR
 1 CLANG_TOOLS_BINARY_DIR
 1 CLANG_TOOLS_EXTRA_SOURCE_DIR
 1 CLANG_TOOLS_SOURCE_DIR
 1 CLANG_VERSION_PATCHLEVEL
 2 CLANG_BINARY_DIR
 2 CLANG_BUILD_STATIC
 2 CLANG_DOC_GENERATE_QCH
 2 CLANG_DOC_GENERATE_QHP
 2 CLANG_EXAMPLES
 2 CLANG_FORMAT_VS_PLUGIN
 2 CLANG_GENERATE_QCH
 2 CLANG_HAS_VERSION_PATCHLEVEL
 2 CLANG_HAVE_LIBXML
 2 CLANG_INCLUDE_DOCS
 2 CLANG_INCLUDE_TESTS
 2 CLANG_LINT_SOURCE_DIR
 2 CLANG_MODERNIZE_SOURCE_DIR
 2 CLANG_TEST_USE_VG
 2 CLANG_TOOLS_DIR
 2 CLANG_TOOLS_TEST_DEPS
 2 CLANG_TOOLS_TEST_EXTRA_ARGS
 2 CLANG_TOOLS_TEST_USE_VG
 2 CLANG_VENDOR_UTI
 3 CLANG_BUILD_EXAMPLES
 3 CLANG_BUILT_STANDALONE
 3 CLANG_EXECUTABLE_VERSION
 3 CLANG_ORDER_FILE
 3 CLANG_TEST_PARAMS
 3 CLANG_VERSION_MAJOR
 3 CLANG_VERSION_MINOR
 4 CLANG_LIBRARY_VERSION
 4 CLANG_LINK_FLAGS
 4 CLANG_REPOSITORY_STRING
 4 CLANG_TABLEGEN_TARGETS
 4 CLANG_TEST_EXTRA_ARGS
 5 CLANG_TEST_DEPS
 6 CLANG_VENDOR
 8 CLANG_ENABLE_ARCMT
 8 CLANG_ENABLE_REWRITER
10 CLANG_ENABLE_STATIC_ANALYZER
11 CLANG_VERSION
12 CLANG_SOURCE_DIR

When I search for one of them, they only occur in CMakeLists.txt files themselves. For example:

grep "CLANG_ENABLE_ARCMT" . -r --context=5

And in the context ofr 5 lines before and after the match I couldn't find any more documentation than the description that I've added as well.

This isn't meant as an excuse but I'd really like to know in what other places to the build parameters.

[kwk]

Based on D2967 I plan to modify this patch.

[kwk]

This change uses the already exising CMake option LLVM_ENABLE_DOXYGEN_QT_HELP
to check whether a Qt Compressed Help file shall be generated. Also, the path
to the qhelpgenerator binary is reused (LLVM_DOXYGEN_QHELPGENERATOR_PATH).

This change depends on revision rL203272 of the LLVM source.

[gottesmm]

One question, otherwise this looks fine to me. I defer of course to other gribozavr if he has any opinions.

docs/CMakeLists.txt

29

I noticed that the previous namespace was org.llvm. Is that correct? Will that cause any conflicts/etc? I don't know that much about QHP, but it just seems like an obvious question.

[kwk]

docs/CMakeLists.txt

29

Both QHP files, the one for LLVM and the Clang one, need to have distinct namespaces, otherwise they cannot be imported by a viewing application like Qt Creator. Therefore, it's correct to pick org.llvm.clang as namespace for the CLANG QHP file.

[kwk]

Since the CMake variables LLVM_ENABLE_DOXYGEN_QT_HELP and LLVM_DOXYGEN_QHELPGENERATOR_PATH are already documented in $LLVM/docs/CMake.rst, I think the most important parts are covered.

[gottesmm]

Alright sounds good to me.

[gribozavr]

Committed r203801.