diff options
| author | Zack M. Davis <code@zackmdavis.net> | 2018-06-30 16:55:13 -0700 |
|---|---|---|
| committer | Who? Me?! <mark-i-m@users.noreply.github.com> | 2018-07-04 17:14:02 -0500 |
| commit | d771413d9d91ed3e05619cd128d13cbb1a90ee47 (patch) | |
| tree | 991ce2e5198663bcee69a7fd706b74440dc540cd /src/doc/rustc-dev-guide | |
| parent | 6fd934ddeaf45ca085eedda5c56191e17858df0b (diff) | |
| download | rust-d771413d9d91ed3e05619cd128d13cbb1a90ee47.tar.gz rust-d771413d9d91ed3e05619cd128d13cbb1a90ee47.zip | |
rewrite suggestions intro to be less bizarrely edition/rustfix centric
The suggestions API was introduced in April 2015 (rust-lang/rust@906a9728ff), long predating rustfix (initial commit July 2016) or editions (RFC 2052 approved September 2017).
Diffstat (limited to 'src/doc/rustc-dev-guide')
| -rw-r--r-- | src/doc/rustc-dev-guide/src/diag.md | 22 |
1 files changed, 13 insertions, 9 deletions
diff --git a/src/doc/rustc-dev-guide/src/diag.md b/src/doc/rustc-dev-guide/src/diag.md index e4c257fd8a4..a0e755718b1 100644 --- a/src/doc/rustc-dev-guide/src/diag.md +++ b/src/doc/rustc-dev-guide/src/diag.md @@ -74,17 +74,21 @@ err.emit(); ## Suggestions -We would like to make edition transitions as smooth as possible. To that end, -[`rustfix`][rustfix] can use compiler suggestions to automatically fix -code. For example, we could use `rustfix` to mechanically apply the `qux` -suggestion from the previous example. However, not all suggestions are -mechanically applicable. We use the +In addition to telling the user exactly _why_ their code is wrong, it's +oftentimes furthermore possible to tell them how to fix it. To this end, +`DiagnosticBuilder` offers a structured suggestions API, which formats code +suggestions pleasingly in the terminal, or (when the `--error-format json` flag +is passed) as JSON for consumption by tools, most notably the [Rust Language +Server][rls] and [`rustfix`][rustfix]. + +[rls]: https://github.com/rust-lang-nursery/rls +[rustfix]: https://github.com/rust-lang-nursery/rustfix + +Not all suggestions should be applied mechanically. Use the [`span_suggestion_with_applicability`][sswa] method of `DiagnosticBuilder` to -inform the emitter of whether a suggestion is mechanically applicable or not. -This information, in turn, is outputed by rustc when the error format is -`json`, which is used by `rustfix`. +make a suggestion while providing a hint to tools whether the suggestion is +mechanically applicable or not. -[rustfix]: https://github.com/rust-lang-nursery/rustfix/ [sswa]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/struct.DiagnosticBuilder.html#method.span_suggestion_with_applicability For example, to make our `qux` suggestion machine-applicable, we would do: |