rustdoc/passes/
check_doc_test_visibility.rs

1//! Looks for items missing (or incorrectly having) doctests.
2//!
3//! This pass is overloaded and runs two different lints.
4//!
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.
7
8use rustc_hir as hir;
9use rustc_macros::Diagnostic;
10use rustc_middle::lint::LintLevelSource;
11use tracing::debug;
12
13use crate::clean::utils::inherits_doc_hidden;
14use crate::clean::{self, *};
15use crate::core::DocContext;
16use crate::html::markdown::{
17    CodeLineMapping, ErrorCodes, Ignore, LangString, MdRelLine, find_testable_code,
18};
19use crate::visit::DocVisitor;
20
21struct DocTestVisibilityLinter<'a, 'tcx> {
22    cx: &'a mut DocContext<'tcx>,
23}
24
25pub(super) fn check_doc_test_visibility(krate: Crate, cx: &mut DocContext<'_>) -> Crate {
26    let mut coll = DocTestVisibilityLinter { cx };
27    coll.visit_crate(&krate);
28    krate
29}
30
31impl DocVisitor<'_> for DocTestVisibilityLinter<'_, '_> {
32    fn visit_item(&mut self, item: &Item) {
33        look_for_tests(self.cx, &item.doc_value(), item);
34
35        self.visit_item_recur(item)
36    }
37}
38
39pub(crate) struct Tests {
40    pub(crate) found_tests: usize,
41}
42
43impl crate::doctest::DocTestVisitor for Tests {
44    fn visit_test(&mut self, _: String, config: LangString, _: MdRelLine, _: Vec<CodeLineMapping>) {
45        if config.rust && config.ignore == Ignore::None {
46            self.found_tests += 1;
47        }
48    }
49}
50
51pub(crate) fn should_have_doc_example(cx: &DocContext<'_>, item: &clean::Item) -> bool {
52    if !(cx.cache.effective_visibilities.is_directly_public(cx.tcx, item.item_id.expect_def_id())
53        || item.is_exported_macro())
54        || matches!(
55            item.kind,
56            clean::StructFieldItem(_)
57                | clean::VariantItem(_)
58                | clean::TypeAliasItem(_)
59                | clean::StaticItem(_)
60                | clean::ConstantItem(..)
61                | clean::ExternCrateItem { .. }
62                | clean::ImportItem(_)
63                | clean::PrimitiveItem(_)
64                | clean::KeywordItem
65                | clean::AttributeItem
66                | clean::ModuleItem(_)
67                | clean::TraitAliasItem(_)
68                | clean::ForeignFunctionItem(..)
69                | clean::ForeignStaticItem(..)
70                | clean::ForeignTypeItem
71                | clean::AssocTypeItem(..)
72                | clean::RequiredAssocConstItem(..)
73                | clean::ProvidedAssocConstItem(..)
74                | clean::ImplAssocConstItem(..)
75                | clean::RequiredAssocTypeItem(..)
76                | clean::ImplItem(_)
77                | clean::PlaceholderImplItem
78        )
79    {
80        return false;
81    }
82
83    // The `expect_def_id()` should be okay because `local_def_id_to_hir_id`
84    // would presumably panic if a fake `DefIndex` were passed.
85    let def_id = item.item_id.expect_def_id().expect_local();
86
87    // check if parent is trait impl
88    if let Some(parent_def_id) = cx.tcx.opt_local_parent(def_id)
89        && matches!(
90            cx.tcx.hir_node_by_def_id(parent_def_id),
91            hir::Node::Item(hir::Item {
92                kind: hir::ItemKind::Impl(hir::Impl { of_trait: Some(_), .. }),
93                ..
94            })
95        )
96    {
97        return false;
98    }
99
100    if (!cx.document_hidden()
101        && (cx.tcx.is_doc_hidden(def_id.to_def_id()) || inherits_doc_hidden(cx.tcx, def_id, None)))
102        || cx.tcx.def_span(def_id.to_def_id()).in_derive_expansion()
103    {
104        return false;
105    }
106    let level_spec = cx.tcx.lint_level_spec_at_node(
107        crate::lint::MISSING_DOC_CODE_EXAMPLES,
108        cx.tcx.local_def_id_to_hir_id(def_id),
109    );
110    !level_spec.is_allow() || matches!(level_spec.src, LintLevelSource::Default)
111}
112
113pub(crate) fn look_for_tests(cx: &DocContext<'_>, dox: &str, item: &Item) {
114    #[derive(Diagnostic)]
115    #[diag("missing code example in this documentation")]
116    struct MissingCodeExample;
117
118    #[derive(Diagnostic)]
119    #[diag("documentation test in private item")]
120    struct DoctestInPrivateItem;
121
122    let Some(hir_id) = DocContext::as_local_hir_id(cx.tcx, item.item_id) else {
123        // If non-local, no need to check anything.
124        return;
125    };
126
127    let mut tests = Tests { found_tests: 0 };
128
129    find_testable_code(dox, &mut tests, ErrorCodes::No, None);
130
131    if tests.found_tests == 0 && cx.tcx.features().rustdoc_missing_doc_code_examples() {
132        if should_have_doc_example(cx, item) {
133            debug!("reporting error for {item:?} (hir_id={hir_id:?})");
134            let sp = item.attr_span(cx.tcx);
135            cx.tcx.emit_node_span_lint(
136                crate::lint::MISSING_DOC_CODE_EXAMPLES,
137                hir_id,
138                sp,
139                MissingCodeExample,
140            );
141        }
142    } else if tests.found_tests > 0
143        && !cx.cache.effective_visibilities.is_exported(cx.tcx, item.item_id.expect_def_id())
144    {
145        cx.tcx.emit_node_span_lint(
146            crate::lint::PRIVATE_DOC_TESTS,
147            hir_id,
148            item.attr_span(cx.tcx),
149            DoctestInPrivateItem,
150        );
151    }
152}
rustdoc/passes/check_doc_test_visibility.rs

rustdoc/passes/
check_doc_test_visibility.rs
