[PATCH] document __builtin_is_constant_evaluated

[Martin Sebor]

On 2/15/19 9:01 PM, Sandra Loosemore wrote:
> On 2/13/19 4:33 PM, Martin Sebor wrote:
> 
>> Index: gcc/doc/extend.texi
>> ===================================================================
>> --- gcc/doc/extend.texi    (revision 268856)
>> +++ gcc/doc/extend.texi    (working copy)
>> @@ -12890,6 +12890,22 @@ built-in in this case, because it has no 
>> opportuni
>> Â optimization.
>> Â @end deftypefn
>>
>> +@deftypefn {Built-in Function} bool __builtin_is_constant_evaluated ()
>> +The @code{__builtin_is_constant_evaluated} function is available only
>> +in C++.  Its main use case is to determine whether a @code{constexpr}
>> +function is being called in a @code{constexpr} context.  A call to
>> +the function evaluates to a core constant expression with the value
>> +@code{true} if and only if it occurs within the evaluation of an 
>> expression
>> +or conversion that is manifestly constant-evaluated as defined in the 
>> C++
>> +standard.  Manifestly constant-evaluated contexts include 
>> constant-expressions,
>> +the conditions of @code{constexpr if} statements, 
>> constraint-expresions, and
> 
> s/expresions/expressions/
> 
>> +initializers of variables usable in constant expressions.  The 
>> built-in is
>> +intended to be used by implementations of the 
>> @code{std::is_constant_evaluated}
>> +C++ function.  Programs should make use of the latter function rather 
>> than
>> +invoking the built-in directly.  For more details refer to the latest 
>> revision
>> +of the C++ standard.
>> +@end deftypefn
>> +
>> Â @deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, 
>> long @var{c})
>> Â @opindex fprofile-arcs
>> Â You may use @code{__builtin_expect} to provide the compiler with
> 
> I think this is generally reasonable (and I agree with the rationale for 
> documenting this at all), but I'd like to see this rearranged and 
> rephrased to put the most important point (it's an internal hook to 
> implement std::is_constant_evaluated and shouldn't be called directly) 
> before the technical details, with a paragraph break in between.

Attached is a revision with this rearrangement.

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