diff --git a/epicardium/epicardium.h b/epicardium/epicardium.h
index a4615364e127a513c5936ce1c86bb13bf2de0c1e..bc32e5cab772b6e952cecce64345c757857f3afe 100644
--- a/epicardium/epicardium.h
+++ b/epicardium/epicardium.h
@@ -336,7 +336,24 @@ API(API_SYSTEM_EXEC, int __epic_exec(char *name));
  */
 API(API_SYSTEM_RESET, void epic_system_reset(void));
 
-API(API_SLEEP, void epic_sleep(uint32_t ms));
+/**
+ * Sleep for the specified amount of time.
+ *
+ * This call will block for at most the specified amount of time. It allows epicardium to
+ * reduce clock speed of the system until this call is finished.
+ *
+ * This call returns early if an interrupt is signaled from epicardium.
+ *
+ * The clock source of epicardium has a limited amount of accuracy. Tolerances
+ * of +- 10% have been observed. This means that the sleep time also has a
+ * tolarance of at least +- 10%. The exact amount varies from device to device and
+ * also with temperature. You should take this into consideration when selecting
+ * the time you want to sleep.
+ *
+ * :param ms:  Time to wait in milliseconds
+ * :returns: 0 if no interrupt happened, ``INT_MAX`` if an interrupt happened and the sleep ended early.
+ */
+API(API_SLEEP, int epic_sleep(uint32_t ms));
 
 /**
  * PMIC API