src/librustdoc/passes/doc_test_lints.rs

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