On Tue, 24 Jun 2025 at 11:47, Simon Schröder via Std-Proposals <
std-proposals_at_[hidden]> wrote:

> I believe that it would be a good part if C++ would handle PARSING for
> documentation. A [[doc]] attribute would be much better than regular
> comments (which could be documentation or just plain comments).
>

Just like we have @param as a convention, we also have /** or /// as a
convention for documentation comments that are not "plain" comments.



> Parsing C++ is the hard part and it constantly changes with each new
> standard. Why would e.g. Doxygen constantly have to change their parser to
> understand the most current C++?
>

Doxygen uses libclang, doesn't it?


> Should I wait to adopt new C++ features until they can also be parsed by
> the documentation tool?
>

Instead you have to wait longer for new C++ features to even be supported
in your compiler, because now your compiler devs also have to maintain the
doc tooling?


> I would say, we don't need to specify the syntax of the documentation, but
> if the compiler can extract these, it would be really nice. It could output
> the documentation to e.g. json to have a connection between the
> documentation text and the function signature, the class name, or whatever.
> Parsing JSON would be a lot easier for Doxygen and it would not have to
> adapt to any new C++ standard (at least most of the time).
>

How would the JSON docs be linked back to some declaration? What if that
declaration is something the doc tooling doesn't understand yet, like a
concept or a module? I don't see how this really insulates the doc tooling
from new C++ features in new standards. Would the JSON just contain a plain
text declaration that the doc tooling can display verbatim, with no
additional context? (e.g. not linking the return type to the docs for that
return type?)