Should there be conditional (if constexpr) comments with either? If reflection and codegen can depend on comments, that could be relevant.   But then, why not directly use attributes for that usage instead of comment attributes?   -----Ursprüngliche Nachricht----- Von:Tiago Freire via Std-Proposals <std-proposals_at_[hidden]> Gesendet:Sa 28.06.2025 14:28 Betreff:Re: [std-proposals] Standardizing Code Documentation An:std-proposals_at_[hidden]; CC:Tiago Freire <tmiguelf_at_[hidden]>; I want to challenge this notion that "if you have a doc parser you have something halfway a C++ parser" or that it has at least to fully understand. This is just not true.   I would expect a doc parser to be able to see multiple alternatives on how things could be compiled, which a compiler doesn't have to do. A C++ interpreter would need to know how to compute the result of operations, casts, lifetimes, etc, while I wouldn't expect a doc parser to go beyond a function signature and some class layouts. Sure, they both have to understand types and functions are, but to think that they have much else in common is not true. I'm not saying that co-opting existing compiler code cannot be used to help a docgen understand code, but they don't have the same goals and surely do not need the same capabilities nor the ability to see code in the same way.       -------------------------------- From: Std-Proposals <std-proposals-bounces_at_[hidden]> on behalf of Simon Schröder via Std-Proposals <std-proposals_at_[hidden]> Sent: Saturday, June 28, 2025 9:41:15 AM To: std-proposals_at_[hidden] <std-proposals_at_[hidden]> Cc: Simon Schröder <dr.simon.schroeder_at_[hidden]> Subject: Re: [std-proposals] Standardizing Code Documentation   On Jun 27, 2025, at 10:31 AM, Jonathan Wakely <cxx_at_[hidden]> wrote:   On Fri, 27 Jun 2025 at 08:46, Simon Schröder via Std-Proposals <std-proposals_at_[hidden] <mailto:std-proposals_at_[hidden]> > wrote: It is nice that you can build tools using libclang. However, I've had a look at it and it is not easy to get started. There are some interesting alternatives to Doxygen out there. It would be even easier to create alternatives if we didn't have to use libclang for this. (It surely is debatable if we should have many different doc tools. I have certainly seen tools that produce nicer or at least more modern documentation than Doxygen. Sphinx Doc comes to mind, but for inline documentation it relies on Doxygen and a bridge which currently makes it too complicated to just use it for smaller/hobby projects.)   Concerning visibility of comments (https://en.cppreference.com/w/cpp/language/translation_phases.html): Translation phase 3 states: "Each comment is replaced by one space character." There is nothing in the standard that requires to still retain the comments (somehow associated with the source code), but it is "required" to delete comments from the code by replacing them by one space character. Only in phase 7 are we doing syntactic and semantic checks and will know if a token is a function or class, etc. If we want to tag functions with a doc comment we need to change the standard that comments are not replaced by one space character in phase 3. It might already work for clang, but if other compilers take the "replace comments by one space character" literally, it might be hard to change the existing compilers to retain the comments just in case they are used for documentation in phase 7.   Which is an argument for not doing this in compilers, but in separate tools. (And then that is an argument for not putting it in the C++ standard.)   For me, this is just the reason to not use comments for documentation, but use annotations instead. Any doc tool still needs to fully understand C++ and thus have a working parser. (Some tools use heuristics, but they also might fail.) If you have a parser you have half a compiler (just without error reporting, optimization, and code gen). Compilers already have to keep annotations around until the proper phase. It would be reasonably simple (compared to other things the compiler has to do) to just export some meta data and the doc annotation string to JSON.   This is also where I disagree with the OP: I would NOT further standardize the syntax of documentations inside the C++ standard. The string inside the doc annotation could contain any syntax and a doc tool could parse it appropriately from JSON.   But, this is also where reflection comes in with the compiler doing the work (through a reflection library) without the compiler actually implementing this feature. Works with doc annotations, doesn’t work with doc comments. -- Std-Proposals mailing list Std-Proposals_at_[hidden] https://lists.isocpp.org/mailman/listinfo.cgi/std-proposals