Is there a way we could prevent including private members with documentation? They kind of clutter the docs generated with members that developers can't even use.

If the user specifies 'ignore.ignore_private_members=false' in their .hdoc.toml, we are interpreting that as if they wrote 'ignore.ignore_private_members=true'. This is because .as_boolean returns a pointer, and we are casting that non-null pointer to a boolean, which always yields true.

Fix the problem:

• Avoid auto, which made the problem harder to see
• Use .value() (which returns a std::optional) instead of .as_boolean() (which returns a toml::value*)
• Use * to extract the value from the std::optional (which the compiler helpfully now tells us to do)

Compiling current master on Arch Linux fails for two reasons, both of which this PR addresses:

• argparse.hpp currently does not include <utility>, which results in an compilation error; this is fixed by bumping it to v2.9.
• Arch Linux ships it clang libraries as clang-cpp (as do some other distros), so that meson can't find the libraries; this is fixed by defaulting to using clang-cpp, but falling back to the old method. This is the same approach as used by mesa.

To reproduce:

1. clone repo
2. meson build
3. See this:

/tmp/hdoc(master) » CC=gcc CXX=g++ meson build                                               [email protected]
The Meson build system
Version: 0.57.1
Source dir: /tmp/hdoc
Build dir: /tmp/hdoc/build
Build type: native build
Project name: hdoc
Project version: 1.0.1
C++ compiler for the host machine: g++ (gcc 10.2.0 "g++ (GCC) 10.2.0")
C++ linker for the host machine: g++ ld.bfd 2.36.1
Host machine cpu family: x86_64
Host machine cpu: x86_64
Found CMake: /home/bogdan/.local/bin/cmake (3.18.4)
WARNING: Ignoring LLVM CMake dependency because dynamic was requested
llvm-config found: YES (/usr/bin/llvm-config) 11.1.0
Run-time dependency LLVM found: YES 11.1.0
Run-time dependency clang found: NO 

