On Sat, 22 Mar 2025 at 09:53, Simon Schröder via Std-Proposals <
std-proposals_at_[hidden]> wrote:

> I don’t fully agree with you, Thiago. C++ also does not have a reference
> compiler and still we write a standard to define the language. The same can
> apply for doc comments. Isn’t there also a committee for tooling? It could
> be in the interest of the tooling group to also unify tooling around
> documentation. This would require a unified syntax in the language.
>

No, it doesn't have to be in the C++ standard for any of the benefits to
happen. The tools that consume those comments are not "C++ implementations"
so are out of scope for the C++ standard. See the first sentence of the
first clause of the standard:
"This document specifies requirements for implementations of the C++
programming language."

Comments do not affect the behaviour of the program as defined by the
abstract machine and the rules of the C++ standard.



>
> However, this also has some major problems: 1) Syntax: it should not
> collide with existing doc comments because they might not follow the
> correct syntax for (to be) standardized tools. A different syntax to
> declare doc comments might make people hesitate to adopt the standardized
> syntax because it is unconventional. 2) Which doc syntax is the best? I
> took a quick glance at JavaDoc and there is some legacy syntax and a new
> syntax featuring markdown. The problem with Markdown is that it has too
> many different incompatible flavors. Which flavor should we use? Or should
> we use reStructuredText? I like the approach of Sphinx Doc, but it is
> currently very complicated to use with inline doc comments (you can use
> Doxygen to extract the doc comments and then feed that into Sphinx). Should
> we fall into the trap of JavaDoc and just use the current fad? (Is Markdown
> a fad? Will it go away eventually and be replaced by something else? How
> should C++ doc comments adapt to that?) I’d expect the C++ community to
> have to specify something that is future proof. This would be a battle of
> who can predict the future best.
>
> I would certainly support having a unified syntax for doc comments. But,
> I’d expect it to take a long time to write a specification that everybody
> agrees on. We have missed the train when Doxygen was the de facto standard.
> Other tools claim to do it better now. And certainly other tools look more
> modern by default.


These are problems that a standard *can* address, by picking a format and
declaring all the others non-conforming (or by allowing all the competing
formats). I don't think doing that belongs in the C++ standard.

A white paper from the tooling study group might be a reasonable delivery
vehicle for it, but somebody would need to do the work, including getting
buy-in from the existing vendors (who aren't necessarily involved with WG21
at present).