I'm currently pro annotations and against comments. It is nice that
libclang can retain the comments. However, the standard right now does not
require this (it seems like this is almost contrary to the standard). I
don't say this is impossible, but if we want to specify doc comments in C++
we need to change the translations phases as well.

For documentation I just need the structure of the program, i.e. no
implementations of functions. The structure can also just be known within
the current compilation unit and its context. With annotations we only need
to write out the symbols that have [[doc]] annotations (with additional
text inside the [[doc]] annotation like previously suggested). With
comments (if we don't specify how doc comments are introduced) we need to
export all symbols that kind of have a comment associated (it doesn't
matter if it is a doc comment or not). Annotations also already belong to a
symbol, where with comments it's just some sort of convention.

I had to google the suggested Swagger JSON/YAML myself (
https://swagger.io/docs/specification/v3_0/basic-structure/). It is an API
specification standard designed for web usage. Some of it is not relevant
for C++ and I'm not sure if it handles everything from C++.

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

> The metaprogramming proposals on top of reflection (last time I saw) where
> going into the direction of: The C++ code is the truth instead of a more
> abstract description of program code.
>
> Perhaps somebody can correct me, if that is no longer the case (or never
> actually was).
>
>
>
> The e.g. JSON you are suggesting - would it describe the whole program in
> a differently structured form (= it could be converted back to working C++)
> or just describe the overall structure (defined entities like functions,
> classes, parameters, ...)?
>
>
>
> So actually you want two things:
>
> - Comments, which are not stripped. Jonathan mentioned, that libclang can
> do that, and so attributes would not be strictly necessary, but could be
> advantageous
>
> - A pre-parsed / converted C++ program or at least structure of the
> program in e.g. JSON format, predominantly for documentation purposes
>
>
>
> Siddarth additionally proposes
>
> - comments being interpreted into code, e.g. contracts, but perhaps even
> full-blown metaprogramming
>
>
>
>
> Being able to more closely interweave code and documentation reminds me of
> D.E. Knuth's philosophy. See also
> https://de.wikipedia.org/wiki/Literate_Programming (von WEB über die
> Weise, wie viele LaTeX-Packages geschrieben sind, bis hin zu heutigen
> Jupyter notebooks).
>
>
>
>
>
> -----Ursprüngliche Nachricht-----
> *Von:* Simon Schröder via Std-Proposals <std-proposals_at_[hidden]>
> *Gesendet:* Di 24.06.2025 15:30
> *Betreff:* Re: [std-proposals] Standardizing Code Documentation
> *An:* std-proposals_at_[hidden];
> *CC:* Simon Schröder <dr.simon.schroeder_at_[hidden]>;
>
> 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/).
>
>
> --
> 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
>