From abbead78f7ab2d27ebf556970695472d1cdad44e Mon Sep 17 00:00:00 2001 From: Noah Lev Date: Sat, 2 Oct 2021 14:07:08 -0700 Subject: rustdoc: Improve doctest pass's name and module's name As the docs at the top of the file say, it is an overloaded pass and actually runs two lints. --- src/librustdoc/passes/calculate_doc_coverage.rs | 2 +- src/librustdoc/passes/check_doc_test_visibility.rs | 141 +++++++++++++++++++++ src/librustdoc/passes/doc_test_lints.rs | 141 --------------------- src/librustdoc/passes/mod.rs | 8 +- 4 files changed, 146 insertions(+), 146 deletions(-) create mode 100644 src/librustdoc/passes/check_doc_test_visibility.rs delete mode 100644 src/librustdoc/passes/doc_test_lints.rs (limited to 'src') diff --git a/src/librustdoc/passes/calculate_doc_coverage.rs b/src/librustdoc/passes/calculate_doc_coverage.rs index 721af3313d2..5e3bd41b85c 100644 --- a/src/librustdoc/passes/calculate_doc_coverage.rs +++ b/src/librustdoc/passes/calculate_doc_coverage.rs @@ -2,7 +2,7 @@ use crate::clean; use crate::core::DocContext; use crate::fold::{self, DocFolder}; use crate::html::markdown::{find_testable_code, ErrorCodes}; -use crate::passes::doc_test_lints::{should_have_doc_example, Tests}; +use crate::passes::check_doc_test_visibility::{should_have_doc_example, Tests}; use crate::passes::Pass; use rustc_hir as hir; use rustc_lint::builtin::MISSING_DOCS; diff --git a/src/librustdoc/passes/check_doc_test_visibility.rs b/src/librustdoc/passes/check_doc_test_visibility.rs new file mode 100644 index 00000000000..1f7d6054233 --- /dev/null +++ b/src/librustdoc/passes/check_doc_test_visibility.rs @@ -0,0 +1,141 @@ +//! This pass is overloaded and runs two different lints. +//! +//! - MISSING_DOC_CODE_EXAMPLES: this lint is **UNSTABLE** and looks for public items missing doctests. +//! - PRIVATE_DOC_TESTS: this lint is **STABLE** and looks for private items with doctests. + +use super::Pass; +use crate::clean; +use crate::clean::*; +use crate::core::DocContext; +use crate::fold::DocFolder; +use crate::html::markdown::{find_testable_code, ErrorCodes, Ignore, LangString}; +use crate::visit_ast::inherits_doc_hidden; +use rustc_hir as hir; +use rustc_middle::lint::LintLevelSource; +use rustc_session::lint; +use rustc_span::symbol::sym; + +crate const CHECK_DOC_TEST_VISIBILITY: Pass = Pass { + name: "check_doc_test_visibility", + run: check_doc_test_visibility, + description: "run various visibility-related lints on doctests", +}; + +struct DocTestVisibilityLinter<'a, 'tcx> { + cx: &'a mut DocContext<'tcx>, +} + +crate fn check_doc_test_visibility(krate: Crate, cx: &mut DocContext<'_>) -> Crate { + let mut coll = DocTestVisibilityLinter { cx }; + + coll.fold_crate(krate) +} + +impl<'a, 'tcx> DocFolder for DocTestVisibilityLinter<'a, 'tcx> { + fn fold_item(&mut self, item: Item) -> Option { + let dox = item.attrs.collapsed_doc_value().unwrap_or_else(String::new); + + look_for_tests(self.cx, &dox, &item); + + Some(self.fold_item_recur(item)) + } +} + +pub(crate) struct Tests { + pub(crate) found_tests: usize, +} + +impl crate::doctest::Tester for Tests { + fn add_test(&mut self, _: String, config: LangString, _: usize) { + if config.rust && config.ignore == Ignore::None { + self.found_tests += 1; + } + } +} + +crate fn should_have_doc_example(cx: &DocContext<'_>, item: &clean::Item) -> bool { + if !cx.cache.access_levels.is_public(item.def_id.expect_def_id()) + || matches!( + *item.kind, + clean::StructFieldItem(_) + | clean::VariantItem(_) + | clean::AssocConstItem(_, _) + | clean::AssocTypeItem(_, _) + | clean::TypedefItem(_, _) + | clean::StaticItem(_) + | clean::ConstantItem(_) + | clean::ExternCrateItem { .. } + | clean::ImportItem(_) + | clean::PrimitiveItem(_) + | clean::KeywordItem(_) + // check for trait impl + | clean::ImplItem(clean::Impl { trait_: Some(_), .. }) + ) + { + return false; + } + + // The `expect_def_id()` should be okay because `local_def_id_to_hir_id` + // would presumably panic if a fake `DefIndex` were passed. + let hir_id = cx.tcx.hir().local_def_id_to_hir_id(item.def_id.expect_def_id().expect_local()); + + // check if parent is trait impl + if let Some(parent_hir_id) = cx.tcx.hir().find_parent_node(hir_id) { + if let Some(parent_node) = cx.tcx.hir().find(parent_hir_id) { + if matches!( + parent_node, + hir::Node::Item(hir::Item { + kind: hir::ItemKind::Impl(hir::Impl { of_trait: Some(_), .. }), + .. + }) + ) { + return false; + } + } + } + + if cx.tcx.hir().attrs(hir_id).lists(sym::doc).has_word(sym::hidden) + || inherits_doc_hidden(cx.tcx, hir_id) + || cx.tcx.hir().span(hir_id).in_derive_expansion() + { + return false; + } + let (level, source) = cx.tcx.lint_level_at_node(crate::lint::MISSING_DOC_CODE_EXAMPLES, hir_id); + level != lint::Level::Allow || matches!(source, LintLevelSource::Default) +} + +crate fn look_for_tests<'tcx>(cx: &DocContext<'tcx>, dox: &str, item: &Item) { + let hir_id = match DocContext::as_local_hir_id(cx.tcx, item.def_id) { + Some(hir_id) => hir_id, + None => { + // If non-local, no need to check anything. + return; + } + }; + + let mut tests = Tests { found_tests: 0 }; + + find_testable_code(&dox, &mut tests, ErrorCodes::No, false, None); + + if tests.found_tests == 0 && cx.tcx.sess.is_nightly_build() { + if should_have_doc_example(cx, &item) { + debug!("reporting error for {:?} (hir_id={:?})", item, hir_id); + let sp = item.attr_span(cx.tcx); + cx.tcx.struct_span_lint_hir( + crate::lint::MISSING_DOC_CODE_EXAMPLES, + hir_id, + sp, + |lint| lint.build("missing code example in this documentation").emit(), + ); + } + } else if tests.found_tests > 0 + && !cx.cache.access_levels.is_public(item.def_id.expect_def_id()) + { + cx.tcx.struct_span_lint_hir( + crate::lint::PRIVATE_DOC_TESTS, + hir_id, + item.attr_span(cx.tcx), + |lint| lint.build("documentation test in private item").emit(), + ); + } +} diff --git a/src/librustdoc/passes/doc_test_lints.rs b/src/librustdoc/passes/doc_test_lints.rs deleted file mode 100644 index 279d0dbda82..00000000000 --- a/src/librustdoc/passes/doc_test_lints.rs +++ /dev/null @@ -1,141 +0,0 @@ -//! This pass is overloaded and runs two different lints. -//! -//! - MISSING_DOC_CODE_EXAMPLES: this lint is **UNSTABLE** and looks for public items missing doctests -//! - PRIVATE_DOC_TESTS: this lint is **STABLE** and looks for private items with doctests. - -use super::Pass; -use crate::clean; -use crate::clean::*; -use crate::core::DocContext; -use crate::fold::DocFolder; -use crate::html::markdown::{find_testable_code, ErrorCodes, Ignore, LangString}; -use crate::visit_ast::inherits_doc_hidden; -use rustc_hir as hir; -use rustc_middle::lint::LintLevelSource; -use rustc_session::lint; -use rustc_span::symbol::sym; - -crate const CHECK_PRIVATE_ITEMS_DOC_TESTS: Pass = Pass { - name: "check-private-items-doc-tests", - run: check_private_items_doc_tests, - description: "check private items doc tests", -}; - -struct PrivateItemDocTestLinter<'a, 'tcx> { - cx: &'a mut DocContext<'tcx>, -} - -crate fn check_private_items_doc_tests(krate: Crate, cx: &mut DocContext<'_>) -> Crate { - let mut coll = PrivateItemDocTestLinter { cx }; - - coll.fold_crate(krate) -} - -impl<'a, 'tcx> DocFolder for PrivateItemDocTestLinter<'a, 'tcx> { - fn fold_item(&mut self, item: Item) -> Option { - let dox = item.attrs.collapsed_doc_value().unwrap_or_else(String::new); - - look_for_tests(self.cx, &dox, &item); - - Some(self.fold_item_recur(item)) - } -} - -pub(crate) struct Tests { - pub(crate) found_tests: usize, -} - -impl crate::doctest::Tester for Tests { - fn add_test(&mut self, _: String, config: LangString, _: usize) { - if config.rust && config.ignore == Ignore::None { - self.found_tests += 1; - } - } -} - -crate fn should_have_doc_example(cx: &DocContext<'_>, item: &clean::Item) -> bool { - if !cx.cache.access_levels.is_public(item.def_id.expect_def_id()) - || matches!( - *item.kind, - clean::StructFieldItem(_) - | clean::VariantItem(_) - | clean::AssocConstItem(_, _) - | clean::AssocTypeItem(_, _) - | clean::TypedefItem(_, _) - | clean::StaticItem(_) - | clean::ConstantItem(_) - | clean::ExternCrateItem { .. } - | clean::ImportItem(_) - | clean::PrimitiveItem(_) - | clean::KeywordItem(_) - // check for trait impl - | clean::ImplItem(clean::Impl { trait_: Some(_), .. }) - ) - { - return false; - } - - // The `expect_def_id()` should be okay because `local_def_id_to_hir_id` - // would presumably panic if a fake `DefIndex` were passed. - let hir_id = cx.tcx.hir().local_def_id_to_hir_id(item.def_id.expect_def_id().expect_local()); - - // check if parent is trait impl - if let Some(parent_hir_id) = cx.tcx.hir().find_parent_node(hir_id) { - if let Some(parent_node) = cx.tcx.hir().find(parent_hir_id) { - if matches!( - parent_node, - hir::Node::Item(hir::Item { - kind: hir::ItemKind::Impl(hir::Impl { of_trait: Some(_), .. }), - .. - }) - ) { - return false; - } - } - } - - if cx.tcx.hir().attrs(hir_id).lists(sym::doc).has_word(sym::hidden) - || inherits_doc_hidden(cx.tcx, hir_id) - || cx.tcx.hir().span(hir_id).in_derive_expansion() - { - return false; - } - let (level, source) = cx.tcx.lint_level_at_node(crate::lint::MISSING_DOC_CODE_EXAMPLES, hir_id); - level != lint::Level::Allow || matches!(source, LintLevelSource::Default) -} - -crate fn look_for_tests<'tcx>(cx: &DocContext<'tcx>, dox: &str, item: &Item) { - let hir_id = match DocContext::as_local_hir_id(cx.tcx, item.def_id) { - Some(hir_id) => hir_id, - None => { - // If non-local, no need to check anything. - return; - } - }; - - let mut tests = Tests { found_tests: 0 }; - - find_testable_code(&dox, &mut tests, ErrorCodes::No, false, None); - - if tests.found_tests == 0 && cx.tcx.sess.is_nightly_build() { - if should_have_doc_example(cx, &item) { - debug!("reporting error for {:?} (hir_id={:?})", item, hir_id); - let sp = item.attr_span(cx.tcx); - cx.tcx.struct_span_lint_hir( - crate::lint::MISSING_DOC_CODE_EXAMPLES, - hir_id, - sp, - |lint| lint.build("missing code example in this documentation").emit(), - ); - } - } else if tests.found_tests > 0 - && !cx.cache.access_levels.is_public(item.def_id.expect_def_id()) - { - cx.tcx.struct_span_lint_hir( - crate::lint::PRIVATE_DOC_TESTS, - hir_id, - item.attr_span(cx.tcx), - |lint| lint.build("documentation test in private item").emit(), - ); - } -} diff --git a/src/librustdoc/passes/mod.rs b/src/librustdoc/passes/mod.rs index 0e86fe45640..99ac87db4ff 100644 --- a/src/librustdoc/passes/mod.rs +++ b/src/librustdoc/passes/mod.rs @@ -33,8 +33,8 @@ crate use self::propagate_doc_cfg::PROPAGATE_DOC_CFG; crate mod collect_intra_doc_links; crate use self::collect_intra_doc_links::COLLECT_INTRA_DOC_LINKS; -mod doc_test_lints; -crate use self::doc_test_lints::CHECK_PRIVATE_ITEMS_DOC_TESTS; +mod check_doc_test_visibility; +crate use self::check_doc_test_visibility::CHECK_DOC_TEST_VISIBILITY; mod collect_trait_impls; crate use self::collect_trait_impls::COLLECT_TRAIT_IMPLS; @@ -79,7 +79,7 @@ crate enum Condition { /// The full list of passes. crate const PASSES: &[Pass] = &[ - CHECK_PRIVATE_ITEMS_DOC_TESTS, + CHECK_DOC_TEST_VISIBILITY, STRIP_HIDDEN, UNINDENT_COMMENTS, STRIP_PRIVATE, @@ -97,7 +97,7 @@ crate const PASSES: &[Pass] = &[ crate const DEFAULT_PASSES: &[ConditionalPass] = &[ ConditionalPass::always(COLLECT_TRAIT_IMPLS), ConditionalPass::always(UNINDENT_COMMENTS), - ConditionalPass::always(CHECK_PRIVATE_ITEMS_DOC_TESTS), + ConditionalPass::always(CHECK_DOC_TEST_VISIBILITY), ConditionalPass::new(STRIP_HIDDEN, WhenNotDocumentHidden), ConditionalPass::new(STRIP_PRIVATE, WhenNotDocumentPrivate), ConditionalPass::new(STRIP_PRIV_IMPORTS, WhenDocumentPrivate), -- cgit 1.4.1-3-g733a5