On Tue, 24 Jun 2025 at 15:41, Simon Schröder via Std-Proposals <
std-proposals_at_[hidden]> wrote:

> I'm currently pro annotations and against comments. It is nice that
> libclang can retain the comments. However, the standard right now does not
> require this (it seems like this is almost contrary to the standard).
>

Of course it isn't contrary to the standard. If libclang is a library for
building tools that work with source code, including compilers and
preprocessors, then it needs to be able to perform the various phases of
translation. Comments aren't removed until phase 3 so a library that could
be used to implement a preprocessor has to be able to start from before
phase 3.


> I don't say this is impossible, but if we want to specify doc comments in
> C++ we need to change the translations phases as well.
>

Why? A tool to extract documentation is not a compiler, it's something
else. So the phases of translation used by C++ compilers aren't relevant.

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



>
> For documentation I just need the structure of the program, i.e. no
> implementations of functions.
>

So not a compiler then.


> The structure can also just be known within the current compilation unit
> and its context. With annotations we only need to write out the symbols
> that have [[doc]] annotations (with additional text inside the [[doc]]
> annotation like previously suggested). With comments (if we don't specify
> how doc comments are introduced) we need to export all symbols that kind of
> have a comment associated (it doesn't matter if it is a doc comment or
> not). Annotations also already belong to a symbol, where with comments it's
> just some sort of convention.
>
> I had to google the suggested Swagger JSON/YAML myself (
> https://swagger.io/docs/specification/v3_0/basic-structure/). It is an
> API specification standard designed for web usage. Some of it is not
> relevant for C++ and I'm not sure if it handles everything from C++.
>
>
>