Better errors

[steveklabnik]

This is the start of my attempt to address #2092.

What this is

Right now, when you compile with an error, you get this:

steve@computer:~/tmp$ cat hello.rs 
fn foo(x: int) {
    match x {
        1 .. 10 => (),
        7       => (),
        _       => (),
    }
}

fn main() {

}
steve@computer:~/tmp$ rustc hello.rs 
hello.rs:4:9: 4:10 error: unreachable pattern [E0001] (pass `--explain E0001` to see a detailed explanation)
hello.rs:4         7       => (),
                   ^
error: aborting due to previous error

Note the [E0001] error code and the ability to get an explanation.

steve@computer:~/tmp$ rustc --explain E0001

    This error suggests that the expression arm corresponding to the noted pattern
    will never be reached as for all possible values of the expression being matched,
    one of the preceeding patterns will match.

    This means that perhaps some of the preceeding patterns are too general, this
    one is too specific or the ordering is incorrect.

This is sweet! But we can do better.

What this adds

With this PR applied, you get this instead:

steve@computer:~/tmp$ rustc hello.rs 
hello.rs:4:9: 4:10 error: unreachable pattern [E0001] (pass `--explain E0001` to see more detail or visit http://doc.rust-lang.org/errors/E0001.html for extensive help with this error)
hello.rs:4         7       => (),
                   ^
error: aborting due to previous error

Along with the doc machinery to generate that page. This should give us a place to provide even more help around errors, and guide people through problems. If they don't have an internet connection, they can see the pages locally as well.

This PR isn't really 'ready' yet, but I wanted to get some feedback. The error pages don't display CSS correctly, and I think I screwed up my git-fu to fix that error message, but I'm about to jump on a plane. Please let me know what you think, and I'll keep working on this if it's a path we want to go down.

[vks]

I think at the moment it is too verbose for a default error message, maybe only show it when passing --explain?

I really like the idea! On the error website we could also link to other resources that might help (IRC etc.).

[jroesch]

cc me

[Gankra]

This is wonderful, and I'd love to help make this more wonderful! Some thoughts:

• Maybe show only (pass --explain E0001 to see more detail), and have --explain provide the extended discussion URL message? This reduces clutter in the compiler output, and provides a nice simple > moderate > advanced progression of the documentation.
• Is the contents of --explain extracted or related to the .md at all? This would seem desirable to avoid maintaining multiple similar documents, and avoid drift/rot.
• Do we want all error help pages to be loose static pages, or do we want the markdown to be parsed and embedded inside a general template like libs?
• Do we want the errors to be indexed and serachable in the same way as libs?

[huonw]

I agree that this makes the error messages too verbose; it's not rare for people on IRC to essentially just ignore what the error message is telling them, because it's just too long (e.g. the "did you mean" suggestions for lifetimes have a long error message, but they include the correct information, but people still just ignore it).

I idly wonder if it's worth supporting nested directories for formatting the doc pages, because we could easily accumulate thousands of them, e.g. E00/E0001.md ... E01/E0123.md ... E02/E0234.md (they would all be rendered to error/Ennnn.html though). shrug

(This should definitely be possible in future, and possibly overengineering.)

Do we want all error help pages to be loose static pages, or do we want the markdown to be parsed and embedded inside a general template like libs?

If they were more connected to the diagnostics macros themselves, we could e.g. have --explain show the same content (especially if we get some form of plain text output for rustdoc, but this would be a somewhat circular dependency...), and possibly make sure that the numbers connect to pages 'correctly'.

[huonw]

The error pages don't display CSS correctly

I think this is because this line is including <link src="rust.css" ...> (or whatever the syntax is) in the HTML; this is fine for the other docs, since rust.css is in the same directory, but should be ../rust.css for these pages, since they're in the error subdir.

[richo]

I almost feel like this should be hidden behind a switch (or at least opt-out-able).

I use a lot of tools that deal with the output of the compiler (and believe I'm not alone in doing this), and the long lines with links in them would significantly clutter up the flow.

Bullish on the principle, but not stoked about the implementation.

[killercup]

Where does the error description in --explain come from? It would probably be a good idea to only have this text in one place.

[ftxqxd]

This is exciting! 😃 I love how extensive Rust’s documentation is getting now. I do share the concerns about long error messages, though.

Maybe this could be separated into a note-like message, similar to the note: expansion site message that appears when an error occurs in a macro expansion? To make it stand out more, perhaps it could be changed to a different colour as well. (Notes are green, warnings are yellow, and errors are red, so maybe this could be a cyan ‘help’ message or something?) Combining this with @vks’s and @gankro’s suggestion of moving the URL to the --explain description, the error looks like this:

hello.rs:4:9: 4:10 error: unreachable pattern [E0001]
hello.rs:4         7       => (),
                   ^
help: pass `--explain E0001` to see more detail
error: aborting due to previous error

which is quite a lot shorter (horizontally) than what we have now, even without this change. The help message would also stand out if it were a different colour, hopefully drawing people’s attention to it.

Regarding duplication of explanations, I think this could be handled later. I’d like it if the --explain description were automatically spliced into the online ‘Summary’ section, but that makes rendering these docs quite complex…

[stormpat]

Great idea! Reminds me of angulars error messages, with links to error pages with more details.

[steveklabnik]

Theres a few things here:

Maybe show only (pass --explain E0001 to see more detail), and have --explain provide the extended discussion URL message? This reduces clutter in the compiler output, and provides a nice simple > moderate > advanced progression of the documentation.

There's tension here: better error output is better for newbies, and more terse output is better for more experienced people or, as @richo mentioned, parsing output. I'm not sure where the right mixture is here.

@huonw you're right about the CSS.

One thing with not matching up the explain text: it allows for a 'short' and 'long' form explanation. Maybe the right answer is to put the URL at the bottom of each explain text, leave the explain in the register call for now, like it is, and leave the extended explanation as the page.

I idly wonder if it's worth supporting nested directories for formatting the doc pages,

Is this because of a lack of inodes or something?

Do we want all error help pages to be loose static pages, or do we want the markdown to be parsed and embedded inside a general template like libs?

It's already embedded inside of the general template, though I'd imagine that eventually, we'd want to change the template around a tiny bit. Unsure.

I really like @P1start 's help: idea, though I have no idea how to implement it.

[Gankra]

@steveklabnik I was thinking something along the lines of --explain outputting the first "section" of what would show up on the full web page. In particular, code samples and references won't show up well in terminal output (I think?), and I think those should be reserved for web.

[steveklabnik]

I was thinking something along the lines of --explain outputting the first "section" of what would show up on the full web page.

This can work, but it also means that it can be awkward sometimes. I'm torn.

(but you're totally right about code, etc)

[Gankra]

@steveklabnik I'm thinking of the following hierarchy/flow:

• Bug occurs: Print the minimal name/desc of the bug, with error number, in terminal, provide usual "hints", and then P1's help message at the bottom. Anyone who clearly sees what the issue really is, isn't distracted. Rookies see the "help" message as the last thing (and are therefore more likely to register it?).
• Explain is passed: Print "this is a summary of the issue, for an indepth explanation, see [URL]", and then print the first section of the web page (everything before the first header, maybe?), which should be an introduction/summary anyway. People who have seen the issue before, or almost understand what's going are easily refreshed/clarified on what this issue is.
• Web page is visited: Everything You Need To Know On This Issue. For those who really don't get why this is an issue, or what the issue even is.

[steveklabnik]

Rookies see the "help" message as the last thing (and are therefore more likely to register it?).

I'm not sure this is true, but I don't think there's any way to figure it out, really. It'd also be nice if it were 😄

[steveklabnik]

(I do like this proposal, though)

[mdinger]

Technically, being brief isn't a huge problem because people often paste weird error messages into Google. Don't know that error C1245 is from visual studio? Search VS error C1245 and you'll usually find a good help page if it's a compiler error.

Verbosity may also be a GUI issue. Visual studio (the older version I used...maybe not the new one) pastes compiler output verbatim. Qt Creator has a second mode which collects the brief descriptions together and only shows the expanded output when you click on the item to expand it. GUIs are probably outside the scope of this bug though.

[steveklabnik]

Don't know that error C1245 is from visual studio? Search VS error C1245 and you'll usually find a good help page if it's a compiler error.

Right, this is the big win of giving them pages in the docs, IMHO.

[vks]

I'm not sure this is true, but I don't think there's any way to figure it out, really. It'd also be nice if it were 😄

I think this is easy to figure out. Write a prototype and ask a few rookies to try it out (or post it on Reddit). Ask them which part of the error message they registered (or registered first/best).

I'm sure there are a few usability experts at Mozilla. Maybe ask them?
(I think it would be pretty cool to have a small usability study on compiler error messages.)

[steveklabnik]

That's not going to have a large enough sample size to matter.

(But yes, a big study would be nice.)

[vks]

That's not going to have a large enough sample size to matter.

Still better than nothing?

[steveklabnik]

I actually don't think so, as it gives you a veil of objectivity without actually being objective.

Anyway, it's a distraction, overall.

[vks]

Well, of course it won't be objective, that is not really the aim. I thought it might cover more potential rookie-pitfalls than just speculating.

[Gankra]

Digging through how this stuff is set up now. All the diagnostic messages are defined in a single file as raw strings in src/librustc/diagnostis.rs. They're registered with some family of macros, which are themselves full-on plugins(!).

That doesn't strike me as a particularly scalable solution if each one of these is going to be a huge discussion of the error. However I'm not sure if there's a technical reason for this, or if this was just convenient/reasonable at the time. Not sure why this had to be done as a macro/plugin either.

A saner alternative might be to just provide the path to the error md, and have them parsed in as plain text, with the #Summary header stripped and everything after the next header (\n# I guess?) excluded. However I'm not clear as to what can or can't be done in librustc's code, especially if things need to be available at early stages of compilation.

However, with this design librustc and librustdoc don't really need to know about each other, they just both know about these docs. Librustc does gain a minor understanding of markdown (in that it knows #'s at starts of lines are important), and the first section of the docs will have to be fairly more well-formed than other doc pages, but not by much.

[alexcrichton]

ping @steveklabnik, is this ready to go?

[aturon]

re-ping @steveklabnik

[mdinger]

s/preceeding/preceding/

[mdinger]

s/preceeding/preceding/

[steveklabnik]

@aturon it's unclear to me that there's any kind of consensus about what the output should be, with and without the flag. If we can make that decision, I'll happily get this ready to merge.

[vks]

@steveklabnik I think there was some consensus that the message is currently too long.

I would be fine with moving the link to the --explain output or at least breaking the super long line, for instance like this:

steve@computer:~/tmp$ rustc hello.rs 
hello.rs:4:9: 4:10 error: unreachable pattern [E0001]
                   (pass `--explain E0001` or visit http://doc.rust-lang.org/errors/E0001.html for more detail)
hello.rs:4         7       => (),
                   ^
error: aborting due to previous error

[nikomatsakis]

💃 just want to show my general delight to see motion on this

[alexcrichton]

Closing due to inactivity (and @bors's queue is quite full!) Feel free to reopen with a rebase!