From a66550e48e58af7c01a9431a923c39a4be6644ba Mon Sep 17 00:00:00 2001 From: "Zack M. Davis" Date: Sat, 30 Jun 2018 16:55:13 -0700 Subject: [PATCH] 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). --- src/diag.md | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/src/diag.md b/src/diag.md index e4c257fd..a0e75571 100644 --- a/src/diag.md +++ b/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 -[`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`. +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 +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: