diff --git a/docs/library/machine.rst b/docs/library/machine.rst
index f734cccc37..a7b5957761 100644
--- a/docs/library/machine.rst
+++ b/docs/library/machine.rst
@@ -63,16 +63,31 @@ Power related functions
 
 .. function:: sleep()
 
-   Stops the CPU and disables all peripherals except for WLAN. Execution is resumed from
-   the point where the sleep was requested. For wake up to actually happen, wake sources
-   should be configured first.
+   .. note:: This function is deprecated, use `lightsleep()` instead with no arguments.
 
-.. function:: deepsleep()
+.. function:: lightsleep([time_ms])
+              deepsleep([time_ms])
 
-   Stops the CPU and all peripherals (including networking interfaces, if any). Execution
-   is resumed from the main script, just as with a reset. The reset cause can be checked
-   to know that we are coming from `machine.DEEPSLEEP`. For wake up to actually happen,
-   wake sources should be configured first, like `Pin` change or `RTC` timeout.
+   Stops execution in an attempt to enter a low power state.
+
+   If *time_ms* is specified then this will be the maximum time in milliseconds that
+   the sleep will last for.  Otherwise the sleep can last indefinitely.
+
+   With or without a timout, execution may resume at any time if there are events
+   that require processing.  Such events, or wake sources, should be configured before
+   sleeping, like `Pin` change or `RTC` timeout.
+
+   The precise behaviour and power-saving capabilities of lightsleep and deepsleep is
+   highly dependent on the underlying hardware, but the general properties are:
+
+   * A lightsleep has full RAM and state retention.  Upon wake execution is resumed
+     from the point where the sleep was requested, with all subsystems operational.
+
+   * A deepsleep may not retain RAM or any other state of the system (for example
+     peripherals or network interfaces).  Upon wake execution is resumed from the main
+     script, similar to a hard or power-on reset. The `reset_cause()` function will
+     return `machine.DEEPSLEEP` and this can be used to distinguish a deepsleep wake
+     from other resets.
 
 .. function:: wake_reason()