C++ Logo

std-proposals

Advanced search

Re: [std-proposals] Standardizing Code Documentation

From: Simon Schröder <dr.simon.schroeder_at_[hidden]>
Date: Sat, 28 Jun 2025 09:40:55 +0200

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

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.

Received on 2025-06-28 07:41:09