1 files changed, 16 insertions, 2 deletions
diff --git a/docs/library/machine.Timer.rst b/docs/library/machine.Timer.rst
index d1709a818..424a49bcb 100644
--- a/docs/library/machine.Timer.rst
+++ b/docs/library/machine.Timer.rst
@@ -42,8 +42,14 @@ Methods
 
    Initialise the timer. Example::
 
-       tim.init(period=100)                         # periodic with 100ms period
-       tim.init(mode=Timer.ONE_SHOT, period=1000)   # one shot firing after 1000ms
+       def mycallback(t):
+           pass
+
+       # periodic with 100ms period
+       tim.init(period=100, callback=mycallback)
+
+       # one shot firing after 1000ms
+       tim.init(mode=Timer.ONE_SHOT, period=1000, callback=mycallback)
 
    Keyword arguments:
 
@@ -54,6 +60,14 @@ Methods
        - ``Timer.PERIODIC`` - The timer runs periodically at the configured
          frequency of the channel.
 
+     - ``period`` - The timer period, in milliseconds.
+
+     - ``callback`` - The callable to call upon expiration of the timer period.
+       The callback must take one argument, which is passed the Timer object.
+       The ``callback`` argument shall be specified. Otherwise an exception
+       will occurr upon timer expiration:
+       ``TypeError: 'NoneType' object isn't callable``
+
 .. method:: Timer.deinit()
 
    Deinitialises the timer. Stops the timer, and disables the timer peripheral.