meson.build:13:0: ERROR: Dependency Clang not found: CMake: invalid module clangTooling for Clang.
Try to explicitly specify one or more targets with the "modules" property.
Valid targets are:
['LLVMDemangle', 'LLVMSupport', 'LLVMTableGen', 'llvm-tblgen', 'LLVMCore', 'LLVMFuzzMutate', 'LLVMIRReader', 'LLVMCodeGen', 'LLVMSelectionDAG', 'LLVMAsmPrinter', 'LLVMMIRParser', 'LLVMGlobalISel', 'LLVMBinaryFormat', 'LLVMBitReader', 'LLVMBitWriter', 'LLVMBitstreamReader', 'LLVMDWARFLinker', 'LLVMExtensions', 'LLVMFrontendOpenACC', 'LLVMFrontendOpenMP', 'LLVMTransformUtils', 'LLVMInstrumentation', 'LLVMAggressiveInstCombine', 'LLVMInstCombine', 'LLVMScalarOpts', 'LLVMipo', 'LLVMVectorize', 'LLVMObjCARCOpts', 'LLVMCoroutines', 'LLVMCFGuard', 'LLVMLinker', 'LLVMAnalysis', 'LLVMLTO', 'LLVMMC', 'LLVMMCParser', 'LLVMMCDisassembler', 'LLVMMCA', 'LLVMObject', 'LLVMObjectYAML', 'LLVMOption', 'LLVMRemarks', 'LLVMDebugInfoDWARF', 'LLVMDebugInfoGSYM', 'LLVMDebugInfoMSF', 'LLVMDebugInfoCodeView', 'LLVMDebugInfoPDB', 'LLVMSymbolize', 'LLVMExecutionEngine', 'LLVMInterpreter', 'LLVMJITLink', 'LLVMMCJIT', 'LLVMOrcError', 'LLVMOrcJIT', 'LLVMRuntimeDyld', 'LLVMTarget', 'LLVMAArch64CodeGen', 'LLVMAArch64AsmParser', 'LLVMAArch64Disassembler', 'LLVMAArch64Desc', 'LLVMAArch64Info', 'LLVMAArch64Utils', 'LLVMAMDGPUCodeGen', 'LLVMAMDGPUAsmParser', 'LLVMAMDGPUDisassembler', 'LLVMAMDGPUDesc', 'LLVMAMDGPUInfo', 'LLVMAMDGPUUtils', 'LLVMARMCodeGen', 'LLVMARMAsmParser', 'LLVMARMDisassembler', 'LLVMARMDesc', 'LLVMARMInfo', 'LLVMARMUtils', 'LLVMAVRCodeGen', 'LLVMAVRAsmParser', 'LLVMAVRDisassembler', 'LLVMAVRDesc', 'LLVMAVRInfo', 'LLVMBPFCodeGen', 'LLVMBPFAsmParser', 'LLVMBPFDisassembler', 'LLVMBPFDesc', 'LLVMBPFInfo', 'LLVMHexagonCodeGen', 'LLVMHexagonAsmParser', 'LLVMHexagonDisassembler', 'LLVMHexagonDesc', 'LLVMHexagonInfo', 'LLVMLanaiCodeGen', 'LLVMLanaiAsmParser', 'LLVMLanaiDisassembler', 'LLVMLanaiDesc', 'LLVMLanaiInfo', 'LLVMMipsCodeGen', 'LLVMMipsAsmParser', 'LLVMMipsDisassembler', 'LLVMMipsDesc', 'LLVMMipsInfo', 'LLVMMSP430CodeGen', 'LLVMMSP430Desc', 'LLVMMSP430Info', 'LLVMMSP430AsmParser', 'LLVMMSP430Disassembler', 'LLVMNVPTXCodeGen', 'LLVMNVPTXDesc', 'LLVMNVPTXInfo', 'LLVMPowerPCCodeGen', 'LLVMPowerPCAsmParser', 'LLVMPowerPCDisassembler', 'LLVMPowerPCDesc', 'LLVMPowerPCInfo', 'LLVMRISCVCodeGen', 'LLVMRISCVAsmParser', 'LLVMRISCVDisassembler', 'LLVMRISCVDesc', 'LLVMRISCVInfo', 'LLVMRISCVUtils', 'LLVMSparcCodeGen', 'LLVMSparcAsmParser', 'LLVMSparcDisassembler', 'LLVMSparcDesc', 'LLVMSparcInfo', 'LLVMSystemZCodeGen', 'LLVMSystemZAsmParser', 'LLVMSystemZDisassembler', 'LLVMSystemZDesc', 'LLVMSystemZInfo', 'LLVMWebAssemblyCodeGen', 'LLVMWebAssemblyAsmParser', 'LLVMWebAssemblyDisassembler', 'LLVMWebAssemblyDesc', 'LLVMWebAssemblyInfo', 'LLVMX86CodeGen', 'LLVMX86AsmParser', 'LLVMX86Disassembler', 'LLVMX86Desc', 'LLVMX86Info', 'LLVMXCoreCodeGen', 'LLVMXCoreDisassembler', 'LLVMXCoreDesc', 'LLVMXCoreInfo', 'LLVMAsmParser', 'LLVMLineEditor', 'LLVMProfileData', 'LLVMCoverage', 'LLVMPasses', 'LLVMTextAPI', 'LLVMDlltoolDriver', 'LLVMLibDriver', 'LLVMXRay', 'LLVMWindowsManifest', 'FileCheck', 'llvm-PerfectShuffle', 'count', 'not', 'yaml-bench', 'LTO', 'LLVMgold', 'llvm-ar', 'llvm-config', 'llvm-lto', 'llvm-profdata', 'bugpoint', 'dsymutil', 'llc', 'lli-child-target', 'lli', 'llvm-as', 'llvm-bcanalyzer', 'llvm-c-test', 'llvm-cat', 'llvm-cfi-verify', 'llvm-cov', 'llvm-cvtres', 'llvm-cxxdump', 'llvm-cxxfilt', 'llvm-cxxmap', 'llvm-diff', 'llvm-dis', 'llvm-dwarfdump', 'llvm-dwp', 'llvm-elfabi', 'llvm-exegesis', 'llvm-extract', 'llvm-gsymutil', 'llvm-ifs', 'llvm-jitlink', 'llvm-link', 'llvm-lipo', 'llvm-lto2', 'llvm-mc', 'llvm-mca', 'llvm-ml', 'llvm-modextract', 'llvm-mt', 'llvm-nm', 'llvm-objcopy', 'llvm-objdump', 'llvm-opt-report', 'llvm-pdbutil', 'llvm-rc', 'llvm-readobj', 'llvm-reduce', 'llvm-rtdyld', 'LLVM', 'llvm-size', 'llvm-split', 'llvm-stress', 'llvm-strings', 'llvm-symbolizer', 'llvm-undname', 'llvm-xray', 'obj2yaml', 'opt', 'Remarks', 'sancov', 'sanstats', 'verify-uselistorder', 'yaml2obj', 'intrinsics_gen', 'omp_gen', 'acc_gen', 'diagtool', 'clang', 'clang-format', 'clang-offload-bundler', 'clang-offload-wrapper', 'clang-scan-deps', 'clang-rename', 'clang-refactor', 'clang-cpp', 'clang-check', 'clang-extdef-mapping', 'clang-apply-replacements', 'clang-reorder-fields', 'modularize', 'clang-tidy', 'clang-change-namespace', 'clang-doc', 'clang-include-fixer', 'find-all-symbols', 'clang-move', 'clang-query', 'pp-trace', 'clangd', 'libclang', 'clang-tablegen-targets']

