Add @timev, @timed documentation [av skip]

[ScottPJones]

This adds documentation for the @timev macro which I added with #11186, as well as documenting the @timed macro, which was already present, but not undocumented.

[tkelman]

number of allocations, and the total number of bytes

[tkelman]

missed this - it's not a verbose version of itself, it's a verbose version of @time

[ScottPJones]

Duh! Sorry!

[yuyichao]

IIRC [ci skip] skips both CI's. It worked on one of my PR's #11260. Probably what you really want.

[tkelman]

Only if you're really sure you pass make check-whitespace locally. Otherwise still good to have Travis check that. It has happened before that a doc commit that was labeled [ci skip] got merged or pushed, but it had trailing whitespace which then caused later commits/PR's to fail.

[yuyichao]

@tkelman Noted.
I have whitespace mode on in emacs so that should help. Probably doesn't hurt to check anyway though...

[yuyichao]

It is probably useful to document the meaning of each line for @timev as well.
Especially since a negetive allocated would be quite confusing (or is it a bug?).

julia> @timev gc()
  18.756 milliseconds (4 allocations: 144 bytes, 99.97% gc time)
elapsed time:    18756225 nanoseconds
gc time:         18749724
bytes allocated: 144
allocated:       -4054608
poolallocs:      4
total allocated: 4054752
pause:           2
full sweep:      1

[ScottPJones]

I'll look at it, it is internally stored as an signed int, and you have to add in a collection value... when it is negative, I think it looks in the pool do do allocations...