Having documents tied to compilation is not my usual experience at all.
When you have cross-platform code, and there are variations between platforms and compilation flags, I want those to be documented into a form that I can publish to a webpage that my users can consult.

And maybe I want to experiment with my tools like add special features for cross-linking information and css3 support.

There's nothing wrong with trying to come up with a standard to do documentations that can be added on top of C++, but that standard doesn't have to be the C++ standard itself.

It's a big pass for me.

________________________________
From: Std-Proposals <std-proposals-bounces_at_[hidden]> on behalf of Sebastian Wittmeier via Std-Proposals <std-proposals_at_[hidden]>
Sent: Tuesday, June 24, 2025 4:13:07 PM
To: std-proposals_at_[hidden]cpp.org <std-proposals_at_[hidden]>
Cc: Sebastian Wittmeier <wittmeier_at_[hidden]>
Subject: Re: [std-proposals] Standardizing Code Documentation


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]g;
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]<mailto: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