rustc_attr_parsing/attributes/
doc_comment.rs1use 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
60pub(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(Target::Param),
96 ])
97};