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