As it has been pointed.
Doxygen has become an informal standard that sees a wide support in IDEs. And I would rather that such a thing not be made part of the C++ standard.
You don't need the C++ to standard to make any normative statements on this in order to work, you can have a standard that works in parallel.
Let C++ just be normative regarding how text is interpreted to generate code, for documentation generation let something else do that work.

________________________________
From: Std-Proposals <std-proposals-bounces_at_[hidden]> on behalf of Jonathan Wakely via Std-Proposals <std-proposals_at_[hidden]>
Sent: Tuesday, June 24, 2025 12:07:41 PM
To: C++ Proposals <std-proposals_at_[hidden]>
Cc: Jonathan Wakely <cxx_at_[hidden]>
Subject: Re: [std-proposals] Standardizing Code Documentation



On Tue, 24 Jun 2025, 10:15 Siddharth Mohanty via Std-Proposals, <std-proposals_at_[hidden]<mailto:std-proposals_at_[hidden]>> wrote:

I was thinking about how C++ handles documentation. We currently rely on comment-parsing, but this is flawed since comments aren't a checked part of the language and can easily become inaccurate.

So are you proposing that they be checked?


I'm imagining a simple attribute, maybe [[doc]], that would let the compiler and static-analyzers see and understand documentation. This could lead to much tighter integration with IDEs and better static analysis. This would be reminiscent of the existing [[deprecated]] attribute but instead of a warning, it would be purely informational.

So not checked?


We could even have a syntax like the example below to formalize our conventional doc comments:

[[doc(R"
@brief This function allocates memory on the heap.
@param bytes The number of bytes to allocate.
@return A pointer to the heap or nullptr in case of exception.

Are you proposing to standardize the tags like @param and @return ?

")]]
void *malloc(size_t bytes);

I'd appreciate feedback on whether this is a good enough idea to turn into a proposal.


I'm not seeing a concrete benefit to doing this. Why is it better than the comments we use now?

Is the tighter integration with IDEs and tools likely? Would it enable anything that isn't possible today by inspecting comments? It would still just be loosely structured text, right?

There has been a proposal on this list before to just standardize Doxygen, i.e. using comments rather than your [[doc]] idea.