Skip to content

Unclear example in io::Error #106937

@jbaublitz

Description

@jbaublitz

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.

Activity

added
A-docsArea: Documentation for any part of the project, including the compiler, standard library, and tools
on Jan 16, 2023
amab8901

amab8901 commented on Jan 16, 2023

@amab8901
Contributor

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

jbaublitz

jbaublitz commented on Jan 16, 2023

@jbaublitz
Author

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

workingjubilee commented on Jan 17, 2023

@workingjubilee
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

ChrisDenton commented on Jan 17, 2023

@ChrisDenton
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.

added a commit that references this issue on Mar 22, 2023
979f472
added a commit that references this issue on Mar 23, 2023
aeabe34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-docsArea: Documentation for any part of the project, including the compiler, standard library, and tools

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      Participants

      @ChrisDenton@jbaublitz@workingjubilee@amab8901

      Issue actions

        Unclear example in io::Error · Issue #106937 · rust-lang/rust