I'm going to try and make a point with a question.

In what way would a tool like gcc benefit or even change by standardizing a documentation style?

I think the answer is, it wouldn't.
It is not going to have any relevance whatsoever on how code gets interpreted. And I think that is all that matters for the C++ standard.

This is only relevant to tools that don't translate code.
Now this is not to say that it couldn't be standardized in some form, but the document "Programming Languages — C++" is not the right place for it.
I would be open to a different non-normative document similar to an RFC or something.

As it has been mentioned, there are more than one type of tool doing this, some claim to do certain things better than others, and that may be true.
I personally would like to see features like the ability to embed externally linked resources, full-fledged diagrams, html formatting, svg animation support, etc...
This feels like opt-ins for individual users that has nothing to do with making C++ code portable and how it should normatively be interpreted.
It is my opinion that no standardization of any kind should take place in this space by the C++ standard, INTENTIONALLY, in order to allow tool developers unfettered freedom to experiment and develop in this space.

And we know we don't need to do more, because we can make it work today.

-----Original Message-----
From: Std-Proposals <std-proposals-bounces_at_lists.isocpp.org> On Behalf Of Jan Schultke via Std-Proposals
Sent: Saturday, March 22, 2025 1:30 PM
To: std-proposals_at_[hidden]
Cc: Jan Schultke <janschultke_at_[hidden]>
Subject: Re: [std-proposals] Standardizing doc comments

I've discussed this with a number of people during the last days, and here are my thoughts:

- I'm not convinced that the status quo is so good that we don't need to bother with standardization. Many tools support doc comments one way or the other, but such support is often limited and inconsistent.
IntelliSense displays Doxygen comments in tooltips that clangd doesn't, for example.

- A whitepaper by the Tooling SG seems like the right feature for this. It could be part of the core language spec if it had semantic effects, like @deprecated tags behaving equivalently to [[deprecated]], but I think that's too controversial anyway.

- Doxygen is a quasi-standard, but has tons of tags with varying support from other tooling. The goal would be to define a common syntax and set of doc comment tags that we expect all documentation tools (that care) to support. It's also not always clear to which construct a doc comment can be used.

- I don't think that Markdown is a fad. It's definitely a good tool for this job and isn't going away anytime soon. If we were to support Markdown, there exists the CommonMark standard. Anything beyond that would be non-standard. It's not clear that we need to specify what the contents of doc comments are anyway. We could just standardize the basic syntax, which C++ constructors the comments apply to, and what tags inside are supported. Making them display pretty could then be QoI.

- Regarding syntax: the best bet is probably to standardize "///" and "/**" as doc comments, and Javadoc-style "@param" etc. These are the greatest common denominator for tooling.

- TODO, FIXME, etc. aren't doc comments. NOLINT, clang-format off, etc. are all outside the scope of such standardization in my opinion, or at least, it would make it much harder to standardize if we don't focus on a specific issue, like just doc comments.
--
Std-Proposals mailing list
Std-Proposals_at_[hidden]
https://lists.isocpp.org/mailman/listinfo.cgi/std-proposals