thread::scope: document how join interacts with TLS destructors

Author: RalfJung

library/std/src/thread/join_handle.rs

@@ -102,6 +102,8 @@ impl<T> JoinHandle<T> {
     /// Waits for the associated thread to finish.
     ///
     /// This function will return immediately if the associated thread has already finished.
+    /// Otherwise, it fully waits for the thread to finish, including all destructors
+    /// for thread-local variables that might be running after the main function of the thread.
     ///
     /// In terms of [atomic memory orderings],  the completion of the associated
     /// thread synchronizes with this function returning. In other words, all

library/std/src/thread/scoped.rs

@@ -80,6 +80,9 @@ impl ScopeData {
 ///
 /// All threads spawned within the scope that haven't been manually joined
 /// will be automatically joined before this function returns.
+/// However, note that joining will only wait for the main function of these threads to finish; even
+/// when this function returns, destructors of thread-local variables in these threads might still
+/// be running.
 ///
 /// # Panics
 ///
@@ -292,6 +295,8 @@ impl<'scope, T> ScopedJoinHandle<'scope, T> {
     /// Waits for the associated thread to finish.
     ///
     /// This function will return immediately if the associated thread has already finished.
+    /// Otherwise, it fully waits for the thread to finish, including all destructors
+    /// for thread-local variables that might be running after the main function of the thread.
     ///
     /// In terms of [atomic memory orderings], the completion of the associated
     /// thread synchronizes with this function returning.