src/tools/clippy/clippy_lints/src/utils/diagnostics.rs

   1 //! Clippy wrappers around rustc's diagnostic functions.
   2
   3 use rustc_errors::{Applicability, DiagnosticBuilder};
   4 use rustc_hir::HirId;
   5 use rustc_lint::{LateContext, Lint, LintContext};
   6 use rustc_span::source_map::{MultiSpan, Span};
   7 use std::env;
   8
   9 fn docs_link(diag: &mut DiagnosticBuilder<'_>, lint: &'static Lint) {
  10     if env::var("CLIPPY_DISABLE_DOCS_LINKS").is_err() {
  11         diag.help(&format!(
  12             "for further information visit https://rust-lang.github.io/rust-clippy/{}/index.html#{}",
  13             &option_env!("RUST_RELEASE_NUM").map_or("master".to_string(), |n| {
  14                 // extract just major + minor version and ignore patch versions
  15                 format!("rust-{}", n.rsplitn(2, '.').nth(1).unwrap())
  16             }),
  17             lint.name_lower().replacen("clippy::", "", 1)
  18         ));
  19     }
  20 }
  21
  22 /// Emit a basic lint message with a `msg` and a `span`.
  23 ///
  24 /// This is the most primitive of our lint emission methods and can
  25 /// be a good way to get a new lint started.
  26 ///
  27 /// Usually it's nicer to provide more context for lint messages.
  28 /// Be sure the output is understandable when you use this method.
  29 ///
  30 /// # Example
  31 ///
  32 /// ```ignore
  33 /// error: usage of mem::forget on Drop type
  34 ///   --> $DIR/mem_forget.rs:17:5
  35 ///    |
  36 /// 17 |     std::mem::forget(seven);
  37 ///    |     ^^^^^^^^^^^^^^^^^^^^^^^
  38 /// ```
  39 pub fn span_lint<T: LintContext>(cx: &T, lint: &'static Lint, sp: impl Into<MultiSpan>, msg: &str) {
  40     cx.struct_span_lint(lint, sp, |diag| {
  41         let mut diag = diag.build(msg);
  42         docs_link(&mut diag, lint);
  43         diag.emit();
  44     });
  45 }
  46
  47 /// Same as `span_lint` but with an extra `help` message.
  48 ///
  49 /// Use this if you want to provide some general help but
  50 /// can't provide a specific machine applicable suggestion.
  51 ///
  52 /// The `help` message can be optionally attached to a `Span`.
  53 ///
  54 /// # Example
  55 ///
  56 /// ```ignore
  57 /// error: constant division of 0.0 with 0.0 will always result in NaN
  58 ///   --> $DIR/zero_div_zero.rs:6:25
  59 ///    |
  60 /// 6  |     let other_f64_nan = 0.0f64 / 0.0;
  61 ///    |                         ^^^^^^^^^^^^
  62 ///    |
  63 ///    = help: Consider using `f64::NAN` if you would like a constant representing NaN
  64 /// ```
  65 pub fn span_lint_and_help<'a, T: LintContext>(
  66     cx: &'a T,
  67     lint: &'static Lint,
  68     span: Span,
  69     msg: &str,
  70     help_span: Option<Span>,
  71     help: &str,
  72 ) {
  73     cx.struct_span_lint(lint, span, |diag| {
  74         let mut diag = diag.build(msg);
  75         if let Some(help_span) = help_span {
  76             diag.span_help(help_span, help);
  77         } else {
  78             diag.help(help);
  79         }
  80         docs_link(&mut diag, lint);
  81         diag.emit();
  82     });
  83 }
  84
  85 /// Like `span_lint` but with a `note` section instead of a `help` message.
  86 ///
  87 /// The `note` message is presented separately from the main lint message
  88 /// and is attached to a specific span:
  89 ///
  90 /// # Example
  91 ///
  92 /// ```ignore
  93 /// error: calls to `std::mem::forget` with a reference instead of an owned value. Forgetting a reference does nothing.
  94 ///   --> $DIR/drop_forget_ref.rs:10:5
  95 ///    |
  96 /// 10 |     forget(&SomeStruct);
  97 ///    |     ^^^^^^^^^^^^^^^^^^^
  98 ///    |
  99 ///    = note: `-D clippy::forget-ref` implied by `-D warnings`
 100 /// note: argument has type &SomeStruct
 101 ///   --> $DIR/drop_forget_ref.rs:10:12
 102 ///    |
 103 /// 10 |     forget(&SomeStruct);
 104 ///    |            ^^^^^^^^^^^
 105 /// ```
 106 pub fn span_lint_and_note<'a, T: LintContext>(
 107     cx: &'a T,
 108     lint: &'static Lint,
 109     span: Span,
 110     msg: &str,
 111     note_span: Option<Span>,
 112     note: &str,
 113 ) {
 114     cx.struct_span_lint(lint, span, |diag| {
 115         let mut diag = diag.build(msg);
 116         if let Some(note_span) = note_span {
 117             diag.span_note(note_span, note);
 118         } else {
 119             diag.note(note);
 120         }
 121         docs_link(&mut diag, lint);
 122         diag.emit();
 123     });
 124 }
 125
 126 /// Like `span_lint` but allows to add notes, help and suggestions using a closure.
 127 ///
 128 /// If you need to customize your lint output a lot, use this function.
 129 pub fn span_lint_and_then<'a, T: LintContext, F>(cx: &'a T, lint: &'static Lint, sp: Span, msg: &str, f: F)
 130 where
 131     F: for<'b> FnOnce(&mut DiagnosticBuilder<'b>),
 132 {
 133     cx.struct_span_lint(lint, sp, |diag| {
 134         let mut diag = diag.build(msg);
 135         f(&mut diag);
 136         docs_link(&mut diag, lint);
 137         diag.emit();
 138     });
 139 }
 140
 141 pub fn span_lint_hir(cx: &LateContext<'_>, lint: &'static Lint, hir_id: HirId, sp: Span, msg: &str) {
 142     cx.tcx.struct_span_lint_hir(lint, hir_id, sp, |diag| {
 143         let mut diag = diag.build(msg);
 144         docs_link(&mut diag, lint);
 145         diag.emit();
 146     });
 147 }
 148
 149 pub fn span_lint_hir_and_then(
 150     cx: &LateContext<'_>,
 151     lint: &'static Lint,
 152     hir_id: HirId,
 153     sp: Span,
 154     msg: &str,
 155     f: impl FnOnce(&mut DiagnosticBuilder<'_>),
 156 ) {
 157     cx.tcx.struct_span_lint_hir(lint, hir_id, sp, |diag| {
 158         let mut diag = diag.build(msg);
 159         f(&mut diag);
 160         docs_link(&mut diag, lint);
 161         diag.emit();
 162     });
 163 }
 164
 165 /// Add a span lint with a suggestion on how to fix it.
 166 ///
 167 /// These suggestions can be parsed by rustfix to allow it to automatically fix your code.
 168 /// In the example below, `help` is `"try"` and `sugg` is the suggested replacement `".any(|x| x >
 169 /// 2)"`.
 170 ///
 171 /// ```ignore
 172 /// error: This `.fold` can be more succinctly expressed as `.any`
 173 /// --> $DIR/methods.rs:390:13
 174 ///     |
 175 /// 390 |     let _ = (0..3).fold(false, |acc, x| acc || x > 2);
 176 ///     |                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: try: `.any(|x| x > 2)`
 177 ///     |
 178 ///     = note: `-D fold-any` implied by `-D warnings`
 179 /// ```
 180 #[allow(clippy::collapsible_span_lint_calls)]
 181 pub fn span_lint_and_sugg<'a, T: LintContext>(
 182     cx: &'a T,
 183     lint: &'static Lint,
 184     sp: Span,
 185     msg: &str,
 186     help: &str,
 187     sugg: String,
 188     applicability: Applicability,
 189 ) {
 190     span_lint_and_then(cx, lint, sp, msg, |diag| {
 191         diag.span_suggestion(sp, help, sugg, applicability);
 192     });
 193 }
 194
 195 /// Create a suggestion made from several `span → replacement`.
 196 ///
 197 /// Note: in the JSON format (used by `compiletest_rs`), the help message will
 198 /// appear once per
 199 /// replacement. In human-readable format though, it only appears once before
 200 /// the whole suggestion.
 201 pub fn multispan_sugg<I>(diag: &mut DiagnosticBuilder<'_>, help_msg: &str, sugg: I)
 202 where
 203     I: IntoIterator<Item = (Span, String)>,
 204 {
 205     multispan_sugg_with_applicability(diag, help_msg, Applicability::Unspecified, sugg)
 206 }
 207
 208 pub fn multispan_sugg_with_applicability<I>(
 209     diag: &mut DiagnosticBuilder<'_>,
 210     help_msg: &str,
 211     applicability: Applicability,
 212     sugg: I,
 213 ) where
 214     I: IntoIterator<Item = (Span, String)>,
 215 {
 216     diag.multipart_suggestion(help_msg, sugg.into_iter().collect(), applicability);
 217 }