API documentation suggestion - reduce usage of the ? operator

[mistydemeo]

The Rust std API documentation currently uses the ? operator in a lot of examples. I think this is likely to be confusing to new Rust developers, who probably haven't encountered it before; it's a powerful shorthand, but it's also confusing and hard to look up.

I think it's a particular problem because error messages surrounding ? are unclear and hard to debug for someone who's new to Rust, and it's easy to make mistakes when borrowing from the examples in the API docs.

For example, say a new dev wants to write a function that opens a file and writes to it. That developer has probably already clicked through to the documentation for std::result, which most prominently shows using strings as the Err type for Result. Searching for writing a file, the user then finds the documentation for std::fs::File, and borrows the code in the example at the top of the page since it does what they wanted it to do. Their resulting code looks something like this:

use std::fs::File;
use std::io::prelude::*;

fn test() -> Result<(), &'static str> {
    let mut file = File::create("foo.txt")?;
    file.write_all(b"Hello, world!")?;

    return Ok(());
}

When trying to build, they get the following errors:

 --> test.rs:5:20
  |
5 |     let mut file = File::create("foo.txt")?;
  |                    ^^^^^^^^^^^^^^^^^^^^^^^^ the trait `std::convert::From<std::io::Error>` is not implemented for `&str`
  |
  = note: required by `std::convert::From::from`

error[E0277]: the trait bound `&str: std::convert::From<std::io::Error>` is not satisfied
 --> test.rs:6:5
  |
6 |     file.write_all(b"Hello, world!")?;
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the trait `std::convert::From<std::io::Error>` is not implemented for `&str`
  |
  = note: required by `std::convert::From::from`

It's not clear at all from this what the problem was, or how copying and pasting these examples caused an issue. As you can probably tell, this example's basically my own experience. 😅 I eventually found out what I was doing wrong, but it does feel a bit like I fell into a trap door that didn't need to be there.

cc @steveklabnik

[steveklabnik]

Hey @mistydemeo !

Thanks for this. You're totally right that it's a pain point. I want to back up briefly and lay out why this is, bear with me for a moment 😄

So, an important part of doc examples is showing idiomatic Rust. Using ? is certainly the idiom when you don't want to explicitly handle an error, which is 99% of the doc cases. So we do want to use ?. Part of the underlying reason here is that you want to show off just the part you actually care about, which is what the example does, rather than the error handling. This is also why there's an implicit main.

We're taking a couple of steps to address things:

1. RFC: ? in main rfcs#1937 would let you use ? in main. This would help a lot, but doesn't always help, as it wouldn't in your case.
2. Improve ? error messages per RFC 1859 #35946 is a diagnostic issue we've filed for better diagnostics generally.

So, I think this issue is mostly a duplicate of that second one there. What do you think?

What error message would you have liked to see, in an ideal world?

[mistydemeo]

Sorry for not getting back sooner.

What error message would you have liked to see, in an ideal world?

I think an ideal error message would be clearer about why a conversion is happening, and what the problem is. Say, something like:

5 |     let mut file = File::create("foo.txt")?;
  |                    ^^^^^^^^^^^^^^^^^^^^^^^^ unable to convert from `std::io::Error` to `&str` (`Err(std::io::Error)` returned via `?`)

With the existing message, it's not clear where the Err is being returned or why there's a type conversion issue.

The other issue I found was that I couldn't find the docs for the ? operator. It's not linked to from the API docs where it's used, and it doesn't lend itself to searching either. For the sake of documenting my steps I tried looking for it in the API docs just now... but failed to find it. 😅 I can't find it at https://doc.rust-lang.org/std, or in the book either. The only places I could find information via Google was Stack Overflow (at various levels of up-to-dateness), a few open issues (like #31436), and the RFC. The Syntax and Semantics looks like it might have been the right place to look, but I didn't find it.

So, I appreciate that ? is considered idiomatic and using it is appropriate, but the road from seeing it in the docs to finding out what it means and how to use it is a roadblock to new users. :)

[steveklabnik]

I think an ideal error message would be clearer about why a conversion is happening, and what the problem is. Say, something like:

💯

in the book either.

A good spot to look for "What syntax is this" is https://doc.rust-lang.org/book/first-edition/syntax-index.html, which says ? is like try!. The second edition is built around ? though, so features it here https://doc.rust-lang.org/book/second-edition/ch09-02-recoverable-errors-with-result.html#a-shortcut-for-propagating-errors- , so I'm guessing more people will be aware now that it's actually available.

It's not linked to from the API docs

This is a problem I've been thinking about too, but am not sure what to do with: language features don't have pages in the API docs. That's because, well, they're not part of the API, but since that's the only part of our docs that has search... I guess docs-wide search would fix it, but yeah :/

[mistydemeo]

The second edition is built around ? though, so features it here https://doc.rust-lang.org/book/second-edition/ch09-02-recoverable-errors-with-result.html#a-shortcut-for-propagating-errors- , so I'm guessing more people will be aware now that it's actually available.

Oh yeah, the fact that "question mark operator" is used will help a lot. The ? character isn't really searchable, and the first edition of the book doesn't use that name for it so a search wouldn't bring it up.

Unfortunately the pagerank of the second edition of the book doesn't seem to be great yet - a search for "rust question mark operator" doesn't include the book in the first five pages.

I guess docs-wide search would fix it, but yeah :/

This would be really useful regardless!

[mistydemeo]

I was looking up the Result documentation when I discovered - the ? operator is documented in the API docs! It just isn't mentioned by name, so it can't be searched for.

[lukaslueg]

shamelessly pitching #25967

[steveklabnik]

A small update on this issue: we now have also fixed this in a different way: https://doc.rust-lang.org/nightly/std/fs/fn.create_dir.html