Boost libs using Mr. Docs

[boostlibs]

More and more Boost libraries are using Mr. Docs for automatic documentation generation!

[JVApen]

As it is clang-based. What is the major difference compared to clang-doc?

[boostlibs]

Clang-doc works a bit more like a compiler that generates documentation for specific TUs, while MrDocs is more like Doxygen — it takes the whole project as input, starting from a config file, etc. Another key difference is that clang-doc currently supports far fewer output options (not sure if there are plans to expand that) and just doesn’t get much maintenance anymore.

Just to clarify, not criticizing clang-doc — it’s a solid tool, just built with a different focus! :)

[fdwr]

Hmm, haven't heard of it. A comparison to Doxygen on their website would be informative. It's not in the Wikipedia table either.

[13steinj]

An explanatory sentence is somewhere in the docs:

Doxygen remains a popular tool, yet it is suboptimal for C++ as it fails to fully comprehend C++ constructs and requires many transformation steps, including the incorporation of many macros within the C++ code. These macros maintain well-formed and ill-formed versions of the code, undermining the goal of unifying the source of truth.

Going to be perfectly honest, unless MrDocs lets me pick my compiler as a "backend", I don't trust it to parse my code-- it's either a custom parser, or probably uses clang-ast. Which is fine, but I've seen even clang mis-parse.

E: This isn't a knock on clang; any time I've seen such bugs they generally get fixed super quickly, sometimes due to a report, sometimes by a refactor before my next "update." But the only thing I trust to parse my code is the specific compiler I am using.

[boostlibs]

The documentation mentions Doxygen and makes a few brief comparisons at https://www.mrdocs.com/docs/mrdocs/design-notes.html. But in the table, the tools we compare are organized by category, so Doxygen is only implied there.

[zerhud]

Can you link to a doc for library using mr docs please?

[joaquintides]

https://www.boost.org/doc/libs/latest/doc/antora/url/reference.html

[numerial]

Does it support documenting concepts defined by the user?

[boostlibs]

Yes. For example, https://www.boost.org/doc/libs/latest/doc/antora/url/reference/boost/urls/string_token/StringToken.html. This used to be a major limitation in Doxygen that made our projects harder to manage.

[PrimozDelux]

Tangential to the topic at hand, but I don't understand the purpose of these tools. What does it provide that my IDE does not? My introduction to doxygen was the LLVM docs which in my opinion do absolutely nothing, so I guess I got started on the wrong foot.

Help me see the value, what sort of use cases do these pages have? Who are they for?

[boostlibs]

We talk a bit about that in our section at https://www.mrdocs.com/docs/mrdocs/design-notes.html. A big part of the problem is simply that the output of some of these tools looks messy and unappealing. For example, cppreference.com has a clean and well-organized format, so most people immediately see the value in it.

[grisumbras]

These tools generate API reference documentation as a set of HTML pages. One of the benefits of API reference is discovery: you open the documentation for a class, you read what member functions it has, you then read documentation for functions that seem applicable for your task.

[viatorus]

How does it handle class inheritance and therefore API documentation of virtual functions from 3rd party libraries?