docs(common): state the ExecutionJoin contract on the variant itself

The variant said a `JoinError` "can't occur for unjoined tasks, such as
execution shutdown". That is about a handle nobody awaits, but it reads as
ruling out the shutdown-cancelled join this variant now carries. State the
contract instead: only a joined task reports a `JoinError`, a cancelled one
lands here with the `JoinError` reachable as the source, and a panicking one
goes to `from_join_error`'s resume path.

Author: claudespice

datafusion/common/src/error.rs

@@ -132,7 +132,15 @@ pub enum DataFusionError {
     Execution(String),
     /// [`JoinError`] during execution of the query.
     ///
-    /// This error can't occur for unjoined tasks, such as execution shutdown.
+    /// Only a task that is actually joined can report a [`JoinError`], so a task
+    /// that is spawned and never awaited never reaches this variant. A joined
+    /// task that was **cancelled** does: it was aborted, or the runtime it was
+    /// spawned on shut down while it was still queued. The `JoinError` stays
+    /// reachable as the error's source so a caller can still ask
+    /// [`JoinError::is_cancelled`].
+    ///
+    /// Construct this with [`DataFusionError::from_join_error`], which reports a
+    /// **panicking** task by resuming its panic rather than returning it here.
     ExecutionJoin(Box<JoinError>),
     /// Error when resources (such as memory of scratch disk space) are exhausted.
     ///