1 files changed, 9 insertions, 1 deletions
diff --git a/docs/library/machine.Timer.rst b/docs/library/machine.Timer.rst
index 424a49bcb..48c023a11 100644
--- a/docs/library/machine.Timer.rst
+++ b/docs/library/machine.Timer.rst
@@ -38,13 +38,16 @@ Constructors
 Methods
 -------
 
-.. method:: Timer.init(*, mode=Timer.PERIODIC, period=-1, callback=None)
+.. method:: Timer.init(*, mode=Timer.PERIODIC, freq=-1, period=-1, callback=None)
 
    Initialise the timer. Example::
 
        def mycallback(t):
            pass
 
+       # periodic at 1kHz
+       tim.init(mode=Timer.PERIODIC, freq=1000, callback=mycallback)
+
        # periodic with 100ms period
        tim.init(period=100, callback=mycallback)
 
@@ -60,6 +63,11 @@ Methods
        - ``Timer.PERIODIC`` - The timer runs periodically at the configured
          frequency of the channel.
 
+     - ``freq`` - The timer frequency, in units of Hz.  The upper bound of
+       the frequency is dependent on the port.  When both the ``freq`` and
+       ``period`` arguments are given, ``freq`` has a higher priority and
+       ``period`` is ignored.
+
      - ``period`` - The timer period, in milliseconds.
 
      - ``callback`` - The callable to call upon expiration of the timer period.