Rollup merge of #94273 - Dylan-DPC:doc/errorkind, r=joshtriplett

add matching doc to errorkind

Rework of #90706

1 files changed, 13 insertions, 0 deletions

diff --git a/library/std/src/io/error.rs b/library/std/src/io/error.rs
index 1aa6d657889..17e2b97545a 100644
--- a/library/std/src/io/error.rs
+++ b/library/std/src/io/error.rs
@@ -141,6 +141,19 @@ struct Custom {
 /// It is used with the [`io::Error`] type.
 ///
 /// [`io::Error`]: Error
+///
+/// # Handling errors and matching on `ErrorKind`
+///
+/// In application code, use `match` for the `ErrorKind` values you are
+/// expecting; use `_` to match "all other errors".
+///
+/// In comprehensive and thorough tests that want to verify that a test doesn't
+/// return any known incorrect error kind, you may want to cut-and-paste the
+/// current full list of errors from here into your test code, and then match
+/// `_` as the correct case. This seems counterintuitive, but it will make your
+/// tests more robust. In particular, if you want to verify that your code does
+/// produce an unrecognized error kind, the robust solution is to check for all
+/// the recognized error kinds and fail in those cases.
 #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
 #[stable(feature = "rust1", since = "1.0.0")]
 #[allow(deprecated)]