mozilla/rust — pull request #12144 by brson (2014-02-10 02:05:32+00:00)
Title: Give all fatals, errors, and warnings unique diagnostic codes

There's a lot more that can be done to make this useful, but I'm hoping to get at least the error code conversion upstream.

Codes are a single letter followed by four digits, 'C0348'. The letter is just a simple namespace, currently rustc uses 'A', `syntax::ext` uses 'B', and the rest of `syntax` uses 'C'. For errors to be stable we have to live with this scheme forever, so think about it.

The procedure for introducing a new error is:

1) Add a new code to either `libsyntax/diag_index.rs` or `librustc/diag_index.rs`, depending on which crate emits the errors.
2) Use the code in the `span_fatal!`, `span_err!`, `span_warn!`, `alert_fatal!`, `alert_err!`, `alert_warn!` macros:

```
span_fatal!(cx, sp, C0348, "found a rotten {}", vegetable);
```

Then some time later to add a FAQ about it you modify the `diag_db_data.rs` file:

```
(C0348, "

Some markdown about the error.

")
```

When the user hits the error it says

```
../src/test/compile-fail/bad-bang-ann.rs:14:5: 14:36 error: found a rotten potato [C0348*]
../src/test/compile-fail/bad-bang-ann.rs:14 if i < 0u { } else { fail!(); }
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
error: aborting due to previous error
note: some of these errors have extended explanations (see `rustc --explain help`)
```

The error code is displayed in magenta `[C0348*]`, with the asterisk indicating there is additional info. Then there's a note at the end that hints how to use it.

You then run `rustc --explain help` to learn about this feature.

```
Rust includes extended documentation about some compiler errors
that explain in greater depth what the errors means, present examples,
and suggestions for how to fix them.

Each Rust error message has a corresponding code. When emitted by
rustc the code will be included in square brackets, like `[A0001]`. If
the error has additional documentation the code will be appended with
an asterisk, as in `[A0002*]`.

To view the extended documentation, run `rustc --explain A0002`, replacing
'A0002' with your error code.

The extent and quality of extended error documentation depends on user
contributions. To learn how to improve Rust's error documentation visit
http://github.com/mozilla/rust/wiki/Note-extended-diagnostics.
```

You then rust `rustc --explain C0348` to get

```
# C0348: found a rotten {}

Some markdown about the error.
```

## Weaknesses

* There are a lot of very similar errors, particularly in the syntax crate, that all get different codes.
* Lints all fall under a single code for now because they are reported in a way that is not compatible with the macros used in this scheme.
* Splitting up the `diag_index.rs` files when refactoring crates could get ugly.
* Editing docs means editing Rust macros in a .rs file.
* The extended docs use the error's format string as a title, and some of our fmt strings are like "{} {}", which is not instructive. I think we may be able to substitute parameter names into the fmt strings to make them display better.
* Could be documented better.
* No actually extended docs yet.
* This adds a `__tt_map` feature gate and two ugly syntax extensions behind it.

## Future

* Needs to export docs to markdown so examples can be tested
* Need to create wiki page mentioned in `--explain help`