I can have to agree with Thiago.
Documentation should be opaque to the C++ language, how the code works shouldn't care about the description.
So, in effect should work like a comment, which how most doc tools work.
The C++ standard shouldn't have to standardize everything. Documentation frameworks such a doxygen are so widespread that they are integrated into almost every modern code editor with a good expectation that they would work.

You don't need to write it into the C++ standard for doxygen to be an informal industry standard.
The only thing the C++ standard should do in this case is to allow for those derived works to exist, which it already does without having to do anything.

Documentation is irrelevant for the code itself, and only plays a role with peripheral tools, such as editors, document generators, etc...
So, it would make sense that how they would work would closely follow the features of those tools.

And the fact different "syntax" could be used to for different tools, is more power to the core. If we can improve the tools to do it in a better way, then we should allow that, we should allow those tools to evolve unrestrained without them being embroiled in committee discussions, and only slowly be allowed to update every 3 years, or 6 years if you made a mistake.


-----Original Message-----
From: Std-Proposals <std-proposals-bounces_at_lists.isocpp.org> On Behalf Of Simon Schröder via Std-Proposals
Sent: Saturday, March 22, 2025 10:53 AM
To: std-proposals_at_[hidden]
Cc: Simon Schröder <dr.simon.schroeder_at_gmail.com>
Subject: Re: [std-proposals] Standardizing doc comments

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_lists.isocpp.org> 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]pp.org
> https://lists.isocpp.org/mailman/listinfo.cgi/std-proposals
--
Std-Proposals mailing list
Std-Proposals_at_lists.isocpp.org
https://lists.isocpp.org/mailman/listinfo.cgi/std-proposals