doc comment

Author: cijothomas

examples/metrics-basic/src/main.rs

@@ -141,7 +141,7 @@ async fn main() {
     // however shutting down the MeterProvider here instantly flushes
     // the metrics, instead of waiting for the 30 sec interval.
     let shutdown_result = meter_provider.shutdown();
-    
+
     // Demonstrate handling the shutdown result.
     match shutdown_result {
         Ok(_) => println!("MeterProvider shutdown successfully"),

opentelemetry-sdk/src/error.rs

@@ -13,16 +13,30 @@ pub trait ExportError: std::error::Error + Send + Sync + 'static {
 #[derive(Error, Debug)]
 /// Errors that can occur during shutdown.
 pub enum ShutdownError {
-    /// Shutdown already invoked.
+    /// Shutdown has already been invoked.
+    ///
+    /// While shutdown is idempotent and calling it multiple times has no
+    /// impact, this error suggests that another part of the application is
+    /// invoking `shutdown` earlier than intended. Users should review their
+    /// code to identify unintended or duplicate shutdown calls and ensure it is
+    /// only triggered once at the correct place.
     #[error("Shutdown already invoked")]
     AlreadyShutdown,
 
     /// Shutdown timed out before completing.
+    ///
+    /// This does not necessarily indicate a failure—shutdown may still be
+    /// complete. If this occurs frequently, consider increasing the timeout
+    /// duration to allow more time for completion.
     #[error("Shutdown timed out after {0:?}")]
     Timeout(Duration),
 
-    /// Shutdown failed with an error.
-    /// This error is returned when the shutdown process failed with an error.
+    /// Shutdown failed due to an internal error.
+    ///
+    /// The error message is intended for logging purposes only and should not
+    /// be used to make programmatic decisions. It is implementation-specific
+    /// and subject to change without notice. Consumers of this error should not
+    /// rely on its content beyond logging.
     #[error("Shutdown failed: {0}")]
     InternalFailure(String),
 }