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_at_[hidden]> 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_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]> 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_at_[hidden]
> https://lists.isocpp.org/mailman/listinfo.cgi/std-proposals
>