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