diff --git a/src/boot/boot.janet b/src/boot/boot.janet
index 9b4af135..f1431645 100644
--- a/src/boot/boot.janet
+++ b/src/boot/boot.janet
@@ -3736,12 +3736,20 @@
     ~(,ev/thread (fn _spawn-thread [&] ,;body) nil :n))
 
   (defmacro ev/with-deadline
-    `Run a body of code with a deadline, such that if the code does not complete before
-    the deadline is up, it will be canceled.`
-    [deadline & body]
+    ``
+    Create a fiber to execute `body`, schedule the event loop to cancel
+    the task (root fiber) associated with `body`'s fiber, and start
+    `body`'s fiber by resuming it.
+
+    The event loop will try to cancel the root fiber if `body`'s fiber
+    has not completed after at least `sec` seconds.
+
+    `sec` is a number that can have a fractional part.
+    ``
+    [sec & body]
     (with-syms [f]
       ~(let [,f (coro ,;body)]
-         (,ev/deadline ,deadline nil ,f)
+         (,ev/deadline ,sec nil ,f)
          (,resume ,f))))
 
   (defn- cancel-all [chan fibers reason]
diff --git a/src/core/ev.c b/src/core/ev.c
index 3aa0e9a9..1473b82a 100644
--- a/src/core/ev.c
+++ b/src/core/ev.c
@@ -2952,10 +2952,15 @@ JANET_CORE_FN(cfun_ev_sleep,
 
 JANET_CORE_FN(cfun_ev_deadline,
               "(ev/deadline sec &opt tocancel tocheck)",
-              "Set a deadline for a fiber `tocheck`. If `tocheck` is not finished after `sec` seconds, "
-              "`tocancel` will be canceled as with `ev/cancel`. "
-              "If `tocancel` and `tocheck` are not given, they default to `(fiber/root)` and "
-              "`(fiber/current)` respectively. Returns `tocancel`.") {
+              "Schedules the event loop to try to cancel the `tocancel` "
+              "task as with `ev/cancel`. After `sec` seconds, the event "
+              "loop will attempt cancellation of `tocancel` if the "
+              "`tocheck` fiber is resumable. `sec` is a number that can "
+              "have a fractional part. `tocancel` defaults to "
+              "`(fiber/root)`, but if specified, must be a task (root "
+              "fiber). `tocheck` defaults to `(fiber/current)`, but if "
+              "specified, should be a fiber. Returns `tocancel` "
+              "immediately.") {
     janet_arity(argc, 1, 3);
     double sec = janet_getnumber(argv, 0);
     JanetFiber *tocancel = janet_optfiber(argv, argc, 1, janet_vm.root_fiber);