chore: update docs

Author: taisho6339

opentelemetry-sdk/src/trace/span_processor.rs

@@ -86,9 +86,11 @@ pub trait SpanProcessor: Send + Sync + std::fmt::Debug {
     ///
     /// # Accessing Context
     ///
-    /// If you need to access context information (such as baggage) in `on_end`,
-    /// note that calling [`Context::current()`] will return the **parent context**,
-    /// not the span's context (which has already been removed from the context stack).
+    /// **Important**: Do not rely on [`Context::current()`] in `on_end`. When `on_end`
+    /// is called during span cleanup, `Context::current()` returns whatever context
+    /// happens to be active at that moment, which is typically unrelated to the span
+    /// being ended. Contexts can be activated in any order and are not necessarily
+    /// hierarchical.
     ///
     /// **Best Practice**: Extract any needed context information in [`on_start`]
     /// and store it as span attributes. This ensures the information is available

opentelemetry/src/context.rs

@@ -119,8 +119,12 @@ impl Context {
     ///
     /// When called from within a [`Drop`] implementation that is triggered by
     /// a [`ContextGuard`] being dropped (e.g., when a [`Span`] is dropped as part
-    /// of context cleanup), this function returns the **parent context**, not the
-    /// context being dropped.
+    /// of context cleanup), this function returns **whatever context happens to be
+    /// current after the guard is popped**, not the context being dropped.
+    ///
+    /// **Important**: The returned context may be completely unrelated to the
+    /// context being dropped, as contexts can be activated in any order and are
+    /// not necessarily hierarchical. Do not rely on any relationship between them.
     ///
     /// This behavior is by design and prevents panics that would otherwise occur
     /// from attempting to borrow the context while it's being mutably borrowed