On Tue, Jun 24, 2025 at 3:01 PM Peter Bindels via Std-Proposals <
std-proposals_at_[hidden]> wrote:

> and ideally output documentation with C++26 reflection.
>

I also thought about reflection to get documentation from (user-defined)
attributes. Can we already write to files in compile time code?

@Sebastian: I can only speak for myself what I would expect. Currently,
different doc tools have different ways to introduce doc comments. Using
attributes instead could unify this approach without preferring a single
tool. (Also, attributes could work with a reflection-based library.)
Furthermore, syntax like @param is not standardized among tools. I
personally don't want to standardize the syntax itself (at least not as
part of C++). With the annotation C++ could produce JSON (and we'd
standardize the JSON output) and just dump the [[doc]] string together with
useful information (e.g. function name, function parameter names and types,
return type) to be processed by a doc tool. C++ would not have to
understand any doc syntax. (This might be different from what Siddharth
wants.) BTW, if I'm not mistaken at the translation phase where additional
information (like the function name or even the fact that this line
declares a function) is available, comments are already stripped, but
annotations are still available. In that regard annotations would be easier
to integrate than comments.

Maybe, if we can implement everything using reflection, this discussion is
mostly superfluous (except for getting the idea to use reflection). Though
going down this route is quite interesting, I'm not entirely sure if this
is the best solution to the problem of in situ documentation. I believe
Rust heavily uses something similar to annotations in several libraries. In
this real world example I find it a little overboarding (I have only read
about it, but never written any Rust code). BTW, I just recently learned
that there is a successor language to C (called C3) which uses specialized
comments <* ... *> for documentation and contracts (
https://c3-lang.org/language-fundamentals/comments/).