A full log can be found at /tmp/hdoc/build/meson-logs/meson-log.txt

clang is installed, as well as g++/gcc. I tried to set CC=clang CXX=clang++, but this didn't help.

This is a minor request, but one small change in my hdoc patches is to hide the timestamp from the footer of generated docs:

Removing the timestamp reduces unnecessary thrash in the generated output. For example, this docs update does not include any changes to cpp docs because the timestamp is not in the footer.

When I tried creating a Dockerfile to build hdoc, I found that the CMake steps failed because C language support was not enabled. Adding 'c' to this list makes things work.

Example failure: https://gist.github.com/jtbandes/b5eea7b8543fa3c1681dda1837e6a0a0

Determining dependency 'LLVM' with CMake executable '/usr/bin/cmake'
Try CMake generator: Ninja

...

CMake failed for generator Ninja and package LLVM with error code 1
OUT:

...

-- Could NOT find FFI (missing: HAVE_FFI_CALL) 
-- Could NOT find Terminfo (missing: Terminfo_LINKABLE) 
-- Could NOT find ZLIB (missing: ZLIB_LIBRARY ZLIB_INCLUDE_DIR) 
-- Found LibXml2: /usr/lib/aarch64-linux-gnu/libxml2.so (found version "2.9.13") 
-- Configuring incomplete, errors occurred!
See also "/hdoc/build/meson-private/cmake_LLVM/CMakeFiles/CMakeOutput.log".

ERR:
CMake Error at /usr/share/cmake-3.22/Modules/Internal/CheckSourceCompiles.cmake:44 (message):
  check_source_compiles: C: needs to be enabled before use.
Call Stack (most recent call first):
  /usr/share/cmake-3.22/Modules/CheckCSourceCompiles.cmake:76 (cmake_check_source_compiles)
  /usr/lib/llvm-14/cmake/FindFFI.cmake:44 (check_c_source_compiles)
  /usr/lib/llvm-14/cmake/LLVMConfig.cmake:242 (find_package)
  CMakeLists.txt:9 (find_package)


CMake Error at /usr/share/cmake-3.22/Modules/Internal/CheckSourceCompiles.cmake:44 (message):
  check_source_compiles: C: needs to be enabled before use.
Call Stack (most recent call first):
  /usr/share/cmake-3.22/Modules/CheckCSourceCompiles.cmake:76 (cmake_check_source_compiles)
  /usr/lib/llvm-14/cmake/FindTerminfo.cmake:21 (check_c_source_compiles)
  /usr/lib/llvm-14/cmake/LLVMConfig.cmake:249 (find_package)
  CMakeLists.txt:9 (find_package)

When I declare a function as a return type like so

