diff --git a/docs/library/machine.rst b/docs/library/machine.rst
index 46d8eea71..7870da2ff 100644
--- a/docs/library/machine.rst
+++ b/docs/library/machine.rst
@@ -24,17 +24,15 @@ Interrupt related functions
 .. function:: disable_irq()
 
    Disable interrupt requests.
-   Returns the previous IRQ state: ``False``/``True`` for disabled/enabled IRQs
-   respectively.  This return value can be passed to enable_irq to restore
-   the IRQ to its original state.
+   Returns the previous IRQ state which should be considered an opaque value.
+   This return value should be passed to the ``enable_irq`` function to restore
+   interrupts to their original state, before ``disable_irq`` was called.
 
-.. function:: enable_irq(state=True)
+.. function:: enable_irq(state)
 
-   Enable interrupt requests.
-   If ``state`` is ``True`` (the default value) then IRQs are enabled.
-   If ``state`` is ``False`` then IRQs are disabled.  The most common use of
-   this function is to pass it the value returned by ``disable_irq`` to
-   exit a critical section.
+   Re-enable interrupt requests.
+   The ``state`` parameter should be the value that was returned from the most
+   recent call to the ``disable_irq`` function.
 
 Power related functions
 -----------------------