[PATCH] document __builtin_is_constant_evaluated

[Martin Sebor]

The attached patch adds the __builtin_is_constant_evaluated newly
introduced in GCC 9 to the Other Builtins section in the manual.

I followed the example of __builtin_setjmp and __builtin_longjmp
by encouraging the use of std::is_constant_evaluated over making
use of the built-in directly.

There have been questions of the value of documenting built-ins
intended to be used by the implementation itself.  There are
good reasons to document all built-ins (and similar extensions)
regardless.  First, the manual is used as a reference not just
by compiler users but also by GCC contributors.  I noticed
the missing documentation while looking for background for a bug
report in pr88977 from a user calling the built-in directly.
(I wanted to check to make sure the built-ins wasn't documented
as experimental or otherwise lacking in expected functionality.)
Documenting a feature as not intended for direct use is better
than not documenting it at all: it makes the intent clear.
Leaving it undocumented and hoping that users won't find it
obviously doesn't work.  Plenty of users read libdstdc++ code,
either while debugging their own programs, or simply out of
curiosity, and so are unavoidably exposed to extensions like
this.  Besides libstdc++ there are also other standard library
implementations that use GCC and that may want to make use of
the built-in.  There are also GCC-compatible compilers that need
to compile libstdc++ code and whose writers need to know about
GCC built-ins.  Many of these writers cannot for IP reasons study
GCC sources (and some may be uncomfortable looking at GCC tests)
and the only information they have access to is the GCC manual.
The absence of documentation makes everyone's work more difficult
and increases the odds that it will be used incorrectly by any of
these users.

Martin
-------------- next part --------------
A non-text attachment was scrubbed...
Name: gcc-doc-is_constant_evaluated.diff
Type: text/x-patch
Size: 1567 bytes
Desc: not available
URL: <http://gcc.gnu.org/pipermail/gcc-patches/attachments/20190213/8fdb49bf/attachment.bin>