constexpr auto borrow() const& noexcept -> const value_type&;

hdoc displays it like so https://imgur.com/a/A17UJ6g

It seems to split the const& specifier on a member function and split it in 2 parts. Not sure why it happens. It's not a big bug, but i thought it was worth reporting

I'm trying hdoc, and it doesn't seem to show my class comments in the generated documentation.

Code: https://github.com/quick-lint/quick-lint-js/blob/079240a6bc89b7386e5e092b67442a85e8d49b6e/src/quick-lint-js/fe/parse.h#L83-L85

hdoc output:

It doesn't seem to work with member functions either: https://github.com/quick-lint/quick-lint-js/blob/079240a6bc89b7386e5e092b67442a85e8d49b6e/src/quick-lint-js/fe/parse.h#L103-L111

or anything else I've looked at.

Here's my .hdoc.toml:

[project]
name = "quick-lint-js"
version = "2.9.0"

git_repo_url = "https://github.com/quick-lint/quick-lint-js/blob/master/"

[paths]
compile_commands = "build/compile_commands.json"
output_dir = "build/hdoc"

It looks like hdoc doesn't show me any global variables. It only shows me classes, functions, enums, and namespaces. I'd like to see my globals listed, searchable, and documented.

I have some file-scoped global variables (example, example). I do not want those variables to be listed by hdoc (because that would be noisy, and possibly confusing because of name collisions).

Feature request:

The only thing stopping me from fully adopting hdoc is the inability to add nicely formatted code examples. Ideally this would take the form of something like Doxygens:

\code{.cpp}
[[magic import example.cpp]]
\endcode 

Another change that I keep in a hdoc patch is to remove this large "hdoc" link from the sidebar:

I'm not against having a link back to hdoc.io to make the tool discoverable (and there already is one in the footer), but it doesn't need to be the largest link on the page and prominently displayed above the title of the actual project being documented. 😄

hdoc supports (some of) doxygen syntax, which makes sense.

But instead, I would like to write documentation in the syntax of Rustdoc, which doesn't require a lot of keywords. Instead it uses markdown syntax: https://doc.rust-lang.org/rust-by-example/meta/doc.html#doc-comments.

This could be a runtime option since being backward compat with doxygen seems like an important thing.

An example comment that uses the # Header syntax in markdown, in this case # Safety which should appear on its own line bolded then: https://docs.hdoc.io/danakj/subspace/r3642BA3A7BB0524E.html#D5D58BB0594AEC21

Static methods disappear into the list of instance methods.

https://docs.hdoc.io/danakj/subspace/r3AD4D4163C31005F.html

It would also be really nice to separate constructors and operators out, and maybe even provide them in a more human-readable friendly way instead of just the C++ syntax.

Here's a class f32: https://docs.hdoc.io/g/subspace/r603874E574DC6453.html

It has a ton of static and instance methods declared in macros: https://github.com/chromium/subspace/blob/main/num/float.h#L30-L31

However the documentation omits them all.

The same is true for other classes like this in the project, i32, i8, u8, etc.

I build my project with precompiled headers. The compile_commands.json lists precompiled headers. Unfortunately, hdoc uses a different version of Clang than my build, leading to errors like the following when running hdoc:

Error while processing /Users/strager/Projects/quick-lint-js/test/test-utf-16.cpp.
[2022-10-01 14:59:58.924] [error] Failed to parse source file: /Users/strager/Projects/quick-lint-js/test/test-utf-16.cpp
error: PCH file built from a different branch ((clang-1400.0.29.102)) than the compiler ()
1 error generated.

I think hdoc should disable PCH to work around this issue.

Feature request: I would like to be able to exclude certain symbols, or symbols under certain namespaces, from the documentation and search index.

This is one of the only remaining things I have to maintain in a patch: https://github.com/foxglove/mcap/blob/a85bd00295255b134f3083efbc5d2274294a83df/cpp/hdoc.patch

It would be great to specify an exclusion pattern in the config file, preferably using regular expressions for maximum flexibility. As an example:

[ignore]
ignore_records = "^(.*::)?internal::.*$"
ignore_functions = "^(.*::)?internal::.*$"