1 //! This pass is overloaded and runs two different lints.
3 //! - MISSING_DOC_CODE_EXAMPLES: this lint is **UNSTABLE** and looks for public items missing doc-tests
4 //! - PRIVATE_DOC_TESTS: this lint is **STABLE** and looks for private items with doc-tests.
6 use super::{span_of_attrs, Pass};
9 use crate::core::DocContext;
10 use crate::fold::DocFolder;
11 use crate::html::markdown::{find_testable_code, ErrorCodes, Ignore, LangString};
12 use rustc_session::lint;
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",
20 struct PrivateItemDocTestLinter<'a, 'tcx> {
21 cx: &'a DocContext<'tcx>,
24 impl<'a, 'tcx> PrivateItemDocTestLinter<'a, 'tcx> {
25 fn new(cx: &'a DocContext<'tcx>) -> Self {
26 PrivateItemDocTestLinter { cx }
30 pub fn check_private_items_doc_tests(krate: Crate, cx: &DocContext<'_>) -> Crate {
31 let mut coll = PrivateItemDocTestLinter::new(cx);
33 coll.fold_crate(krate)
36 impl<'a, 'tcx> DocFolder for PrivateItemDocTestLinter<'a, 'tcx> {
37 fn fold_item(&mut self, item: Item) -> Option<Item> {
39 let dox = item.attrs.collapsed_doc_value().unwrap_or_else(String::new);
41 look_for_tests(&cx, &dox, &item);
43 self.fold_item_recur(item)
47 pub(crate) struct Tests {
48 pub(crate) found_tests: usize,
51 impl crate::doctest::Tester for Tests {
52 fn add_test(&mut self, _: String, config: LangString, _: usize) {
53 if config.rust && config.ignore == Ignore::None {
54 self.found_tests += 1;
59 pub fn should_have_doc_example(item_kind: &clean::ItemEnum) -> bool {
61 clean::StructFieldItem(_)
62 | clean::VariantItem(_)
63 | clean::AssocConstItem(_, _)
64 | clean::AssocTypeItem(_, _)
65 | clean::TypedefItem(_, _)
66 | clean::StaticItem(_)
67 | clean::ConstantItem(_)
68 | clean::ExternCrateItem(_, _)
69 | clean::ImportItem(_)
70 | clean::PrimitiveItem(_)
71 | clean::KeywordItem(_)
75 pub fn look_for_tests<'tcx>(cx: &DocContext<'tcx>, dox: &str, item: &Item) {
76 let hir_id = match cx.as_local_hir_id(item.def_id) {
77 Some(hir_id) => hir_id,
79 // If non-local, no need to check anything.
84 let mut tests = Tests { found_tests: 0 };
86 find_testable_code(&dox, &mut tests, ErrorCodes::No, false, None);
88 if tests.found_tests == 0
89 && rustc_feature::UnstableFeatures::from_environment().is_nightly_build()
91 if should_have_doc_example(&item.inner) {
92 debug!("reporting error for {:?} (hir_id={:?})", item, hir_id);
93 let sp = span_of_attrs(&item.attrs).unwrap_or(item.source.span());
94 cx.tcx.struct_span_lint_hir(
95 lint::builtin::MISSING_DOC_CODE_EXAMPLES,
98 |lint| lint.build("missing code example in this documentation").emit(),
101 } else if tests.found_tests > 0 && !cx.renderinfo.borrow().access_levels.is_public(item.def_id)
103 cx.tcx.struct_span_lint_hir(
104 lint::builtin::PRIVATE_DOC_TESTS,
106 span_of_attrs(&item.attrs).unwrap_or(item.source.span()),
107 |lint| lint.build("documentation test in private item").emit(),