Merge pull request #2112 from aG0aep6G/ctfe

clarify CTFE spec a bit
merged-on-behalf-of: Petar Kirov <ZombineDev@users.noreply.github.com>

Author: dlang-bot

spec/function.dd

@@ -2199,15 +2199,50 @@ void main()
 $(H2 $(LNAME2 interpretation, Compile Time Function Execution (CTFE)))
 
     $(P Functions which are both portable and free of global side-effects can be
-    executed at compile time. This is useful when constant folding
-    algorithms need to include recursion and looping. Compile time function
-    execution is subject to the following restrictions:
+    executed at compile time. In certain contexts, such compile time execution
+    is guaranteed. It is called Compile Time Function Execution (CTFE) then.
+    The contexts that trigger CTFE are:)
+
+    $(UL
+    $(LI initialization of a static variable or a
+        $(DDSUBLINK spec/enum, manifest_constants, manifest constant))
+    $(LI static initializers of struct/class members)
+    $(LI dimension of a $(DDSUBLINK spec/arrays, static-arrays, static array))
+    $(LI argument for a $(DDSUBLINK spec/template, template_value_parameter,
+        template value parameter))
+    $(LI $(DDSUBLINK spec/version, staticif, `static if`))
+    $(LI $(DDSUBLINK spec/version, staticforeach, `static foreach`))
+    $(LI $(DDSUBLINK spec/version, static-assert, `static assert`))
+    $(LI $(DDSUBLINK spec/statement, mixin-statement,
+        `mixin` statement))
+    $(LI $(DDLINK spec/pragma, Pragmas, `pragma` argument))
     )
 
+$(SPEC_RUNNABLE_EXAMPLE_COMPILE
+---
+enum eval(Args...) = Args[0];
+
+int square(int i)
+{
+    return i * i;
+}
+
+void foo()
+{
+    static j = square(3);      // CTFE
+    writeln(j);
+    assert(square(4));         // run time
+    writeln(eval!(square(5))); // CTFE
+}
+---
+)
+
+    $(P CTFE is subject to the following restrictions:)
+
     $(OL
     $(LI The function source code must be available to the compiler. Functions
         which exist in the source code only as $(D_KEYWORD extern) declarations
-        cannot be executed at compile time.)
+        cannot be executed in CTFE.)
 
     $(LI Executed expressions may not reference any global or local
         static variables.)
@@ -2217,7 +2252,7 @@ $(H2 $(LNAME2 interpretation, Compile Time Function Execution (CTFE)))
     $(LI Non-portable casts (eg, from $(D int[]) to $(D float[])), including
         casts which depend on endianness, are not permitted.
         Casts between signed and unsigned types are permitted)
-    $(LI Reinterpretation of overlapped fields in a Union.)
+    $(LI Reinterpretation of overlapped fields in a Union is not permitted.)
     )
 
     $(P Pointers are permitted in CTFE, provided they are used safely:)
@@ -2289,47 +2324,14 @@ static assert(countTen(6) == 6);    // OK
 static assert(countTen(12) == 12);  // invalid, modifies y.
 ---
     $(P The $(D __ctfe) boolean pseudo-variable, which evaluates to $(D_KEYWORD true)
-        at compile time, but $(D_KEYWORD false) at run time, can be used to provide
+        in CTFE, but $(D_KEYWORD false) otherwise, can be used to provide
         an alternative execution path to avoid operations which are forbidden
-        at compile time. Every usage of $(D __ctfe) is evaluated before
+        in CTFE. Every usage of $(D __ctfe) is evaluated before
         code generation and therefore has no run-time cost, even if no optimizer
         is used.
     )
 
-
-    $(P In order to be executed at compile time, the function
-    must appear in a context where it must be so executed, for
-    example:)
-
-    $(UL
-    $(LI initialization of a static variable or a manifest constant)
-    $(LI dimension of a static array)
-    $(LI argument for a template value parameter)
-    )
-
-$(SPEC_RUNNABLE_EXAMPLE_COMPILE
----
-template eval( A... )
-{
-    const typeof(A[0]) eval = A[0];
-}
-
-int square(int i)
-{
-    return i * i;
-}
-
-void foo()
-{
-    static j = square(3);      // compile time
-    writeln(j);
-    writeln(square(4));        // run time
-    writeln(eval!(square(5))); // compile time
-}
----
-)
-
-    $(P Executing functions at compile time can take considerably
+    $(P Executing functions via CTFE can take considerably
     longer than executing it at run time.
     If the function goes into an infinite loop, it will hang at
     compile time (rather than hanging at run time).
@@ -2339,7 +2341,7 @@ void foo()
     throw exceptions; instead, they end interpretation immediately.
     )
 
-    $(P Functions executed at compile time can give different results
+    $(P Functions executed via CTFE can give different results
     from run time in the following scenarios:
     )
 
@@ -2357,7 +2359,7 @@ void foo()
 
 $(H3 $(LNAME2 string-mixins, String Mixins and Compile Time Function Execution))
 
-        $(P Any functions that execute at compile time must also
+        $(P Any functions that execute in CTFE must also
         be executable at run time. The compile time evaluation of
         a function does the equivalent of running the function at
         run time. This means that the semantics of a function cannot
@@ -2372,11 +2374,13 @@ int foo(char[] s)
 const int x = foo("1");
 ---
 
-        $(P is illegal, because the runtime code for foo() cannot be
+        $(COMMENT Intentionally not a $(P ...) so that it doesn't get a
+        paragraph number, because this continues the paragraph above.)
+        is illegal, because the runtime code for `foo` cannot be
         generated. A function template would be the appropriate
-        method to implement this sort of thing.)
+        method to implement this sort of thing.
 
-$(H3 $(LNAME2 nogc-functions, No-GC Functions))
+$(H2 $(LNAME2 nogc-functions, No-GC Functions))
 
         $(P No-GC functions are functions marked with the $(D @nogc) attribute.
             Those functions do not allocate memory on the GC heap,