docs: fix incorrectly rendered doc tests; tighten phrasing (#2150)

tokio/src/task/task_local.rs

@@ -6,22 +6,22 @@ use std::pin::Pin;
 use std::task::{Context, Poll};
 use std::{fmt, thread};
 
-/// Declare a new task local storage key of type [`tokio::task::LocalKey`].
+/// Declares a new task-local key of type [`tokio::task::LocalKey`].
 ///
 /// # Syntax
 ///
-/// The macro wraps any number of static declarations and makes them task locals.
+/// The macro wraps any number of static declarations and makes them local to the current task.
-/// Publicity and attributes for each static are allowed.
+/// Publicity and attributes for each static is preserved. For example:
 ///
 /// # Examples
 ///
 /// ```
 /// # use tokio::task_local;
 /// task_local! {
-///     pub static FOO: u32;
+///     pub static ONE: u32;
 ///
 ///     #[allow(unused)]
-///     static BAR: f32;
+///     static TWO: f32;
 /// }
 /// # fn main() {}
 /// ```
@@ -61,59 +61,58 @@ macro_rules! __task_local_inner {
 
 /// A key for task-local data.
 ///
-/// This type is generated by `task_local!` macro and unlike `thread_local!` it has
+/// This type is generated by the `task_local!` macro.
-/// no concept of lazily initialization. Instead, it is designed to provide task local
-/// storage the future that is passed to `set`.
 ///
-/// # Initialization and Destruction
+/// Unlike [`std::thread::LocalKey`], `tokio::task::LocalKey` will
-///
+/// _not_ lazily initialize the value on first access. Instead, the
-/// Initialization is done via `set` which is an `async fn` that wraps another
+/// value is first initialized when the future containing
-/// [`std::future::Future`] and will set the value on each `Future::poll` call.
+/// the task-local is first polled by a futures executor, like Tokio.
-/// Once the `set` future is dropped the corresponding task local value is also
-/// dropped.
 ///
 /// # Examples
 ///
 /// ```
 /// # async fn dox() {
 /// tokio::task_local! {
-///     static FOO: u32;
+///     static NUMBER: u32;
 /// }
 ///
-/// FOO.scope(1, async move {
+/// NUMBER.scope(1, async move {
-///     assert_eq!(FOO.get(), 1);
+///     assert_eq!(NUMBER.get(), 1);
 /// }).await;
 ///
-/// FOO.scope(2, async move {
+/// NUMBER.scope(2, async move {
-///     assert_eq!(FOO.get(), 2);
+///     assert_eq!(NUMBER.get(), 2);
 ///
-///     FOO.scope(3, async move {
+///     NUMBER.scope(3, async move {
-///         assert_eq!(FOO.get(), 3);
+///         assert_eq!(NUMBER.get(), 3);
 ///     }).await;
 /// }).await;
 /// # }
 /// ```
+/// [`std::thread::LocalKey`]: https://doc.rust-lang.org/std/thread/struct.LocalKey.html
 pub struct LocalKey<T: 'static> {
     #[doc(hidden)]
     pub inner: thread::LocalKey<RefCell<Option<T>>>,
 }
 
 impl<T: 'static> LocalKey<T> {
-    /// Sets a value `T` as the task local value for the future `F`.
+    /// Sets a value `T` as the task-local value for the future `F`.
     ///
-    /// This will run the provided future to completion and set the
+    /// On completion of `scope`, the task-local will be dropped.
-    /// provided value as the task local under this key. Once the returned
-    /// future is dropped so will the value passed be dropped.
     ///
+    /// ### Examples
+    ///
+    /// ```
     /// # async fn dox() {
     /// tokio::task_local! {
-    ///     static FOO: u32;
+    ///     static NUMBER: u32;
     /// }
     ///
-    /// FOO.scope(1, async move {
+    /// NUMBER.scope(1, async move {
-    ///     println!("task local value: {}", FOO.get());
+    ///     println!("task local value: {}", NUMBER.get());
     /// }).await;
     /// # }
+    /// ```
     pub async fn scope<F>(&'static self, value: T, f: F) -> F::Output
     where
         F: Future,
@@ -126,13 +125,12 @@ impl<T: 'static> LocalKey<T> {
         .await
     }
 
-    /// Access this task-local key, running the provided closure with a reference
+    /// Accesses the current task-local and runs the provided closure.
-    /// passed to the value.
     ///
     /// # Panics
     ///
-    /// This function will panic if not called within a future that has not been
+    /// This function will panic if not called within the context
-    /// set via `LocalKey::set`.
+    /// of a future containing a task-local with the corresponding key.
     pub fn with<F, R>(&'static self, f: F) -> R
     where
         F: FnOnce(&T) -> R,
@@ -143,9 +141,11 @@ impl<T: 'static> LocalKey<T> {
         )
     }
 
-    /// Access this task-local key, running the provided closure with a reference
+    /// Accesses the current task-local and runs the provided closure.
-    /// passed to the value. Unlike `with` this function will return a `Result<R, AccessError>`
+    ///
-    /// instead of panicking.
+    /// If the task-local with the accociated key is not present, this
+    /// method will return an `AccessError`. For a panicking variant,
+    /// see `with`.
     pub fn try_with<F, R>(&'static self, f: F) -> Result<R, AccessError>
     where
         F: FnOnce(&T) -> R,
@@ -161,8 +161,8 @@ impl<T: 'static> LocalKey<T> {
 }
 
 impl<T: Copy + 'static> LocalKey<T> {
-    /// Get a copy of the task-local value if it implements
+    /// Returns a copy of the task-local value
-    /// the `Copy` trait.
+    /// if the task-local value implements `Copy`.
     pub fn get(&'static self) -> T {
         self.with(|v| *v)
     }