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.