C++ Logo

std-proposals

Advanced search

Re: [std-proposals] Standardizing Code Documentation

From: Jens Maurer <jens.maurer_at_[hidden]>
Date: Fri, 27 Jun 2025 10:06:15 +0200
On 27.06.25 09:45, Simon Schröder via Std-Proposals wrote:
> Concerning visibility of comments (https://en.cppreference.com/w/cpp/language/translation_phases.html <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 intend to specify in the standard that comments can contains
stuff that the compiler needs to "see" (e.g. to give errors on
"bad" content), we certainly need a change to [lex.phases] and
probably represent the contents of comments as tokens of some
form.

In any case, I'm opposed to putting rules about comment content into the standard
proper. I wouldn't be opposed to have a separate TR/TS/standard/whatever
that specifies e.g. the Doxygen rules for cross-language use.
(Whether it's worth the effort and bother to get the necessary
industry buy-in, I'm skeptical.)

Jens

Received on 2025-06-27 08:06:20