Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Unclear example in io::Error #106937

Closed
jbaublitz opened this issue Jan 16, 2023 · 4 comments · Fixed by #106964
Closed

Unclear example in io::Error #106937

jbaublitz opened this issue Jan 16, 2023 · 4 comments · Fixed by #106964
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools

Comments

@jbaublitz
Copy link

Location

The unclear example is located here.

Summary

I originally interpreted this example to mean that constructing an error from a raw error code always resulted in ErrorKind::Uncategorized. I think it might help to be explicit that no error has occurred yet and that is the reason that this shows up as uncategorized.

@jbaublitz jbaublitz added the A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools label Jan 16, 2023
@amab8901
Copy link
Contributor

can you give us a running example to help us reproduce the issue?

@jbaublitz
Copy link
Author

jbaublitz commented Jan 16, 2023

I apologize if I missed this in the doc report template, but I've never reported a doc issue before. Can you clarify what you mean by a running example? Do you mean the command to build the docs highlighted in the link?

@workingjubilee
Copy link
Member

The variant is #[doc(hidden)], I assume quite deliberately. There is an argument that we should not be mentioning it in the documentation at all. It certainly is confusing, I agree.

@ChrisDenton
Copy link
Member

To summarise the above points, the relevant part of the example is the following:

fn main() {
    // Will print "Uncategorized".
    print_error(Error::last_os_error());

This is weird for two reasons:

  • Uncategorized is hidden and unstable.
  • It's not actually defined what happens when calling last_os_error() without first calling an OS function that failed (this will be highly system specific or may even be affected by pre-main shenanigans but will likely be a success code, hence Uncategorized).

Maybe the example could use from_raw_os_error with a note that the returned kind will depend on how that error code is interpreted by the OS.

Dylan-DPC added a commit to Dylan-DPC/rust that referenced this issue Mar 22, 2023
…idden-documentation, r=ChrisDenton

Clarify `Error::last_os_error` can be weird

Fundamentally, querying the OS for error codes is a process that is deeply subject to the whims of chance and fortune. We can account for OS, but not for every combination of platform APIs. A compiled binary may not recognize new errors introduced years later. We should clarify a few especially odd situations, and what they mean: We can effectively promise nothing... if you ask for Rust to decode errors where none have occurred.

This allows removing mention of ErrorKind::Uncategorized.
That error variant is hidden deliberately, so we should not explicitly mention it.

This fixes rust-lang#106937.

Since you had an opinion also: Does this solution seem acceptable?
r? `@ChrisDenton`
@bors bors closed this as completed in aeabe34 Mar 23, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants