Skip to content

Unclear example in io::Error #106937

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

Rollup merge of rust-lang#106964 - workingjubilee:crouching-ioerror-h…

979f472
added a commit that references this issue on Mar 23, 2023

Rollup merge of rust-lang#106964 - workingjubilee:crouching-ioerror-h…

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