Skip to main content

rustc_attr_parsing/attributes/
doc_comment.rs

1use std::mem;
2
3use rustc_ast::AttrKind;
4use rustc_ast::token::CommentKind;
5use rustc_ast::visit::AssocCtxt;
6use rustc_attr_ir::target::{AstTarget, MethodKind, Target};
7use rustc_errors::{Diagnostic, MultiSpan};
8use rustc_lint_defs::LintId;
9use rustc_lint_defs::builtin::UNUSED_DOC_COMMENTS;
10use rustc_span::Span;
11
12use crate::attributes::prelude::{Allow, Error};
13use crate::diagnostics::{BuiltinUnusedDocComment, BuiltinUnusedDocCommentSub};
14use crate::target_checking::Policy::AllowSilent;
15use crate::target_checking::{AllowedResult, AllowedTargets};
16use crate::{AttributeParser, EmitAttribute, ShouldEmit};
17
18pub(crate) fn target_check_doc_comment(
19    parser: &AttributeParser<'_>,
20    attr: &rustc_ast::Attribute,
21    target: &AstTarget<'_>,
22    target_span: Span,
23    emit_lint: &mut impl FnMut(LintId, MultiSpan, EmitAttribute),
24    has_target_checked_doc_comment: &mut bool,
25) {
26    if #[allow(non_exhaustive_omitted_patterns)] match parser.should_emit {
    ShouldEmit::Nothing => true,
    _ => false,
}matches!(parser.should_emit, ShouldEmit::Nothing) {
27        return;
28    }
29    if mem::replace(has_target_checked_doc_comment, true) {
30        return;
31    }
32    let target = Target::from_ast_target(target);
33    let res = DOC_TARGETS.is_allowed(target);
34    if res == AllowedResult::Allowed {
35        return;
36    }
37
38    let sub = match attr.kind {
39        AttrKind::DocComment(CommentKind::Line, _) | AttrKind::Normal(..) => {
40            BuiltinUnusedDocCommentSub::PlainHelp
41        }
42        AttrKind::DocComment(CommentKind::Block, _) => BuiltinUnusedDocCommentSub::BlockHelp,
43        AttrKind::Synthetic(..) | AttrKind::Generated(..) => ::core::panicking::unreachable_default_msg()unreachable!(),
44    };
45
46    let context =
47        if attr.span.ctxt() == target_span.ctxt() { target_span.shrink_to_lo() } else { attr.span };
48
49    let attr_span = attr.span;
50    emit_lint(
51        LintId::of(UNUSED_DOC_COMMENTS),
52        attr_span.into(),
53        EmitAttribute(Box::new(move |dcx, level, _| {
54            BuiltinUnusedDocComment { sub, target: target.plural_name(), label: attr_span, context }
55                .into_diag(dcx, level)
56        })),
57    );
58}
59
60/// This set of targets is used both for the `doc` attribute and doc comments.
61pub(crate) const DOC_TARGETS: AllowedTargets<'static> = {
62    AllowedTargets::AllowListWarnRest(&[
63        Allow(Target::Use),
64        Allow(Target::Static),
65        Allow(Target::Const),
66        Allow(Target::Fn),
67        Allow(Target::Mod),
68        Allow(Target::Enum),
69        Allow(Target::Variant),
70        Allow(Target::Struct),
71        Allow(Target::Field),
72        Allow(Target::Union),
73        Allow(Target::Trait),
74        Allow(Target::TraitAlias),
75        Allow(Target::TyAlias),
76        Allow(Target::AssocConst(AssocCtxt::Impl { of_trait: false })),
77        Allow(Target::AssocConst(AssocCtxt::Trait)),
78        Allow(Target::AssocConst(AssocCtxt::Impl { of_trait: true })),
79        Allow(Target::Method(MethodKind::Inherent)),
80        Allow(Target::Method(MethodKind::Trait { body: false })),
81        Allow(Target::Method(MethodKind::Trait { body: true })),
82        Allow(Target::Method(MethodKind::TraitImpl)),
83        Allow(Target::AssocTy(AssocCtxt::Impl { of_trait: false })),
84        Allow(Target::AssocTy(AssocCtxt::Trait)),
85        Allow(Target::AssocTy(AssocCtxt::Impl { of_trait: true })),
86        Allow(Target::ForeignFn),
87        Allow(Target::ForeignStatic),
88        Allow(Target::ForeignTy),
89        Allow(Target::MacroDef),
90        Allow(Target::Crate),
91        Allow(Target::ExternCrate),
92        Allow(Target::Impl { of_trait: false }),
93        Allow(Target::Impl { of_trait: true }),
94        AllowSilent(Target::WherePredicate), // Error, checked elsewhere
95        Error(Target::Param),
96    ])
97};