clippy_lints/src/return_self_not_must_use.rs

   1 use clippy_utils::diagnostics::span_lint_and_help;
   2 use clippy_utils::ty::is_must_use_ty;
   3 use clippy_utils::{nth_arg, return_ty};
   4 use rustc_hir::def_id::LocalDefId;
   5 use rustc_hir::intravisit::FnKind;
   6 use rustc_hir::{Body, FnDecl, HirId, TraitItem, TraitItemKind};
   7 use rustc_lint::{LateContext, LateLintPass, LintContext};
   8 use rustc_middle::lint::in_external_macro;
   9 use rustc_session::{declare_lint_pass, declare_tool_lint};
  10 use rustc_span::{sym, Span};
  11
  12 declare_clippy_lint! {
  13     /// ### What it does
  14     /// This lint warns when a method returning `Self` doesn't have the `#[must_use]` attribute.
  15     ///
  16     /// ### Why is this bad?
  17     /// Methods returning `Self` often create new values, having the `#[must_use]` attribute
  18     /// prevents users from "forgetting" to use the newly created value.
  19     ///
  20     /// The `#[must_use]` attribute can be added to the type itself to ensure that instances
  21     /// are never forgotten. Functions returning a type marked with `#[must_use]` will not be
  22     /// linted, as the usage is already enforced by the type attribute.
  23     ///
  24     /// ### Limitations
  25     /// This lint is only applied on methods taking a `self` argument. It would be mostly noise
  26     /// if it was added on constructors for example.
  27     ///
  28     /// ### Example
  29     /// ```rust
  30     /// pub struct Bar;
  31     /// impl Bar {
  32     ///     // Missing attribute
  33     ///     pub fn bar(&self) -> Self {
  34     ///         Self
  35     ///     }
  36     /// }
  37     /// ```
  38     ///
  39     /// Use instead:
  40     /// ```rust
  41     /// # {
  42     /// // It's better to have the `#[must_use]` attribute on the method like this:
  43     /// pub struct Bar;
  44     /// impl Bar {
  45     ///     #[must_use]
  46     ///     pub fn bar(&self) -> Self {
  47     ///         Self
  48     ///     }
  49     /// }
  50     /// # }
  51     ///
  52     /// # {
  53     /// // Or on the type definition like this:
  54     /// #[must_use]
  55     /// pub struct Bar;
  56     /// impl Bar {
  57     ///     pub fn bar(&self) -> Self {
  58     ///         Self
  59     ///     }
  60     /// }
  61     /// # }
  62     /// ```
  63     #[clippy::version = "1.59.0"]
  64     pub RETURN_SELF_NOT_MUST_USE,
  65     pedantic,
  66     "missing `#[must_use]` annotation on a method returning `Self`"
  67 }
  68
  69 declare_lint_pass!(ReturnSelfNotMustUse => [RETURN_SELF_NOT_MUST_USE]);
  70
  71 fn check_method(cx: &LateContext<'_>, decl: &FnDecl<'_>, fn_def: LocalDefId, span: Span, hir_id: HirId) {
  72     if_chain! {
  73         // If it comes from an external macro, better ignore it.
  74         if !in_external_macro(cx.sess(), span);
  75         if decl.implicit_self.has_implicit_self();
  76         // We only show this warning for public exported methods.
  77         if cx.access_levels.is_exported(fn_def);
  78         // We don't want to emit this lint if the `#[must_use]` attribute is already there.
  79         if !cx.tcx.hir().attrs(hir_id).iter().any(|attr| attr.has_name(sym::must_use));
  80         if cx.tcx.visibility(fn_def.to_def_id()).is_public();
  81         let ret_ty = return_ty(cx, hir_id);
  82         let self_arg = nth_arg(cx, hir_id, 0);
  83         // If `Self` has the same type as the returned type, then we want to warn.
  84         //
  85         // For this check, we don't want to remove the reference on the returned type because if
  86         // there is one, we shouldn't emit a warning!
  87         if self_arg.peel_refs() == ret_ty;
  88         // If `Self` is already marked as `#[must_use]`, no need for the attribute here.
  89         if !is_must_use_ty(cx, ret_ty);
  90
  91         then {
  92             span_lint_and_help(
  93                 cx,
  94                 RETURN_SELF_NOT_MUST_USE,
  95                 span,
  96                 "missing `#[must_use]` attribute on a method returning `Self`",
  97                 None,
  98                 "consider adding the `#[must_use]` attribute to the method or directly to the `Self` type"
  99             );
 100         }
 101     }
 102 }
 103
 104 impl<'tcx> LateLintPass<'tcx> for ReturnSelfNotMustUse {
 105     fn check_fn(
 106         &mut self,
 107         cx: &LateContext<'tcx>,
 108         kind: FnKind<'tcx>,
 109         decl: &'tcx FnDecl<'tcx>,
 110         _: &'tcx Body<'tcx>,
 111         span: Span,
 112         hir_id: HirId,
 113     ) {
 114         if_chain! {
 115             // We are only interested in methods, not in functions or associated functions.
 116             if matches!(kind, FnKind::Method(_, _));
 117             if let Some(fn_def) = cx.tcx.hir().opt_local_def_id(hir_id);
 118             if let Some(impl_def) = cx.tcx.impl_of_method(fn_def.to_def_id());
 119             // We don't want this method to be te implementation of a trait because the
 120             // `#[must_use]` should be put on the trait definition directly.
 121             if cx.tcx.trait_id_of_impl(impl_def).is_none();
 122
 123             then {
 124                 check_method(cx, decl, fn_def, span, hir_id);
 125             }
 126         }
 127     }
 128
 129     fn check_trait_item(&mut self, cx: &LateContext<'tcx>, item: &'tcx TraitItem<'tcx>) {
 130         if let TraitItemKind::Fn(ref sig, _) = item.kind {
 131             check_method(cx, sig.decl, item.def_id, item.span, item.hir_id());
 132         }
 133     }
 134 }