add info about repeated invocation and interactive use

README.rst

@@ -20,8 +20,8 @@ accurately.
     implementation and portability notes below for details.
 
 
-Basic usage
------------
+Usage
+-----
 
 It's easy to get started with ``statprof``: ::
 
@@ -41,6 +41,38 @@ Or with a contextmanager : ::
     with statprof.profile():
         my_questionable_function()
 
+The profiler can be invoked at more than one place inside your code and will
+report its findings for all of them at once at the end: ::
+
+    import statprof
+
+    statprof.start()
+    try:
+        my_questionable_function()
+    finally:
+        statprof.stop()
+
+    uninteresting_code()
+
+    statprof.start()
+    try:
+        my_other_questionable_function()
+    finally:
+        statprof.stop()
+
+    statprof.display()
+
+However, when you are profiling your code by repeatedly executing it in
+IPython, each run will add new samples to the previously collected ones, and
+display results aggregated over all runs. Since you will likely just want to
+see the results for the last run, remember to reset the profiler first: ::
+
+    import statprof
+
+    statprof.reset()
+    with statprof.profile():
+        my_questionable_function()
+
 For more comprehensive help, run ``pydoc statprof``.