add optional description to @time and new @showtime macro

base/exports.jl

@@ -992,6 +992,7 @@ export
 
     # profiling
     @time,
+    @showtime,
     @timed,
     @timev,
     @elapsed,

base/timing.jl

@@ -175,18 +175,21 @@ macro __tryfinally(ex, fin)
 end
 
 """
-    @time
+    @time expr
+    @time "description" expr
 
 A macro to execute an expression, printing the time it took to execute, the number of
 allocations, and the total number of bytes its execution caused to be allocated, before
 returning the value of the expression. Any time spent garbage collecting (gc) or
 compiling is shown as a percentage.
 
+Optionally provide a description string to print before the time report.
+
 In some cases the system will look inside the `@time` expression and compile some of the
 called code before execution of the top-level expression begins. When that happens, some
 compilation time will not be counted. To include this time you can run `@time @eval ...`.
 
-See also [`@timev`](@ref), [`@timed`](@ref), [`@elapsed`](@ref), and
+See also [`@showtime`](@ref), [`@timev`](@ref), [`@timed`](@ref), [`@elapsed`](@ref), and
 [`@allocated`](@ref).
 
 !!! note
@@ -209,9 +212,20 @@ julia> @time begin
        end
   0.301395 seconds (8 allocations: 336 bytes)
 2
+
+julia> @time "A one second sleep" sleep(1)
+A one second sleep ->  1.003785 seconds (4 allocations: 128 bytes)
+
 ```
 """
-macro time(ex)
+macro time(ex...)
+    if length(ex) == 2 && ex[1] isa String
+        msg, ex = ex
+    elseif length(ex) == 1
+        msg, ex = nothing, ex[1]
+    else
+        error("Incorrect format used with @time. Valid forms are `@time expr` or `@time \"msg\" expr`")
+    end
     quote
         @compile
         local stats = gc_num()
@@ -222,18 +236,41 @@ macro time(ex)
             compile_elapsedtime = cumulative_compile_time_ns_after() - compile_elapsedtime)
         )
         local diff = GC_Diff(gc_num(), stats)
+        isnothing($msg) || print($msg, " ->")
         time_print(elapsedtime, diff.allocd, diff.total_time, gc_alloc_count(diff), compile_elapsedtime, true)
         val
     end
 end
 
 """
-    @timev
+    @showtime expr
+
+Like `@time` but also prints the expression being evaluated for reference.
+
+See also [`@time`](@ref).
+
+```julia-repl
+julia> @showtime sleep(1)
+sleep(1) ->  1.002164 seconds (4 allocations: 128 bytes)
+
+```
+"""
+macro showtime(ex)
+    quote
+        @time $(sprint(show_unquoted,ex)) $(esc(ex))
+    end
+end
+
+"""
+    @timev expr
+    @timev "description" expr
 
 This is a verbose version of the `@time` macro. It first prints the same information as
 `@time`, then any non-zero memory allocation counters, and then returns the value of the
 expression.
 
+Optionally provide a description string to print before the time report.
+
 See also [`@time`](@ref), [`@timed`](@ref), [`@elapsed`](@ref), and
 [`@allocated`](@ref).
 
@@ -258,7 +295,14 @@ bytes allocated:   896
 pool allocs:       1
 ```
 """
-macro timev(ex)
+macro timev(ex...)
+    if length(ex) == 2 && ex[1] isa String
+        msg, ex = ex
+    elseif length(ex) == 1
+        msg, ex = nothing, ex[1]
+    else
+        error("Incorrect format used with @timev. Valid forms are `@timev expr` or `@timev \"msg\" expr`")
+    end
     quote
         @compile
         local stats = gc_num()
@@ -269,6 +313,7 @@ macro timev(ex)
             compile_elapsedtime = cumulative_compile_time_ns_after() - compile_elapsedtime)
         )
         local diff = GC_Diff(gc_num(), stats)
+        isnothing($msg) || print($msg, " ->")
         timev_print(elapsedtime, diff, compile_elapsedtime)
         val
     end