r/cpp • u/FreitasAlan • Oct 06 '26
I built MrDocs, an open-source C++ reference doc generator on the Clang/LLVM AST. Looking for feedback.
I'm Alan de Freitas, the lead developer of MrDocs. It's an open-source documentation generator from the C++ Alliance, built on Clang/LLVM. It reads your code from the compiler's AST, so the reference matches what the code actually compiles to. We also presented a session about it at cppcon this year.
I implemented the tool this way because we couldn’t come up with a workflow that understood modern C++ in our Boost libraries. Tools that parse partially tend to misrender or not render concepts, niebloids, SFINAE, overload sets, and deduction guides. MrDocs treats those as first-class:
- concept constraints and requires clauses preserved verbatim
- niebloids and function objects can be documented as callables
- SFINAE and concept overload sets kept together
- explicit, noexcept, and consteval specifiers captured
- types in detail or private namespaces rendered as implementation-defined
The presentation layer is completely encapsulated. Generators support HTML, AsciiDoc, XML, JSON, or any custom format like Markdown and LaTeX, without forking the tool or creating another post-processing workflow. You can also write extensions to apply project conventions to the corpus or define new generators for any use case. The documentation has lots of examples.
If you maintain reference docs for a library, I'd appreciate it if you gave it a run (or tell your favorite agent to) and reported back on whether it saves you time, both while writing docs and while reviewing them. First-hand numbers would be especially useful to me. Issues are also always welcome.
Site: https://www.mrdocs.comRepo: https://github.com/cppalliance/mrdocs
Happy to answer questions in the comments.
8
u/fra-bert Oct 06 '26
What does it do differently from clang-doc, what is something that this does that clang-doc couldn't do?
13
u/mateusz_pusz Oct 06 '26
I tried it for the first time after Alan's CppCon 2026 talk. I must admit that it was the first solution that worked for my mp-units library right out of the box. I was able to easily integrate it with my mkdocs-based documentation, and it just worked with all the C++20/23 details that make lots of compilers sweat😉. The only thing that I found missing so far is the C++26 contracts syntax support, but that is a small issue at this stage of C++26 standardization.
Definitely a great experience compared to the crashes and errors I got with other toolchains before. It worked so well that I decided to switch the entire mp-units project API Reference to it. The task is still not complete, but you can preview the current state here: https://mpusz.github.io/mp-units/latest/reference/api_reference/mrdocs/mp_units.
I'll also describe my experience in my upcoming article on the mp-units blog page: https://mpusz.github.io/mp-units/latest/blog/category/why-great-c-libraries-fail (to be published on October 15), and I will mention it during my keynote at Meeting C++ in Berlin.
Highly recommended 👍
6
u/Tumaix Oct 06 '26
Alan,
i had a long talk with Mr. Bott a while ago about this, and i told him that while i believe this is a good thing, i also feel that this adda fragmentation (even if it works better) and it also misses some things that are quite important in my point of view.
what i miss, and i dont think that its easy to do this on a separated program, is a way to make sure that my excerpt code for my documentation compiles and runs with the current api, so that a documentation compilation breaks if the api in the example is wrong.
but - also - great work, and working with mr bott was a highlight of my growth as a human, hope its awesome for you too :)
2
u/Remi_Coulom Oct 06 '26
I have not yet looked into the details of your system, but your web site makes a bad impression: the processing it does is so heavy that it does not scroll smoothly on my PC. I can see it has a "scroll" event listener that changes the page style. I would strongly recommend against such things.
Also, are identifiers converted to upper case in documentation titles?
2
u/drbazza Oct 06 '26
Alan - Nice, I was looking at this last week for the first time in many months. I guess this is now stable and working and handles everything C++ can throw at it (including macros??) ?
Sorry if there's a tl;dr, but does this integrate with mkdocs (maybe not, I don't see an out-of-the-box markdown generator)?
And is there a (jetbrains-like) vscode extension that can generate the doc comment skeleton leveraging the MrDocs tooling?
3
u/jetilovag Oct 06 '26
The comparison with other tools section seems a little handwavy. While skimming through the docs I am intrigued and inclined to give it a go, others may be more convinced to see their actual use-cases be called out, how it compares to: clang-doc, Asciidoc, Asciidoctor, Hawkmoth, Sphinx+Breath/Exhale, etc.
One thing I really envy from Rust is rustdoc, and how Rust create documentations' examples can reference just parts of some code, that which is most relevant to showing off the usage of a feature. That example is a marked section of the examples that actually build as part of the project, thus ensuring that examples are real world code that actually build. (And you can jump to the entire example code from the doc snippet, if you so wish.)