I'd like to move away from Doxygen to something more robust

[vinniefalco]

We're using Doxygen's XML output to build an XML database of the C++ program's declarations, and then our own custom XSL toolchain to process that into Boostbook output. Typical javadoc looks like this:

https://github.com/CPPAlliance/url/blob/336917aca8d09b950b85c2cabdd46375aa0f0fb7/include/boost/url/url_view.hpp#L535

And the rendered output from our toolchain:

https://master.url.cpp.al/url/ref/boost__urls__url_view/user.html

We're having more and more problems with Doxygen not recognizing C++ syntax, such as deleted functions or template aliases. And it doesn't pick up markdown in some places, and so on.

Where is standardese in terms of completeness? Is there enough there to support our use-case that we might consider a trial integration? Or does it still need more time? Thanks!

[saraedum]

Where is standardese in terms of completeness?

You should try to run cppast against your code base. It renders your code's AST as XML. If there is nothing missing in there, then standardese might support all the C++ that you are using.

Is there enough there to support our use-case that we might consider a trial integration?

Currently, standardese does not support doxygen syntax but expects comments written in MarkDown (with some additional syntax) so it would be a lot of work to migrate.

I don't use the XML output that standardese produces myself and I doubt it exposes things in a way that makes it easy to process with your XSLT. That said, it's probably not too difficult to write a comment parser that understands doxygen syntax. Once 0.6.0 is out, it's hopefully much easier to write an output generator that creates exactly the XML that you need for your application.

[Freed-Wu]

As a supplement, if you want to publish your document to some website like readthedocs.org, they only have a preinstalled doxygen in their CI/CD machine, while don't have standardese (even cannout apt install because ubuntu doesn't have it). cldoc can be installed from PYPI.

[vinniefalco]

We have developed a replacement for Doxygen for C++ code. It is called "Mr. Docs" and you can learn more here https://mrdocs.com

This is an example Mr. Docs output:

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

[Freed-Wu]

If you can provide some comparison between mrdocs, cldoc, standardese, doxygen in the document, it will be better 😄

[vinniefalco]

cldoc, doxygen, and standardese all use libclang. While Mr. Docs uses Clang's unstable API and thus is as equal in capability for understanding C++ as the very latest clang compiler.

[Freed-Wu]

I notice mrdocs use compile_command.json, otherwise don't use. Why this difference?

[vinniefalco]

I notice mrdocs use compile_command.json, otherwise don't use. Why this difference?

Because Mr. Docs uses clang, it needs to be able to compile your program. For example it needs to know the include paths, the architecture, the macro definitions, and so on. The best way to do this is to make sure that Mr. Docs sees the same command line options as the ones used to build your program (or library). The compile_commands.json captures this information precisely.

We should probably move the discussion here: cppalliance/mrdocs#773 since this has gone off topic.