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

Those separate tools do not need to be constrained by the phases of
translation for a C++ compiler. Even compilers don't need to be constrained
by the phases of translation, footnote 7 makes that clear:
"Implementations behave as if these separate phases occur, although in
practice different phases can be folded together."
An implementation that keeps comments around and just ignores them for the
purposes of code generation is perfectly valid.