1. The end goal of my proposal is to have more formal
documentation(allowing C++ code in docs) so that the documentation can
generate the code rather than human developers writing docs based on the
code they write. This would be a benefit to developers in the future since
the docs would be the source of truth, defining intended behavior and
actual code execution.
2. The better connection enabled by attributes would better position docs
to act as the source of truth since comments are fragile and depend on
positioning.
3./4/ The actual implementation of the standard isn't yet a concern of mine
at this stage, I was just floating this idea to see what the reception
would be like.

On Tue, Jun 24, 2025 at 4:07 AM Sebastian Wittmeier via Std-Proposals <
std-proposals_at_[hidden]> wrote:

> I think the current standard specifies full well, what parts of the
> translation unit is a comment and which parts are the actual code.
>
> So you could e.g. deduce a tool from the standard, which inserts two
> markers: Comment start, comment stop.
>
>
>
> Could Siddharth and you, Simon, elaborate, what you want to get beyond
> this distinction?
>
> - A better guarantee that current comments are not used as code in future
> C++ versions? I think that the standard progression is quite conservative
> in this regards to make sure not to change the meaning of existing programs
>
> - A better connection of comments to actual C++ entities?
>
> - The tooling itself, but the standard is fine for specifying?
>
> - Output of the code structure / parse tree? And the comments on top of
> it?
>
> - Something else?
>
>
> -----Ursprüngliche Nachricht-----
> *Von:* Simon Schröder via Std-Proposals <std-proposals_at_[hidden]>
> *Gesendet:* Di 24.06.2025 12:47
> *Betreff:* Re: [std-proposals] Standardizing Code Documentation
> *An:* std-proposals_at_[hidden];
> *CC:* Simon Schröder <dr.simon.schroeder_at_[hidden]>;
> 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
>
> --
> Std-Proposals mailing list
> Std-Proposals_at_[hidden]
> https://lists.isocpp.org/mailman/listinfo.cgi/std-proposals
>
> --
> Std-Proposals mailing list
> Std-Proposals_at_[hidden]
> https://lists.isocpp.org/mailman/listinfo.cgi/std-proposals
>