clippy_lints/src/missing_doc.rs

   1 // Note: More specifically this lint is largely inspired (aka copied) from
   2 // *rustc*'s
   3 // [`missing_doc`].
   4 //
   5 // [`missing_doc`]: https://github.com/rust-lang/rust/blob/cf9cf7c923eb01146971429044f216a3ca905e06/compiler/rustc_lint/src/builtin.rs#L415
   6 //
   7
   8 use clippy_utils::attrs::is_doc_hidden;
   9 use clippy_utils::diagnostics::span_lint;
  10 use clippy_utils::is_from_proc_macro;
  11 use if_chain::if_chain;
  12 use rustc_ast::ast::{self, MetaItem, MetaItemKind};
  13 use rustc_hir as hir;
  14 use rustc_lint::{LateContext, LateLintPass, LintContext};
  15 use rustc_middle::ty::DefIdTree;
  16 use rustc_session::{declare_tool_lint, impl_lint_pass};
  17 use rustc_span::def_id::CRATE_DEF_ID;
  18 use rustc_span::source_map::Span;
  19 use rustc_span::sym;
  20
  21 declare_clippy_lint! {
  22     /// ### What it does
  23     /// Warns if there is missing doc for any documentable item
  24     /// (public or private).
  25     ///
  26     /// ### Why is this bad?
  27     /// Doc is good. *rustc* has a `MISSING_DOCS`
  28     /// allowed-by-default lint for
  29     /// public members, but has no way to enforce documentation of private items.
  30     /// This lint fixes that.
  31     #[clippy::version = "pre 1.29.0"]
  32     pub MISSING_DOCS_IN_PRIVATE_ITEMS,
  33     restriction,
  34     "detects missing documentation for public and private members"
  35 }
  36
  37 pub struct MissingDoc {
  38     /// Stack of whether #[doc(hidden)] is set
  39     /// at each level which has lint attributes.
  40     doc_hidden_stack: Vec<bool>,
  41 }
  42
  43 impl Default for MissingDoc {
  44     #[must_use]
  45     fn default() -> Self {
  46         Self::new()
  47     }
  48 }
  49
  50 impl MissingDoc {
  51     #[must_use]
  52     pub fn new() -> Self {
  53         Self {
  54             doc_hidden_stack: vec![false],
  55         }
  56     }
  57
  58     fn doc_hidden(&self) -> bool {
  59         *self.doc_hidden_stack.last().expect("empty doc_hidden_stack")
  60     }
  61
  62     fn has_include(meta: Option<MetaItem>) -> bool {
  63         if_chain! {
  64             if let Some(meta) = meta;
  65             if let MetaItemKind::List(list) = meta.kind;
  66             if let Some(meta) = list.get(0);
  67             if let Some(name) = meta.ident();
  68             then {
  69                 name.name == sym::include
  70             } else {
  71                 false
  72             }
  73         }
  74     }
  75
  76     fn check_missing_docs_attrs(
  77         &self,
  78         cx: &LateContext<'_>,
  79         attrs: &[ast::Attribute],
  80         sp: Span,
  81         article: &'static str,
  82         desc: &'static str,
  83     ) {
  84         // If we're building a test harness, then warning about
  85         // documentation is probably not really relevant right now.
  86         if cx.sess().opts.test {
  87             return;
  88         }
  89
  90         // `#[doc(hidden)]` disables missing_docs check.
  91         if self.doc_hidden() {
  92             return;
  93         }
  94
  95         if sp.from_expansion() {
  96             return;
  97         }
  98
  99         let has_doc = attrs
 100             .iter()
 101             .any(|a| a.doc_str().is_some() || Self::has_include(a.meta()));
 102         if !has_doc {
 103             span_lint(
 104                 cx,
 105                 MISSING_DOCS_IN_PRIVATE_ITEMS,
 106                 sp,
 107                 &format!("missing documentation for {article} {desc}"),
 108             );
 109         }
 110     }
 111 }
 112
 113 impl_lint_pass!(MissingDoc => [MISSING_DOCS_IN_PRIVATE_ITEMS]);
 114
 115 impl<'tcx> LateLintPass<'tcx> for MissingDoc {
 116     fn enter_lint_attrs(&mut self, _: &LateContext<'tcx>, attrs: &'tcx [ast::Attribute]) {
 117         let doc_hidden = self.doc_hidden() || is_doc_hidden(attrs);
 118         self.doc_hidden_stack.push(doc_hidden);
 119     }
 120
 121     fn exit_lint_attrs(&mut self, _: &LateContext<'tcx>, _: &'tcx [ast::Attribute]) {
 122         self.doc_hidden_stack.pop().expect("empty doc_hidden_stack");
 123     }
 124
 125     fn check_crate(&mut self, cx: &LateContext<'tcx>) {
 126         let attrs = cx.tcx.hir().attrs(hir::CRATE_HIR_ID);
 127         self.check_missing_docs_attrs(cx, attrs, cx.tcx.def_span(CRATE_DEF_ID), "the", "crate");
 128     }
 129
 130     fn check_item(&mut self, cx: &LateContext<'tcx>, it: &'tcx hir::Item<'_>) {
 131         match it.kind {
 132             hir::ItemKind::Fn(..) => {
 133                 // ignore main()
 134                 if it.ident.name == sym::main {
 135                     let at_root = cx.tcx.local_parent(it.def_id.def_id) == CRATE_DEF_ID;
 136                     if at_root {
 137                         return;
 138                     }
 139                 }
 140             },
 141             hir::ItemKind::Const(..)
 142             | hir::ItemKind::Enum(..)
 143             | hir::ItemKind::Macro(..)
 144             | hir::ItemKind::Mod(..)
 145             | hir::ItemKind::Static(..)
 146             | hir::ItemKind::Struct(..)
 147             | hir::ItemKind::Trait(..)
 148             | hir::ItemKind::TraitAlias(..)
 149             | hir::ItemKind::TyAlias(..)
 150             | hir::ItemKind::Union(..)
 151             | hir::ItemKind::OpaqueTy(..) => {},
 152             hir::ItemKind::ExternCrate(..)
 153             | hir::ItemKind::ForeignMod { .. }
 154             | hir::ItemKind::GlobalAsm(..)
 155             | hir::ItemKind::Impl { .. }
 156             | hir::ItemKind::Use(..) => return,
 157         };
 158
 159         let (article, desc) = cx.tcx.article_and_description(it.def_id.to_def_id());
 160
 161         let attrs = cx.tcx.hir().attrs(it.hir_id());
 162         if !is_from_proc_macro(cx, it) {
 163             self.check_missing_docs_attrs(cx, attrs, it.span, article, desc);
 164         }
 165     }
 166
 167     fn check_trait_item(&mut self, cx: &LateContext<'tcx>, trait_item: &'tcx hir::TraitItem<'_>) {
 168         let (article, desc) = cx.tcx.article_and_description(trait_item.def_id.to_def_id());
 169
 170         let attrs = cx.tcx.hir().attrs(trait_item.hir_id());
 171         if !is_from_proc_macro(cx, trait_item) {
 172             self.check_missing_docs_attrs(cx, attrs, trait_item.span, article, desc);
 173         }
 174     }
 175
 176     fn check_impl_item(&mut self, cx: &LateContext<'tcx>, impl_item: &'tcx hir::ImplItem<'_>) {
 177         // If the method is an impl for a trait, don't doc.
 178         if let Some(cid) = cx.tcx.associated_item(impl_item.def_id).impl_container(cx.tcx) {
 179             if cx.tcx.impl_trait_ref(cid).is_some() {
 180                 return;
 181             }
 182         } else {
 183             return;
 184         }
 185
 186         let (article, desc) = cx.tcx.article_and_description(impl_item.def_id.to_def_id());
 187         let attrs = cx.tcx.hir().attrs(impl_item.hir_id());
 188         if !is_from_proc_macro(cx, impl_item) {
 189             self.check_missing_docs_attrs(cx, attrs, impl_item.span, article, desc);
 190         }
 191     }
 192
 193     fn check_field_def(&mut self, cx: &LateContext<'tcx>, sf: &'tcx hir::FieldDef<'_>) {
 194         if !sf.is_positional() {
 195             let attrs = cx.tcx.hir().attrs(sf.hir_id);
 196             if !is_from_proc_macro(cx, sf) {
 197                 self.check_missing_docs_attrs(cx, attrs, sf.span, "a", "struct field");
 198             }
 199         }
 200     }
 201
 202     fn check_variant(&mut self, cx: &LateContext<'tcx>, v: &'tcx hir::Variant<'_>) {
 203         let attrs = cx.tcx.hir().attrs(v.id);
 204         if !is_from_proc_macro(cx, v) {
 205             self.check_missing_docs_attrs(cx, attrs, v.span, "a", "variant");
 206         }
 207     }
 208 }