FAQ links in error messages

[nikomatsakis]

On IRC we were discussing how, for complex errors, we ought to put a link to a FAQ in the error message. Perhaps we could even embed the rust manual and print the relevant paragraph if you use rustc --explain or something.

Some examples of errors that could benefit:

• ret disallowed from within sugared closure {|| ... }
• ; required after a statement with non-unit type
• etc.

This of course would also entail making such a FAQ. :)

[brson]

I think this could be really cool, and possibly useful, and has a lot of possibilities. it would be nice if every error had a specific link into the rust documentation for retrieving more info.

[brson]

A start to this would simply be adding a way to associate specific errors with stable ids. One possible design would be to create two enums, one in syntax and one in rustc:

enum Errors {
    AliasedMutableLocationError,
    etc.
}

Make it implement a trait, NamedError that converts the enum to a crate ID (either syntax or rustc)and an error ID (the enum value).

Then add a transaction API to diagnostics that takes a NamedError, then lets you emit any number of messages related to that error.

[alexcrichton]

Just to make sure this was here, I also think it would be great to have example code proving that the check is necessary. Basically some code which shows that if a check weren't in place, the code would crash or it wouldn't be sound in some way.

While I'm at it, I'll also nominate for the production-ready milestone. This would be super-helpful to anyone new to rust.

[graydon]

see also #6806

[graydon]

accepted for production-ready milestone

[emberian]

Triage bump

[bblum]

i noted in the above issue that a good use case for this would be explaining what the send, etc kinds mean.

[catamorphism]

High, but 1.0. Extra goodwill for anyone who implements this!

[emberian]

I was thinking how to implement this the other day actually. Every class of error needs a unique ID first, and a way to expose them when doing span_err etc. Once that infrastructure is in place we can actually have a usable FAQ.

[brson]

I'm starting a patch to do this.

[steveklabnik]

If we had a website where these errors lived, we could get them to rank highly in search engines, making this exceedingly useful.

[brson]

FWIW, my previous patch is utterly bitrotted and any effort here will need to start from scratch.

[nmsmith]

This is a great idea. I think it would be a huge help to programmers. Helping people understand why something they've done is wrong by the compiler, as well as how to resolve the issue, is an essential part of learning the concepts behind the language. A dedicated page for each error linked from the command line can allow us to elaborate on the meaning of the error, justify its existence, and suggest solutions much more effectively than a short text string. Resorting to StackOverflow implies that the compiler isn't able to clearly explain its own rules.

It may also be worthwhile considering passing parameters in the URL that encodes the user's specific instance of the error, so that the help page can tailor itself to the precise problem (i.e. using the same variable names). I'm not sure how feasible that would be, though.

[steveklabnik]

I'm pulling a massive triage effort to get us ready for 1.0. As part of this, I'm moving stuff that's wishlist-like to the RFCs repo, as that's where major new things should get discussed/prioritized.

This issue has been moved to the RFCs repo: rust-lang/rfcs#603