src/librustdoc/passes/check_doc_test_visibility.rs

   1 //! This pass is overloaded and runs two different lints.
   2 //!
   3 //! - MISSING_DOC_CODE_EXAMPLES: this lint is **UNSTABLE** and looks for public items missing doctests.
   4 //! - PRIVATE_DOC_TESTS: this lint is **STABLE** and looks for private items with doctests.
   5
   6 use super::Pass;
   7 use crate::clean;
   8 use crate::clean::*;
   9 use crate::core::DocContext;
  10 use crate::html::markdown::{find_testable_code, ErrorCodes, Ignore, LangString};
  11 use crate::visit::DocVisitor;
  12 use crate::visit_ast::inherits_doc_hidden;
  13 use rustc_hir as hir;
  14 use rustc_middle::lint::LintLevelSource;
  15 use rustc_session::lint;
  16 use rustc_span::symbol::sym;
  17
  18 crate const CHECK_DOC_TEST_VISIBILITY: Pass = Pass {
  19     name: "check_doc_test_visibility",
  20     run: check_doc_test_visibility,
  21     description: "run various visibility-related lints on doctests",
  22 };
  23
  24 struct DocTestVisibilityLinter<'a, 'tcx> {
  25     cx: &'a mut DocContext<'tcx>,
  26 }
  27
  28 crate fn check_doc_test_visibility(krate: Crate, cx: &mut DocContext<'_>) -> Crate {
  29     let mut coll = DocTestVisibilityLinter { cx };
  30     coll.visit_crate(&krate);
  31     krate
  32 }
  33
  34 impl<'a, 'tcx> DocVisitor for DocTestVisibilityLinter<'a, 'tcx> {
  35     fn visit_item(&mut self, item: &Item) {
  36         let dox = item.attrs.collapsed_doc_value().unwrap_or_else(String::new);
  37
  38         look_for_tests(self.cx, &dox, &item);
  39
  40         self.visit_item_recur(item)
  41     }
  42 }
  43
  44 pub(crate) struct Tests {
  45     pub(crate) found_tests: usize,
  46 }
  47
  48 impl crate::doctest::Tester for Tests {
  49     fn add_test(&mut self, _: String, config: LangString, _: usize) {
  50         if config.rust && config.ignore == Ignore::None {
  51             self.found_tests += 1;
  52         }
  53     }
  54 }
  55
  56 crate fn should_have_doc_example(cx: &DocContext<'_>, item: &clean::Item) -> bool {
  57     if !cx.cache.access_levels.is_public(item.def_id.expect_def_id())
  58         || matches!(
  59             *item.kind,
  60             clean::StructFieldItem(_)
  61                 | clean::VariantItem(_)
  62                 | clean::AssocConstItem(_, _)
  63                 | clean::AssocTypeItem(_, _)
  64                 | clean::TypedefItem(_, _)
  65                 | clean::StaticItem(_)
  66                 | clean::ConstantItem(_)
  67                 | clean::ExternCrateItem { .. }
  68                 | clean::ImportItem(_)
  69                 | clean::PrimitiveItem(_)
  70                 | clean::KeywordItem(_)
  71                 // check for trait impl
  72                 | clean::ImplItem(clean::Impl { trait_: Some(_), .. })
  73         )
  74     {
  75         return false;
  76     }
  77
  78     // The `expect_def_id()` should be okay because `local_def_id_to_hir_id`
  79     // would presumably panic if a fake `DefIndex` were passed.
  80     let hir_id = cx.tcx.hir().local_def_id_to_hir_id(item.def_id.expect_def_id().expect_local());
  81
  82     // check if parent is trait impl
  83     if let Some(parent_hir_id) = cx.tcx.hir().find_parent_node(hir_id) {
  84         if let Some(parent_node) = cx.tcx.hir().find(parent_hir_id) {
  85             if matches!(
  86                 parent_node,
  87                 hir::Node::Item(hir::Item {
  88                     kind: hir::ItemKind::Impl(hir::Impl { of_trait: Some(_), .. }),
  89                     ..
  90                 })
  91             ) {
  92                 return false;
  93             }
  94         }
  95     }
  96
  97     if cx.tcx.hir().attrs(hir_id).lists(sym::doc).has_word(sym::hidden)
  98         || inherits_doc_hidden(cx.tcx, hir_id)
  99         || cx.tcx.hir().span(hir_id).in_derive_expansion()
 100     {
 101         return false;
 102     }
 103     let (level, source) = cx.tcx.lint_level_at_node(crate::lint::MISSING_DOC_CODE_EXAMPLES, hir_id);
 104     level != lint::Level::Allow || matches!(source, LintLevelSource::Default)
 105 }
 106
 107 crate fn look_for_tests<'tcx>(cx: &DocContext<'tcx>, dox: &str, item: &Item) {
 108     let hir_id = match DocContext::as_local_hir_id(cx.tcx, item.def_id) {
 109         Some(hir_id) => hir_id,
 110         None => {
 111             // If non-local, no need to check anything.
 112             return;
 113         }
 114     };
 115
 116     let mut tests = Tests { found_tests: 0 };
 117
 118     find_testable_code(dox, &mut tests, ErrorCodes::No, false, None);
 119
 120     if tests.found_tests == 0 && cx.tcx.sess.is_nightly_build() {
 121         if should_have_doc_example(cx, item) {
 122             debug!("reporting error for {:?} (hir_id={:?})", item, hir_id);
 123             let sp = item.attr_span(cx.tcx);
 124             cx.tcx.struct_span_lint_hir(
 125                 crate::lint::MISSING_DOC_CODE_EXAMPLES,
 126                 hir_id,
 127                 sp,
 128                 |lint| lint.build("missing code example in this documentation").emit(),
 129             );
 130         }
 131     } else if tests.found_tests > 0
 132         && !cx.cache.access_levels.is_public(item.def_id.expect_def_id())
 133     {
 134         cx.tcx.struct_span_lint_hir(
 135             crate::lint::PRIVATE_DOC_TESTS,
 136             hir_id,
 137             item.attr_span(cx.tcx),
 138             |lint| lint.build("documentation test in private item").emit(),
 139         );
 140     }
 141 }