time: document that timeouts check only before poll
@@ -21,6 +21,10 @@ use std::task::{self, Poll};
/// value is returned. Otherwise, an error is returned and the future is
/// canceled.
///
+/// Note that the timeout is checked before polling the future, so if the future
+/// does not yield during execution then it is possible for the future to complete
+/// and exceed the timeout _without_ returning an error.
+///
/// This function returns a future whose return type is [`Result`]`<T,`[`Elapsed`]`>`, where `T` is the
/// return type of the provided future.
///
