[pattern matching] I’m not sure how this can be emulated in C++ as of today.

You can have a look at this library developed by renowned people in the C++ community:
https://github.com/solodon4/Mach7

Regarding the use of comments, ideally they should not be required to understand what a new code written from scratch does. But they are really useful to explain the constraints, quote issues/RFC/papers, and tell what the code doesn’t do and why.

Any complex / legacy system tend to have a growing number of comments over time and these comments are precious, sometimes more than the code itself, because they contain the knowledge that was painfully acquired over time. Just have a look at WebKit, the Linux Kernel, LLVM, etc…

My point about automatic tools is not to generated automatic documentation like your example your are mentionning but more to generate template for doxygen (ex : /brief …) and collapse/expand/coloring to avoid noise during code review (agree with you I have seen also “iProID : the id of the Pro” is just a noise)
In my experience if you ask a dev to add manually comments compatible with doxygen + update doc as soon as we change the prototype without any tools you have bugs in doxygen and doc not in line with code.
But in case of very sensitive api dispatch among hundreds of client we need tools to provide information to client but My point of view is comments into the code is too painful due to lack of tooks

I would say it depends on what kind of API you have.
If you have a small API, with your clients including your headers in their code, they will probably read the documentation through their IDE. In which case, it will mainly be read as raw text and nice formatting will be in the way. Some minimalist Doxygen or just raw comments might be a good solution.
For big C++ APIs, I think more advanced Doxygen formatting and upload on the web is the norm, but I might be missing some recent cool tools.
For REST APIs, I hear lot of good things about Swagger.
I don’t really agree with your need for a tool generating documentation automatically. Automatic documentation generation is doomed to be pure noise, in my opinion. I have seen tools documenting “getValueAt(int i)” with “get the value at i”, but it is already in the method’s name. The documentation that interests me is what happens if i is negative or bigger than the number of values and only the implementer can write that.

Indeed fred it is true for a client API
But after to make the choice of documentation comes the choice of tools:
Which tools to use ? Doxygen seems to be the most common one but the generated doc has not the same quality as Sphinx for example in python
Even if you customize well Doxygen you need a lot of plugin to generate doc in your code :
1) you need to have a tools that expand/collapse comments for code review
2) you need to have a way to generate automatically template for doxygen and modify automatically the code when you modify the prototype
Etc/etc
So I do not find any solution generator and tools that has the same kind of level that Sphinx in python for example
At the end due to lack of complete solution about code documentation in C++ no one maintain the documentation
A wiki page I think is more adapted even for client API like a Rest service

Thanks for sharing Jonathan – and glad you found the post useful!