Restore @force_compile docs & test (JuliaLang#42785)

* Revert "Revert "Fix docs for `Experimental.@force_compile` (JuliaLang#42760)" (JuliaLang#42784)"

This reverts commit dad4071.

* Truncate test harness from stacktrace

base/experimental.jl

@@ -170,17 +170,18 @@ Force compilation of the block or function (Julia's built-in interpreter is bloc
 # Examples
 
 ```
-module WithPrecompiles
-#=
- code definitions
-=#
-
-if Sys.iswindows()
- Experimental.@compile
- compile_me() # `compile_me` will be compiled before execution
-end
-
-end
+julia> occursin("interpreter", string(stacktrace(begin
+ # with forced compilation
+ Base.Experimental.@force_compile
+ backtrace()
+ end, true)))
+false
+
+julia> occursin("interpreter", string(stacktrace(begin
+ # without forced compilation
+ backtrace()
+ end, true)))
+true
 ```
 """
 macro force_compile() Expr(:meta, :force_compile) end

test/core.jl

@@ -7589,3 +7589,21 @@ end
 
 # avoid impossible normalization (don't try to form Tuple{Complex{String}} here)
 @test Tuple{Complex{T} where String<:T<:String} == Tuple{Complex{T} where String<:T<:String}
+
+# control over compilation/interpreter
+@testset "Experimental.@force_compile" begin
+ function trim_after_eval(str::AbstractString)
+ rng = findfirst("eval(", str)
+ @test !isempty(rng)
+ return str[1:first(rng)-1]
+ end
+ btc = eval(quote
+ Base.Experimental.@force_compile
+ backtrace()
+ end)
+ bti = eval(quote
+ backtrace()
+ end)
+ @test !occursin(r"(interpreter|do_call)", trim_after_eval(string(stacktrace(btc, true))))
+ @test occursin(r"(interpreter|do_call)", trim_after_eval(string(stacktrace(bti, true))))
+end