Update references docs

2 files changed, 59 insertions, 0 deletions

diff --git a/docs/reference.rst b/docs/reference.rst
index 72f0fa9..ac0ccf2 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -114,6 +114,11 @@ Record :ref:`timer <timer-type>` information.
     def foo():
         pass
 
+::
+
+    timer = StatsClient().timer('foo', rate=1).start()
+    timer.stop()
+
 Automatically record timing information for a managed block or function
 call.  See also the :ref:`chapter on timing <timing-chapter>`.
 
@@ -124,6 +129,58 @@ call.  See also the :ref:`chapter on timing <timing-chapter>`.
   sample rate into account for timers.
 
 
+.. _timer-start:
+
+``start``
+=========
+
+::
+
+    StatsClient().timer('foo').start()
+
+Causes a timer object to start counting. Called automatically when the
+object is used as a decorator or context manager. Returns the timer
+object for simplicity.
+
+
+.. _timer-stop:
+
+``stop``
+========
+
+::
+
+    timer = StatsClient().timer('foo').start()
+    timer.stop()
+
+Causes the timer object to stop timing and send the results to statsd_.
+Can be called with ``send=False`` to prevent immediate sending
+immediately, and use ``send()``. Called automatically when the object is
+used as a decorator or context manager. Returns the timer object.
+
+If ``stop()`` is called before ``start()``, a ``RuntimeError`` is
+raised.
+
+
+.. _timer-send:
+
+``send``
+========
+
+::
+
+    timer = StatsClient().timer('foo').start()
+    timer.stop(send=False)
+    timer.send()
+
+Causes the timer to send any unsent data. If the data has already been
+sent, or has not yet been recorded, a ``RuntimeError`` is raised.
+
+.. note::
+   See the note abbout `timer objects and pipelines
+   <timer-direct-note>`_.
+
+
 .. _gauge:
 
 ``gauge``
diff --git a/docs/timing.rst b/docs/timing.rst
index 133da91..053749d 100644
--- a/docs/timing.rst
+++ b/docs/timing.rst
@@ -99,6 +99,8 @@ this behavior with the ``send=False`` keyword argument to ``stop()``::
 Use :py:meth:`statsd.client.Timer.send` to send the stat when you're
 ready.
 
+.. _timer-direct-note:
+
 .. note::
    This use of timers is compatible with `Pipelines <pipeline-chapter>`_
    but be careful with the ``send()`` method. It *must* be called for