update docstrings

cormullion · cormullion · commit ceac4658c541 · 2018-05-25T17:54:14.000+01:00
diff --git a/README.md b/README.md
@@ -2,22 +2,23 @@
 
 ![tick tock](images/ticktock.gif)
 
-
 | **PackageEvaluator** | **Build Status**  |
 |:---:|:---:|
 |[![][pkg-0.6-img]][pkg-0.6-url] [![][pkg-0.7-img]][pkg-0.7-url] | [![][travis-img]][travis-url] [![][appveyor-img]][appveyor-url] [![][codecov-img]][codecov-url] |
 
-This module provides `tick()`, `tock()`, and `tok()` functions. They're similar to the `tic()`, `toc()`, and `toq()` functions that you might find in other technical software. There are also `laptimer()` and `peektimer()` functions that show you current timing activity without stopping any active timers.
+This module provides simple timer functions:
+
+- `tick()`  start a timer
+- `tock()`  stop a timer, show total elapsed time
+- `tok()`   stop a timer, return elapsed seconds
+- `laptimer()` continue timing, show total elapsed time of active timers
+- `peektimer()` continue timing, return elapsed seconds of most recent timer
 
-**Don't use these for timing code execution!** Julia provides much better facilities for measuring performance, ranging from the `@time` and `@elapsed` macros to packages such as [BenchmarkTools.jl](https://github.com/JuliaCI/BenchmarkTools.jl). (And remember, don't time Julia code running in global scope!) The [TimerOutputs.jl](https://github.com/KristofferC/TimerOutputs.jl) package provides tools for timing different sections of a program.
+`laptimer()` and `peektimer()` functions show your current timing activity without stopping any active timers.
 
-## Functions
+**Don't use these for timing code execution!**
 
-- `tick()` start a timer
-- `tock()` stop a timer, show total elapsed time
-- `tok()` stop a timer, return elapsed seconds
-- `peektimer() ` continue timing, return elapsed seconds of most recent timer
-- `laptimer()  ` continue timing, show total elapsed time of active timers
+Julia provides much better facilities for measuring performance, ranging from the `@time` and `@elapsed` macros to packages such as [BenchmarkTools.jl](https://github.com/JuliaCI/BenchmarkTools.jl). (And remember, don't time Julia code running in global scope!) The [TimerOutputs.jl](https://github.com/KristofferC/TimerOutputs.jl) package provides tools for timing different sections of a program.
 
 ## Suggestions for use
 
@@ -93,12 +94,11 @@ Some of this code used to live in Julia Base in the `tic()`, `toc()`, and `toq()
 
 [appveyor-img]: https://ci.appveyor.com/api/projects/status/j4w1iwued4ojsfm6?svg=true
 [appveyor-url]: https://ci.appveyor.com/project/cormullion/ticktock-jl/branch/master
-  
+
 [codecov-img]: https://codecov.io/github/cormullion/TickTock.jl/coverage.svg?branch=master
 [codecov-url]: https://codecov.io/github/cormullion/TickTock.jl
 
 [pkg-0.6-img]: http://pkg.julialang.org/badges/TickTock_0.6.svg
 [pkg-0.6-url]: http://pkg.julialang.org/?pkg=TickTock&ver=0.6
 [pkg-0.7-img]: http://pkg.julialang.org/badges/TickTock_0.7.svg
 [pkg-0.7-url]: http://pkg.julialang.org/?pkg=TickTock&ver=0.7
-
diff --git a/src/TickTock.jl b/src/TickTock.jl
@@ -1,34 +1,32 @@
 """
 This module provides `tick()`, `tock()`, and `tok()` functions.
 
-They're similar to the `tic()`, `toc()`, and `toq()` functions that you might find in MATLAB
-and similar software.
+- `tick()`       ` start a new timer and start counting
+- `tock()`       ` stop counting, show total elapsed time in canonical form
+- `tok()`        ` stop counting, show and return total elapsed time in seconds
+- `peektimer()   ` continue counting, show and return elapsed seconds so far
+- `laptimer()    ` continue counting, show elapsed time so far in canonical form
 
 Don't use these for timing code execution! Julia provides much better facilities for
 measuring performance, ranging from the `@time` and `@elapsed` macros to packages such as
-[BenchmarkTools.jl](https://github.com/JuliaCI/BenchmarkTools.jl). (And remember, don't
-time Julia code running in global scope!)
-
-This code used to live in Julia Base as the `tic()`, `toc()`, and `toq()` functions
-(in base/util.jl). They were deprecated in GitHub issue [17046](https://github.com/JuliaLang/julia/issues/17046).
+[BenchmarkTools.jl](https://github.com/JuliaCI/BenchmarkTools.jl).
 """
 module TickTock
 
 export tick, tock, tok, peektimer, laptimer
 
 if VERSION > v"0.7.0-"
-    using Dates # for now() :(
+    using Dates # for now()
 end
 
 """
     tick()
 
-Start counting. The other functions are:
+Start a timer.
 
-- `tock()`       ` stop counting, show total elapsed time in canonical form
-- `tok()`        ` stop counting, return seconds
-- `peektimer()   ` continue counting, return elapsed seconds
-- `laptimer()    ` continue counting, show total elapsed time in canonical form
+Other functions: `tock()` (stop counting and show canonical), `tok()` (stop
+counting and return seconds), `peektimer()` (continue counting, return elapsed
+seconds), and `laptimer()` (continue counting, show canonical)
 """
 function tick()
     t0 = time_ns()
@@ -60,7 +58,7 @@ end
 """
     peektimer()
 
-Return the current elapsed seconds counted by the most recent timer, without stopping it.
+Return the elapsed seconds counted by the most recent timer, without stopping it.
 """
 function peektimer()
     t1 = time_ns()
@@ -75,7 +73,7 @@ end
 """
     tok()
 
-Return the current elapsed seconds counted by the most recent timer, then stop counting.
+Return the elapsed seconds counted by the most recent timer, then stop counting.
 """
 function tok()
     timers = get(task_local_storage(), :TIMERS, ())
@@ -112,8 +110,7 @@ end
 """
 laptimer()
 
-Print the current elapsed time, in canonical form, since the previous `tick()`,
-and continue counting.
+Print the elapsed time, in canonical form, of the most recent timer, and continue counting.
 """
 laptimer() = showtimes(canonical=true)
 
