Tool to generate code docs

Clang Frontend
1

Hi team clang,

I am interested in developing a tool to generate code documentation. So I am wondering if this project already exists and I could collaborate with you. If not, I can start this project and I would still love to collaborate with anyone who’s interested.

Kindly,

Anshil

2

Seems there might already be one under the clang umbrella:
https://clang.llvm.org/extra/clang-doc.html - but I'm not sure how old
it is and whether it's being actively developed.

3

Thanks, I’ll check it out.

4

I’d recommend Julie’s lighting talk from 2018 LLVM Developers’ Meeting: “clang-doc: an elegant generator for more civilized documentation” to learn more about the tool.

We have a bot that continuously builds and publishes HTML documentation generated from Fuchsia’s codebase to fuchsia-docs.firebaseapp.com/cpp/ to ensure that the tool keeps working. The tools itself has been stable and performant. However, if you open that site, you’ll probably notice that the generated output needs some work (try https://fuchsia-docs.firebaseapp.com/cpp/zx/index.html to see a more concrete example).

What we really need is someone with HTML, JS and CSS experience. For example, the navigation is currently loaded synchronously and always rendered in its entirety which is a problem for larger projects, which is why the page load takes so long for the link I gave above. The content itself also lacks any styling. Unfortunately, we don’t have that experience on our team and we could really use some help here.

I’m happy to review clang-doc changes if this is something you’d be interested in contributing to.

5

There's also GitHub - standardese/standardese: A (work-in-progress) nextgen Doxygen for C++

6

I’d recommend https://llvm.org/docs/GettingStarted.html which is a useful starting point.

clang-doc is a part of clang-tools-extra, so to build it you can use:

git clone https://github.com/llvm/llvm-project.git
cd llvm-project
mkdir build
cd build
cmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS -DLLVM_ENABLE_PROJECTS=‘clang;clang-tools-extra’ …/llvm

ninja clang-doc

To use it, you can use the compilation database (see https://clang.llvm.org/docs/JSONCompilationDatabase.html for more information on compilation databse) generated by the command above as:

./bin/clang-doc --format=html --output=docs compile_commands.json

This generates documentation for LLVM, clang and clang-tools-extra in the docs directory.

Once you have a patch, I’d recommend following https://llvm.org/docs/Contributing.html.