AW: [std-proposals] Standardizing Code Documentation

I believe that it would be a good part if C++ would handle PARSING for documentation. A [[doc]] attribute would be much better than regular comments (which could be documentation or just plain comments). Parsing C++ is the hard part and it constantly changes with each new standard. Why would e.g. Doxygen constantly have to change their parser to understand the most current C++? Should I wait to adopt new C++ features until they can also be parsed by the documentation tool?

I would say, we don't need to specify the syntax of the documentation, but if the compiler can extract these, it would be really nice. It could output the documentation to e.g. json to have a connection between the documentation text and the function signature, the class name, or whatever. Parsing JSON would be a lot easier for Doxygen and it would not have to adapt to any new C++ standard (at least most of the time).

On Tue, Jun 24, 2025 at 12:25 PM Tiago Freire via Std-Proposals <std-proposals@lists.isocpp.org> wrote:

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@lists.isocpp.org> on behalf of Jonathan Wakely via Std-Proposals <std-proposals@lists.isocpp.org>
Sent: Tuesday, June 24, 2025 12:07:41 PM
To: C++ Proposals <std-proposals@lists.isocpp.org>
Cc: Jonathan Wakely <cxx@kayari.org>
Subject: Re: [std-proposals] Standardizing Code Documentation

On Tue, 24 Jun 2025, 10:15 Siddharth Mohanty via Std-Proposals, <std-proposals@lists.isocpp.org> 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.

--
Std-Proposals mailing list
Std-Proposals@lists.isocpp.org
https://lists.isocpp.org/mailman/listinfo.cgi/std-proposals