Rollup merge of #110620 - Nilstrieb:document-the-undocumented, r=thomcc

Document `const {}` syntax for `std::thread_local`.

It exists and is pretty cool. More people should use it.

It was added in #83416 and stabilized in #91355 with the tracking issue #84223.

1 files changed, 20 insertions, 2 deletions

diff --git a/library/std/src/thread/local.rs b/library/std/src/thread/local.rs
index fa08fdc1653..3b7c31826b9 100644
--- a/library/std/src/thread/local.rs
+++ b/library/std/src/thread/local.rs
@@ -134,10 +134,28 @@ impl<T: 'static> fmt::Debug for LocalKey<T> {
 /// thread_local! {
 ///     pub static FOO: RefCell<u32> = RefCell::new(1);
 ///
-///     #[allow(unused)]
 ///     static BAR: RefCell<f32> = RefCell::new(1.0);
 /// }
-/// # fn main() {}
+///
+/// FOO.with(|foo| assert_eq!(*foo.borrow(), 1));
+/// BAR.with(|bar| assert_eq!(*bar.borrow(), 1.0));
+/// ```
+///
+/// This macro supports a special `const {}` syntax that can be used
+/// when the initialization expression can be evaluated as a constant.
+/// This can enable a more efficient thread local implementation that
+/// can avoid lazy initialization. For types that do not
+/// [need to be dropped][crate::mem::needs_drop], this can enable an
+/// even more efficient implementation that does not need to
+/// track any additional state.
+///
+/// ```
+/// use std::cell::Cell;
+/// thread_local! {
+///     pub static FOO: Cell<u32> = const { Cell::new(1) };
+/// }
+///
+/// FOO.with(|foo| assert_eq!(foo.get(), 1));
 /// ```
 ///
 /// See [`LocalKey` documentation][`std::thread::LocalKey`] for more