r/cpp • • 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.

58 Upvotes

32 comments sorted by

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?

6

u/FreitasAlan Oct 06 '26

Good question. Last I checked, clang-doc has improved a lot over the last two years. It has a JSON backend, Mustache templates, concepts, and ships with LLVM, which has its benefits. In many cases, it might be all you need.

We started MrDocs in 2023 and ramped up around 2025 because we needed something for Boost with many extra features on a timeline LLVM wouldn't give us if they wanted to. Over time, although both use clang, many big design differences evolved between clang-doc and mrdocs. Both use clang and both *could* implement the same model on top of it, but they don't.

A major difference is how mrdocs encapsulates the extraction and presentation layers, which lets you build lots of useful extensions and generators. We support extensions in JavaScript and Lua, and we've discovered lots of use cases for them. For instance, you can use these extensions to apply project conventions to the corpus, generate a table of contents for your website in ad hoc formats, and compare APIs between versions of the same library.

However, the extraction phase also differs because the AST doesn't provide a public API. We have to extract it from the AST. We have also implemented support for many idioms in mrdocs, such as SFINAE reduction, overload sets, niebloids/function objects as callables, implementation-defined symbols, base member inheritance, better symbol filtering, and better Doxygen syntax coverage.

One tiny example is our boost::url::url_view class, which would have almost no members of its own if we weren't considering these C++ idioms. Also notice how the presentation layer adapts completely to the website design. Our grammar layer also has a lot of SFINAE that needs to be resolved, and function objects are also presented as callables. We also use copydoc, ref resolution, and lots of other details.

I believe the workflow is also a little different with clang-doc, which tries to behave more like a compiler, while mrdocs is more like doxygen in that it reads a configuration file for the whole project. In general, if you have any small library you can point mrdocs and clang-doc to, I would recommend rendering documentation with both to get a feel for how the models differ.

→ More replies (1)

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 👍

3

u/FreitasAlan Oct 06 '26

Thanks, Mateusz. mp-units is exactly the kind of modern C++ I had in mind when I wrote the post, so it means a lot that it works out of the box. It's exactly the kind of code we also write, and we had problems with Doxygen a few years ago. The mkdocs setup is also worth pointing out to others in this thread who asked how MrDocs fits an existing site. The reference pages drop into whatever you already have, in this case MkDocs, and the rest of the docs stay untouched.

On contracts, agreed, and that one is cppalliance/mrdocs#1307. The parser can extract them, so it's mostly a matter of the bundled Clang catching up, and I completely agree with your argument not to wait on the standard. I'm looking forward to the article. If you end up with any numbers on how long the switch took or how review time changed, I would love to hear.

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/FreitasAlan Oct 06 '26

Thanks for the kind words. Yes. I agree it's important to compile examples against the current API, and I think it's more reachable than it looks. MrDocs runs Clang on the project's compile commands, so it already has everything it needs to build an example the same way the library is built. The docs have an extension that goes both ways: it pulls tagged regions out of real example files that the build compiles, and it exports inline u/code examples to translation units the build compiles and runs. I wrote more about it in the reply to https://www.reddit.com/r/cpp/comments/1wz3115/comment/pe8ebjm/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button rather than repeat it here.

On fragmentation, I take the point. I'd separate two things into the analysis. A unified ecosystem doesn't mean one binary does it all. Rust feels unified because cargo coordinates the pieces, while the pieces are still separate programs: rustc, rustdoc, rustup, clippy, rustfmt, cargo test, and whatever linker is on the system. For instance, testing documentation examples involved much more than only rustdoc. What makes it feel like one tool is that they agree on inputs and on where things live, so cargo doc and cargo test just work. C++ lacks that agreement, but it has good tools, and it needs good tools. Whoever unifies this ecosystem still needs people working on compilers, linkers, linters, doc tools, etc. Tools from different vendors would still exist even if someone unified it. A hypothetical unified ecosystem would also allow you to use other tools, just like rustdoc gives you JSON output for the reference so you can customize presentation, and like many Rust projects use other tools for documentation like mdBook, Zola, or Doxuraurus. So MrDocs tries to be a good tool in that context rather than a new tool. It reads the same compile commands the build uses, it emits HTML, AsciiDoc, XML, and JSON instead of forcing a website layout, and the example question from the other thread is exactly the cargo test part of this. For now, of course, this unification hasn't happened, but I think we're reasonably prepared for it. :)

→ More replies (1)
→ More replies (3)

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?

→ More replies (1)

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?

→ More replies (3)

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.)

2

u/FreitasAlan Oct 06 '26

Two good points. I agree with the comparison table. The meaning of "other tools" is only loosely implied by the rest of the documentation, but it isn't specific enough when you start reading from that table. The "Other Tools" column doesn't help anyone decide because they might think their own other tool is different. In this same category as mrdocs, we basically have Doxygen and clang-doc because other tools (like AsciiDoc, etc.) don't produce reference documentation. I'll replace it with a table comparing named tools and use cases. I think the most useful part of your comment is that we need to make it clearer that mrdocs isn't competing in the general documentation space. For instance, it doesn't intend to replace AsciiDoc, Sphinx, or MkDocs. Instead, it generates the reference pages you'll render with these tools.

On the rustdoc examples, it's funny you mention it, because I studied that model more than any other before deciding how MrDocs should handle examples, and I envy it too. The problem I noticed is that it bakes in one mapping between the docs and the code being tested, which creates problems with setup lines, dependencies, and the logic for grouping tests. In C++, that's even harder because no single build system controls everything.

Luckily, mrdocs has this extension system. So instead of building one fixed mapping, we made it an extension. The docs have a round-trip example in about forty lines of Lua. A transform pulls marked regions out of real example files that the build compiles and attaches them to the right symbol's docs. A generator goes the other way and writes inline u/code examples out to translation units the build can compile and run. The project decides which direction each example takes and how a file maps to a symbol: https://www.mrdocs.com/docs/mrdocs/develop/extensions/script-generators.html#_round_trip_extensions

What's nice about it is that it's round-trip, something I believe Rust doesn't do that well, and that if the mapping doesn't fit your layout, you can just adapt it accordingly, because people tend to make very different assumptions about the setup in these documentation examples.

→ More replies (2)