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