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.

On Fri, Jun 27, 2025 at 9:17 AM Thiago Macieira via Std-Proposals <
std-proposals_at_[hidden]> wrote:

> On Thursday, 26 June 2025 23:04:52 Central European Summer Time Jonathan
> Wakely via Std-Proposals wrote:
> > A tool built using libclang doesn't need to be a compiler either, so
> > there's nothing contrary to the standard that says it can't see comments.
> > You could use it to build a preprocessor, in which case obviously it
> needs
> > to see the original source
>
> There's nothing that says the compiler can't see them either. The Standard
> only says that they have no influence in code syntax, but compilers do
> warn
> about things perfectly well-allowed by the standard. How long is it going
> to
> be until compilers apply some AI and warn "your code doesn't match your
> comment" or "you should document this function"
>
> BTW, didn't GCC have support for
> // fallthrough
> comments in falling-through switch cases?
>
> --
> Thiago Macieira - thiago (AT) macieira.info - thiago (AT) kde.org
> Principal Engineer - Intel Platform & System Engineering
>
>
>
> --
> Std-Proposals mailing list
> Std-Proposals_at_[hidden]
> https://lists.isocpp.org/mailman/listinfo.cgi/std-proposals
>