add matching doc to errorkind

library/std/src/io/error.rs

@@ -141,6 +141,16 @@ 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 list of errors from here into your test code. 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)]