On Tue, Jun 24, 2025 at 9:08 AM Siddharth Mohanty via Std-Proposals
<std-proposals_at_[hidden]> wrote:
>
> 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.

I don't see anything from your proposal that wouldn't be possible with
the existing pseudo-standard. Even doc-comments inside of source code
can be parsed if you want. Clang's front end can retain comments
(which is how Doxygen can use it).

> 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.

So, slightly fewer errors. Except attributes are less flexible.

One thing that Doxygen allows you to do is to write a parameter and
document that parameter after it appears in the parameter list. It's
been a while since I used it, but it looks something like:

```
void func(
  int first_param /**< documentation for `first_param` **/
  ,int second param /**< documentation for `second_param` **/
)
```

The same is true of documentation for enumerators in an enumeration.
But that's even harder for attributes, as their documentation comes
after any `= value` constructs.

Attribute attachment rules don't really allow for that.

> 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.