I can see some form of use for having [[doc]] annotations; the benefit of
Doxygen is that it's almost universal, the biggest downsides IMO are that
it both duplicates what's already in code, and that it uses comments as
meaningful data.

If we had a way to annotate specific parts with annotations, that fixes the
"using comments" part, and allowing omission of parts that are identical to
what the code already says allows me to fix the other half. Having an
argument called `index` that has a contract `index < size()` already says
most of what it should be; I do not want to repeat that in a comment, both
for duplication and for consistency reasons. There is no good way to
annotate order of function calls though, things to call first or after,
object state to have, or what exceptions should be expected from a given
function.

I appreciate a way to specify this, even if it's not in a C++ standard
somehow, so that we can write tools that interact with it, and ideally
output documentation with C++26 reflection.

Thanks for the idea!

On Tue, Jun 24, 2025 at 1:57 PM Jan Schultke via Std-Proposals <
std-proposals_at_[hidden]> wrote:

> I've had a very similar idea a while back, although I'm not sure if
> I've floated it on this mailing list.
>
> The overall take was that such a documentation tool doesn't need to be
> in the C++ standard itself. There may be value in having a separate
> standard which describes the syntax for doc comments also maintained
> through the ISO process, but that's as far as makes sense to
> standardize.
>
> The hard part which is worth standardizing is which specifications
> (@param etc.) exist, what their syntax is, and how they link to C++
> constructs in the declarations below. While Doxygen has established
> itself as sort of a standard, we would really want all tooling to have
> some common, rigorously specified documentation language that's some
> subset of the Doxygen syntax, so that you can rely on certain parts
> working with every linter and other tool that interacts with doc
> comments.
>
> There is very little motivation for this to live in the C++ standard
> directly though, or to have a syntax based on attributes. Doc comments
> seem like a perfect fit for this task. Keep in mind that WG21
> standardizes existing practice if possible, and designing some
> attribute syntax for documentation out of thin air seems like a bad
> fit for standardization.
>
> If you want attributes to do this, feel free to implement such doc
> attributes in a compiler or documentation generator, let that feature
> mature for ten years, and then come back with experience and existing
> practice.
> --
> Std-Proposals mailing list
> Std-Proposals_at_[hidden]
> https://lists.isocpp.org/mailman/listinfo.cgi/std-proposals
>