io::ErrorKind: Discuss matching

[ijackson]

Here I add a cross-reference to a blog post (one of my own). I have no idea if that is allowed. (FWIW the URL is stable and I don't expect Dreamwidth do go away.)

I did it like this because this extensive discussion doesn't readily fit into the stdlib docs. I'm prepared for the possiblity that the suggestion to c&p, or the external reference, might be controversial...

Closes #89175

[rust-highfive]

r? @Mark-Simulacrum

(rust-highfive has picked a reviewer for you, use r? to override)

[Mark-Simulacrum]

I don't think we should link to an external blog post here, but I do think including those longer-form docs somewhere makes sense. Given that it's at least generally accepted already, maybe a good strategy would be to propose an RFC for T-libs, which we can then link to? I imagine getting that RFC into FCP would not take too long.

r? @m-ou-se since the question here is basically where to best put these docs

[joshtriplett]

Agreed regarding external posts.

For the time being, I'd be happy to merge this with the last line removed, or replaced with a summary.

I do think the suggestion to copy-paste (for the case of exhaustive tests) is reasonable here.

[ijackson]

For the time being, I'd be happy to merge this with the last line removed, or replaced with a summary.

I do think the suggestion to copy-paste (for the case of exhaustive tests) is reasonable here.

The difficulty is that without a longer explanation (I don't think a summary will do) the suggestion to c&p is highly unusual, and runs very counter to usual advice. Without a full explanation I doubt many readers will follow the advice; they might dismiss the doc as written by idiots or lunatics.

I like the suggestion of putting this into an RFC, albeit after the decision has already been taken. My blog post has many of the elements of such an RFC in it already.

[joshtriplett]

@ijackson The explanation in your post is four paragraphs; I don't think that'd be unreasonable, and it may also be possible to reduce further (as your post was optimizing for both a less-familiar audience and an expectation of potential incredulity).

Also, on balance, I don't think people are in the habit of assuming that the standard library documentation's recommendations are wildly unreasonable; on the contrary, we usually have the problem of people taking them too seriously. (This is, for instance, one reason why we don't tend to recommend specific third-party crates, because that recommendation carries too much weight.)

Borrowing heavily from your post, here's a summary that should be sufficiently clear and self-contained:

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.

You don't want to test specifically that an error is not recognized by the version of the Rust standard library currently in use, because Rust might start recognizing more errors; when the test is compiled and run later, perhaps years later, the error in this test case might indeed be categorized. You want to test that the error is not any of the error kinds which existed when the test was written; thus, you want to copy-paste the list of known error kinds.

Copy-pasting will seem wrong, because the list in your code and in Rust can get out of step. But when they do get out of step you want your version, not the standard library's.

You probably only want to maintain one copy of this list, so put it somewhere central in your codebase's test support machinery. Periodically, you can update the list deliberately - and fix any resulting test failures.

[JohnCSimon]

Triage: @ijackson - returning to author
@rustbot label: +S-waiting-on-author -S-waiting-on-review

[Mark-Simulacrum]

One thought I additionally had just now: it may be reasonable for us to either provide a copyable snippet that is updated when variants are added (so that it's easy to get started, and if you already read/trust the documentation, can just directly copy).

We could also consider exposing a function which asserts on behalf of the user, with a version parameter. But that would be significantly "new ground" (exposing versions, etc), though might allow for better error messages than would otherwise be possible (e.g., indicating which version the new variant was added in).

[JohnCSimon]

Ping from triage:
@ijackson Can you address the comments from the reviewers and post your status on this PR?

[Dylan-DPC]

reworked in #94273