std: Expand on blocking behavior of LazyLock

Author: behnam-oneschema

library/std/src/sync/lazy_lock.rs

@@ -20,6 +20,8 @@ union Data<T, F> {
 /// A value which is initialized on the first access.
 ///
 /// This type is a thread-safe [`LazyCell`], and can be used in statics.
+/// Therefore, any dereferencing call will block the calling thread if
+/// another initialization routine is currently running.
 ///
 /// [`LazyCell`]: crate::cell::LazyCell
 ///
@@ -81,8 +83,7 @@ pub struct LazyLock<T, F = fn() -> T> {
 }
 
 impl<T, F: FnOnce() -> T> LazyLock<T, F> {
-    /// Creates a new lazy value with the given initializing
-    /// function.
+    /// Creates a new lazy value with the given initializing function.
     #[inline]
     #[unstable(feature = "lazy_cell", issue = "109736")]
     pub const fn new(f: F) -> LazyLock<T, F> {
@@ -239,7 +240,7 @@ impl<T: fmt::Debug, F> fmt::Debug for LazyLock<T, F> {
 }
 
 // We never create a `&F` from a `&LazyLock<T, F>` so it is fine
-// to not impl `Sync` for `F`
+// to not impl `Sync` for `F`.
 #[unstable(feature = "lazy_cell", issue = "109736")]
 unsafe impl<T: Sync + Send, F: Send> Sync for LazyLock<T, F> {}
 // auto-derived `Send` impl is OK.