added doc strings

cormullion · cormullion · commit 1729c43e3fdf · 2017-12-11T18:31:01.000Z
diff --git a/README.md b/README.md
@@ -1,5 +1,22 @@
 # TickTock
 
+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.
+
+## Example
+
+```julia
+julia-0.6> using TickTock
+
+julia-0.6> tick()
+0x0000146b7dcc5c23
+
+julia-0.6> tock()
+2 seconds
+```
+
 [![Build Status](https://travis-ci.org/cormullion/TickTock.jl.svg?branch=master)](https://travis-ci.org/cormullion/TickTock.jl)
 
 [![Coverage Status](https://coveralls.io/repos/cormullion/TickTock.jl/badge.svg?branch=master&service=github)](https://coveralls.io/github/cormullion/TickTock.jl?branch=master)
diff --git a/src/TickTock.jl b/src/TickTock.jl
@@ -1,29 +1,51 @@
+"""
+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.
+"""
+
 module TickTock
 
-export tick, tock
+export tick, tock, tok
+
+"""
+    tick()
 
+Start counting.
+"""
 function tick()
     t0 = time_ns()
     task_local_storage(:TIMERS, (t0, get(task_local_storage(), :TIMERS, ())))
     return t0
 end
 
-function toqk()
+"""
+    tok()
+
+Return the time since the previous `tick()`, in seconds, and then stop counting.
+"""
+function tok()
     t1 = time_ns()
     timers = get(task_local_storage(), :TIMERS, ())
     if timers === ()
-        error("You tock()ed before you tick()ed...")
+        error("You must first use `tick()`.")
     end
     t0 = timers[1]::UInt64
     task_local_storage(:TIMERS, timers[2])
-    (t1-t0)/1e9
+    (t1-t0)/1e9 # seconds
 end
 
+"""
+    tock()
+
+Print the elapsed time, in suitably canonical form, since the previous `tick()`,
+and then stop counting.
+"""
 function tock()
-    t = toqk()
-    dc = Dates.canonicalize(Dates.CompoundPeriod(now() - t))
-    println(dc)
-    return dc
+    t = tok()
+    canondc = Dates.canonicalize(Dates.CompoundPeriod(Dates.Second(floor(t))))
+    println(canondc)
 end
 
 end # module
diff --git a/test/runtests.jl b/test/runtests.jl
@@ -2,4 +2,7 @@ using TickTock
 using Base.Test
 
 # write your own tests here
-@test 1 == 2
+tick()
+sleep(1)
+@test tok() > 1.0
+ 
