time: document return type of timeout (#5118)

tokio/src/time/error.rs

@@ -41,6 +41,9 @@ impl From<Kind> for Error {
 }
 
 /// Errors returned by `Timeout`.
+///
+/// This error is returned when a timeout expires before the function was able
+/// to finish.
 #[derive(Debug, PartialEq)]
 pub struct Elapsed(());
 

tokio/src/time/timeout.rs

@@ -21,6 +21,12 @@ use std::task::{self, Poll};
 /// value is returned. Otherwise, an error is returned and the future is
 /// canceled.
 ///
+/// This function returns a future whose return type is [`Result`]`<T,`[`Elapsed`]`>`, where `T` is the
+/// return type of the provided future.
+///
+/// [`Result`]: std::result::Result
+/// [`Elapsed`]: crate::time::error::Elapsed
+///
 /// # Cancellation
 ///
 /// Cancelling a timeout is done by dropping the future. No additional cleanup
@@ -68,9 +74,9 @@ use std::task::{self, Poll};
 /// [`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>
+pub fn timeout<F>(duration: Duration, future: F) -> Timeout<F>
 where
-    T: Future,
+    F: Future,
 {
     let location = trace::caller_location();
 
@@ -87,6 +93,12 @@ where
 /// If the future completes before the instant is reached, then the completed
 /// value is returned. Otherwise, an error is returned.
 ///
+/// This function returns a future whose return type is [`Result`]`<T,`[`Elapsed`]`>`, where `T` is the
+/// return type of the provided future.
+///
+/// [`Result`]: std::result::Result
+/// [`Elapsed`]: crate::time::error::Elapsed
+///
 /// # Cancellation
 ///
 /// Cancelling a timeout is done by dropping the future. No additional cleanup
@@ -116,9 +128,9 @@ where
 /// }
 /// # }
 /// ```
-pub fn timeout_at<T>(deadline: Instant, future: T) -> Timeout<T>
+pub fn timeout_at<F>(deadline: Instant, future: F) -> Timeout<F>
 where
-    T: Future,
+    F: Future,
 {
     let delay = sleep_until(deadline);