src/librustdoc/passes/doc_test_lints.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::{span_of_attrs, Pass};
   7 use crate::clean;
   8 use crate::clean::*;
   9 use crate::core::DocContext;
  10 use crate::fold::DocFolder;
  11 use crate::html::markdown::{find_testable_code, ErrorCodes, Ignore, LangString};
  12 use rustc_middle::lint::LintLevelSource;
  13 use rustc_session::lint;
  14
  15 crate const CHECK_PRIVATE_ITEMS_DOC_TESTS: Pass = Pass {
  16     name: "check-private-items-doc-tests",
  17     run: check_private_items_doc_tests,
  18     description: "check private items doc tests",
  19 };
  20
  21 struct PrivateItemDocTestLinter<'a, 'tcx> {
  22     cx: &'a mut DocContext<'tcx>,
  23 }
  24
  25 crate fn check_private_items_doc_tests(krate: Crate, cx: &mut DocContext<'_>) -> Crate {
  26     let mut coll = PrivateItemDocTestLinter { cx };
  27
  28     coll.fold_crate(krate)
  29 }
  30
  31 impl<'a, 'tcx> DocFolder for PrivateItemDocTestLinter<'a, 'tcx> {
  32     fn fold_item(&mut self, item: Item) -> Option<Item> {
  33         let dox = item.attrs.collapsed_doc_value().unwrap_or_else(String::new);
  34
  35         look_for_tests(self.cx, &dox, &item);
  36
  37         Some(self.fold_item_recur(item))
  38     }
  39 }
  40
  41 pub(crate) struct Tests {
  42     pub(crate) found_tests: usize,
  43 }
  44
  45 impl crate::doctest::Tester for Tests {
  46     fn add_test(&mut self, _: String, config: LangString, _: usize) {
  47         if config.rust && config.ignore == Ignore::None {
  48             self.found_tests += 1;
  49         }
  50     }
  51 }
  52
  53 crate fn should_have_doc_example(cx: &DocContext<'_>, item: &clean::Item) -> bool {
  54     if matches!(
  55         *item.kind,
  56         clean::StructFieldItem(_)
  57             | clean::VariantItem(_)
  58             | clean::AssocConstItem(_, _)
  59             | clean::AssocTypeItem(_, _)
  60             | clean::TypedefItem(_, _)
  61             | clean::StaticItem(_)
  62             | clean::ConstantItem(_)
  63             | clean::ExternCrateItem(_, _)
  64             | clean::ImportItem(_)
  65             | clean::PrimitiveItem(_)
  66             | clean::KeywordItem(_)
  67     ) {
  68         return false;
  69     }
  70     let hir_id = cx.tcx.hir().local_def_id_to_hir_id(item.def_id.expect_local());
  71     let (level, source) =
  72         cx.tcx.lint_level_at_node(lint::builtin::MISSING_DOC_CODE_EXAMPLES, hir_id);
  73     level != lint::Level::Allow || matches!(source, LintLevelSource::Default)
  74 }
  75
  76 crate fn look_for_tests<'tcx>(cx: &DocContext<'tcx>, dox: &str, item: &Item) {
  77     let hir_id = match cx.as_local_hir_id(item.def_id) {
  78         Some(hir_id) => hir_id,
  79         None => {
  80             // If non-local, no need to check anything.
  81             return;
  82         }
  83     };
  84
  85     let mut tests = Tests { found_tests: 0 };
  86
  87     find_testable_code(&dox, &mut tests, ErrorCodes::No, false, None);
  88
  89     if tests.found_tests == 0 && cx.tcx.sess.is_nightly_build() {
  90         if should_have_doc_example(cx, &item) {
  91             debug!("reporting error for {:?} (hir_id={:?})", item, hir_id);
  92             let sp = span_of_attrs(&item.attrs).unwrap_or(item.source.span());
  93             cx.tcx.struct_span_lint_hir(
  94                 lint::builtin::MISSING_DOC_CODE_EXAMPLES,
  95                 hir_id,
  96                 sp,
  97                 |lint| lint.build("missing code example in this documentation").emit(),
  98             );
  99         }
 100     } else if tests.found_tests > 0 && !cx.renderinfo.access_levels.is_public(item.def_id) {
 101         cx.tcx.struct_span_lint_hir(
 102             lint::builtin::PRIVATE_DOC_TESTS,
 103             hir_id,
 104             span_of_attrs(&item.attrs).unwrap_or(item.source.span()),
 105             |lint| lint.build("documentation test in private item").emit(),
 106         );
 107     }
 108 }