Rollup merge of rust-lang#91460 - ChrisDenton:doc-last-os-error, r=joshtriplett

Document how `last_os_error` should be used

It should be made clear that the state of the last OS error could change if another function call is made before the call to `Error::last_os_error()`.

Fixes: rust-lang#53155

Author: matthiaskrgr

library/std/src/io/error.rs

@@ -440,12 +440,18 @@ impl Error {
     /// `GetLastError` on Windows) and will return a corresponding instance of
     /// [`Error`] for the error code.
     ///
+    /// This should be called immediately after a call to a platform function,
+    /// otherwise the state of the error value is indeterminate. In particular,
+    /// other standard library functions may call platform functions that may
+    /// (or may not) reset the error value even if they succeed.
+    ///
     /// # Examples
     ///
     /// ```
     /// use std::io::Error;
     ///
-    /// println!("last OS error: {:?}", Error::last_os_error());
+    /// let os_error = Error::last_os_error();
+    /// println!("last OS error: {:?}", os_error);
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     #[must_use]