time: document missing timer panics (#4247)

tokio/src/time/driver/handle.rs

@@ -40,16 +40,19 @@ cfg_rt! {
         ///
         /// This function panics if there is no current timer set.
         ///
-        /// It can be triggered when `Builder::enable_time()` or
-        /// `Builder::enable_all()` are not included in the builder.
+        /// It can be triggered when [`Builder::enable_time`] or
+        /// [`Builder::enable_all`] are not included in the builder.
         ///
         /// It can also panic whenever a timer is created outside of a
-        /// Tokio runtime. That is why `rt.block_on(delay_for(...))` will panic,
+        /// Tokio runtime. That is why `rt.block_on(sleep(...))` will panic,
         /// since the function is executed outside of the runtime.
-        /// Whereas `rt.block_on(async {delay_for(...).await})` doesn't panic.
+        /// Whereas `rt.block_on(async {sleep(...).await})` doesn't panic.
         /// And this is because wrapping the function on an async makes it lazy,
         /// and so gets executed inside the runtime successfully without
         /// panicking.
+        ///
+        /// [`Builder::enable_time`]: crate::runtime::Builder::enable_time
+        /// [`Builder::enable_all`]: crate::runtime::Builder::enable_all
         pub(crate) fn current() -> Self {
             crate::runtime::context::time_handle()
                 .expect("A Tokio 1.x context was found, but timers are disabled. Call `enable_time` on the runtime builder to enable timers.")
@@ -65,16 +68,19 @@ cfg_not_rt! {
         ///
         /// This function panics if there is no current timer set.
         ///
-        /// It can be triggered when `Builder::enable_time()` or
-        /// `Builder::enable_all()` are not included in the builder.
+        /// It can be triggered when [`Builder::enable_time`] or
+        /// [`Builder::enable_all`] are not included in the builder.
         ///
-        /// It can also panic whenever a timer is created outside of a Tokio
-        /// runtime. That is why `rt.block_on(delay_for(...))` will panic,
+        /// It can also panic whenever a timer is created outside of a
+        /// Tokio runtime. That is why `rt.block_on(sleep(...))` will panic,
         /// since the function is executed outside of the runtime.
-        /// Whereas `rt.block_on(async {delay_for(...).await})` doesn't
-        /// panic. And this is because wrapping the function on an async makes it
-        /// lazy, and so outside executed inside the runtime successfully without
+        /// Whereas `rt.block_on(async {sleep(...).await})` doesn't panic.
+        /// And this is because wrapping the function on an async makes it lazy,
+        /// and so gets executed inside the runtime successfully without
         /// panicking.
+        ///
+        /// [`Builder::enable_time`]: crate::runtime::Builder::enable_time
+        /// [`Builder::enable_all`]: crate::runtime::Builder::enable_all
         pub(crate) fn current() -> Self {
             panic!("{}", crate::util::error::CONTEXT_MISSING_ERROR)
         }

tokio/src/time/driver/sleep.rs

@@ -41,8 +41,25 @@ cfg_trace! {
 ///
 /// See the documentation for the [`Sleep`] type for more examples.
 ///
+/// # Panics
+///
+/// This function panics if there is no current timer set.
+///
+/// It can be triggered when [`Builder::enable_time`] or
+/// [`Builder::enable_all`] are not included in the builder.
+///
+/// It can also panic whenever a timer is created outside of a
+/// Tokio runtime. That is why `rt.block_on(sleep(...))` will panic,
+/// since the function is executed outside of the runtime.
+/// Whereas `rt.block_on(async {sleep(...).await})` doesn't panic.
+/// And this is because wrapping the function on an async makes it lazy,
+/// and so gets executed inside the runtime successfully without
+/// panicking.
+///
 /// [`Sleep`]: struct@crate::time::Sleep
 /// [`interval`]: crate::time::interval()
+/// [`Builder::enable_time`]: crate::runtime::Builder::enable_time
+/// [`Builder::enable_all`]: crate::runtime::Builder::enable_all
 // Alias for old name in 0.x
 #[cfg_attr(docsrs, doc(alias = "delay_until"))]
 #[track_caller]
@@ -84,8 +101,25 @@ pub fn sleep_until(deadline: Instant) -> Sleep {
 ///
 /// See the documentation for the [`Sleep`] type for more examples.
 ///
+/// # Panics
+///
+/// This function panics if there is no current timer set.
+///
+/// It can be triggered when [`Builder::enable_time`] or
+/// [`Builder::enable_all`] are not included in the builder.
+///
+/// It can also panic whenever a timer is created outside of a
+/// Tokio runtime. That is why `rt.block_on(sleep(...))` will panic,
+/// since the function is executed outside of the runtime.
+/// Whereas `rt.block_on(async {sleep(...).await})` doesn't panic.
+/// And this is because wrapping the function on an async makes it lazy,
+/// and so gets executed inside the runtime successfully without
+/// panicking.
+///
 /// [`Sleep`]: struct@crate::time::Sleep
 /// [`interval`]: crate::time::interval()
+/// [`Builder::enable_time`]: crate::runtime::Builder::enable_time
+/// [`Builder::enable_all`]: crate::runtime::Builder::enable_all
 // Alias for old name in 0.x
 #[cfg_attr(docsrs, doc(alias = "delay_for"))]
 #[cfg_attr(docsrs, doc(alias = "wait"))]

tokio/src/time/timeout.rs

@@ -48,6 +48,24 @@ use std::task::{self, Poll};
 /// }
 /// # }
 /// ```
+///
+/// # Panics
+///
+/// This function panics if there is no current timer set.
+///
+/// It can be triggered when [`Builder::enable_time`] or
+/// [`Builder::enable_all`] are not included in the builder.
+///
+/// It can also panic whenever a timer is created outside of a
+/// Tokio runtime. That is why `rt.block_on(sleep(...))` will panic,
+/// since the function is executed outside of the runtime.
+/// Whereas `rt.block_on(async {sleep(...).await})` doesn't panic.
+/// And this is because wrapping the function on an async makes it lazy,
+/// and so gets executed inside the runtime successfully without
+/// panicking.
+///
+/// [`Builder::enable_time`]: crate::runtime::Builder::enable_time
+/// [`Builder::enable_all`]: crate::runtime::Builder::enable_all
 #[track_caller]
 pub fn timeout<T>(duration: Duration, future: T) -> Timeout<T>
 where