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.

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.

> On Mar 21, 2025, at 5:56 PM, Thiago Macieira via Std-Proposals <std-proposals_at_[hidden]> wrote:
>
> On Thursday, 20 March 2025 23:59:33 Pacific Daylight Time Jan Schultke via Std-
> Proposals wrote:
>> Has there been any attempt to standardize doc comments for C++,
>> similar to Javadoc
>> (https://download.java.net/java/early_access/loom/docs/specs/javadoc/doc-com
>> ment-spec.html)?
>>
>> Doxygen-style comments have been existing practice for a long time,
>> and many tools support them to some extent. I could improve UX if we
>> had a standard syntax and a set of standard tags for such comments.
>
> We don't need something in the Standard for this, because the Standard won't
> do anything about it. Unlike Java, there's no reference compiler with a
> reference document generator.
>
> But as you say, we have a de-facto standard. Most IDEs can highlight those
> blocks properly, often parse them to display next to function uses to help
> developers. So I think we have everything we need.
>
> --
> Thiago Macieira - thiago (AT) macieira.info - thiago (AT) kde.org
> Principal Engineer - Intel DCAI Platform & System Engineering
>
>
>
> --
> Std-Proposals mailing list
> Std-Proposals_at_[hidden]
> https://lists.isocpp.org/mailman/listinfo.cgi/std-proposals