One other thing that just occurred to me is that the best documentation tool to annotate classes and functions needs to understand the surrounding programming language. All tools try to extract the function signature or the member functions of a class. This will get harder and harder the more language features are added. Most tools just use a heuristic. I think it would be a good idea to let the compiler do the extraction. We should then specify an intermediate format, e.g. json, that the compiler writes to. Documentation tools would just need to be able to parse this intermediate format that is well structured without being able to parse the language. If the language changes and adds a new attribute/keyword to the intermediate format older tools could just skip everything they don’t understand.

BTW, I think it would be useful if we could write internal docs (e.g. for library developers) and external API docs (for the user of the library) as doc comments inside the same source code. Sometimes I like to describe the strategy or the algorithm that is not for the user, but it is just internal. It wouldn’t be in many places, but it would still be helpful. This might especially helpful for open source projects for people to navigate internal documentation the same way we already do it as users of libraries.

> On Mar 22, 2025, at 1:30 PM, Jan Schultke via Std-Proposals <std-proposals_at_[hidden]> wrote:
>
> I've discussed this with a number of people during the last days, and
> here are my thoughts:
>
> - I'm not convinced that the status quo is so good that we don't need
> to bother with standardization. Many tools support doc comments one
> way or the other, but such support is often limited and inconsistent.
> IntelliSense displays Doxygen comments in tooltips that clangd
> doesn't, for example.
>
> - A whitepaper by the Tooling SG seems like the right feature for
> this. It could be part of the core language spec if it had semantic
> effects, like @deprecated tags behaving equivalently to
> [[deprecated]], but I think that's too controversial anyway.
>
> - Doxygen is a quasi-standard, but has tons of tags with varying
> support from other tooling. The goal would be to define a common
> syntax and set of doc comment tags that we expect all documentation
> tools (that care) to support. It's also not always clear to which
> construct a doc comment can be used.
>
> - I don't think that Markdown is a fad. It's definitely a good tool
> for this job and isn't going away anytime soon. If we were to support
> Markdown, there exists the CommonMark standard. Anything beyond that
> would be non-standard. It's not clear that we need to specify what the
> contents of doc comments are anyway. We could just standardize the
> basic syntax, which C++ constructors the comments apply to, and what
> tags inside are supported. Making them display pretty could then be
> QoI.
>
> - Regarding syntax: the best bet is probably to standardize "///" and
> "/**" as doc comments, and Javadoc-style "@param" etc. These are the
> greatest common denominator for tooling.
>
> - TODO, FIXME, etc. aren't doc comments. NOLINT, clang-format off,
> etc. are all outside the scope of such standardization in my opinion,
> or at least, it would make it much harder to standardize if we don't
> focus on a specific issue, like just doc comments.
> --
> Std-Proposals mailing list
> Std-Proposals_at_[hidden]
> https://lists.isocpp.org/mailman/listinfo.cgi/std-proposals