1use rustc_ast::ast::{AttrStyle, LitKind, MetaItemLit};
2use rustc_attr_ir::target::{AstTarget, ConstTypeAstTarget, Target};
3use rustc_attr_ir::{
4 AttributeKind, CfgEntry, CfgHideShow, DocAttribute, DocCfgHideShow, DocCfgHideShowValue,
5 DocInline, HideOrShow, NotableTraitColor,
6};
7use rustc_data_structures::fx::{FxHashSet, FxIndexMap, IndexEntry};
8use rustc_errors::{Applicability, MultiSpan, msg};
9use rustc_feature::AttributeStability;
10use rustc_lint_defs::builtin::{INVALID_DOC_ATTRIBUTES, UNUSED_ATTRIBUTES};
11use rustc_span::{Span, Symbol, edition, kw, sym};
12
13use super::prelude::AllowedTargets;
14use super::{AcceptMapping, AttributeParser, template};
15use crate::attributes::doc_comment::DOC_TARGETS;
16use crate::context::{AcceptContext, FinalizeContext};
17use crate::diagnostics::{
18 DocAliasBadChar, DocAliasDuplicated, DocAliasEmpty, DocAliasMalformed, DocAliasStartEnd,
19 DocAttrNotCrateLevel, DocAttrNotTraitLevel, DocAttributeNotAttribute,
20 DocAutoCfgExpectsHideOrShow, DocAutoCfgHideShowExpectsList,
21 DocAutoCfgHideShowNoIdentBeforeValues, DocAutoCfgHideShowUnexpectedItem,
22 DocAutoCfgHideShowUnexpectedItemAfterValues, DocAutoCfgHideShowValuesMix,
23 DocAutoCfgWrongLiteral, DocInlineConflict, DocInlineOnlyUse, DocKeywordAttributeNotAnonConst,
24 DocKeywordNotKeyword, DocTestLiteral, DocTestTakesList, DocTestUnknown, DocUnknownAny,
25 DocUnknownInclude, DocUnknownPasses, DocUnknownPlugins, DocUnknownSpotlight,
26 DuplicateNotableTraitColor, ExpectedNameValue, ExpectedNoArgs, IllFormedAttributeInput,
27 InvalidNotableTraitAttr, InvalidNotableTraitColor, MalformedDoc, UnusedDuplicate,
28};
29use crate::parser::{
30 ArgParser, MetaItemListParser, MetaItemOrLitParser, MetaItemParser, OwnedPathParser,
31};
32use crate::target_checking::Policy::{Allow, AllowSilent};
33
34fn check_keyword(cx: &mut AcceptContext<'_, '_>, keyword: Symbol, span: Span) -> bool {
35 if keyword.is_reserved(|| edition::LATEST_STABLE_EDITION)
39 || keyword.is_weak()
40 || keyword == sym::SelfTy
41 {
42 return true;
43 }
44 cx.emit_err(DocKeywordNotKeyword { span, keyword });
45 false
46}
47
48fn check_attribute(cx: &mut AcceptContext<'_, '_>, attribute: Symbol, span: Span) -> bool {
49 if rustc_feature::BUILTIN_ATTRIBUTE_SET.contains(&attribute) {
51 return true;
52 }
53 cx.emit_err(DocAttributeNotAttribute { span, attribute });
54 false
55}
56
57fn check_attr_not_crate_level(
59 cx: &mut AcceptContext<'_, '_>,
60 span: Span,
61 attr_name: Symbol,
62) -> bool {
63 if cx.shared.target == Target::Crate {
64 cx.emit_err(DocAttrNotCrateLevel { span, attr_name });
65 return false;
66 }
67 true
68}
69
70fn expected_name_value(cx: &mut AcceptContext<'_, '_>, span: Span, _name: Option<Symbol>) {
72 cx.emit_lint(INVALID_DOC_ATTRIBUTES, ExpectedNameValue, span);
73}
74
75fn expected_no_args(cx: &mut AcceptContext<'_, '_>, span: Span) {
77 cx.emit_lint(INVALID_DOC_ATTRIBUTES, ExpectedNoArgs, span);
78}
79
80fn expected_string_literal(
83 cx: &mut AcceptContext<'_, '_>,
84 span: Span,
85 _actual_literal: Option<&MetaItemLit>,
86) {
87 cx.emit_lint(INVALID_DOC_ATTRIBUTES, MalformedDoc, span);
88}
89
90fn parse_notable_trait(
91 cx: &mut AcceptContext<'_, '_>,
92 path: &OwnedPathParser,
93 args: &ArgParser,
94 attr_value: &mut Option<(Option<(NotableTraitColor, Span)>, Span)>,
95 attr_name: Symbol,
96) {
97 let span = path.span();
98
99 let notable_trait_color_attr = match args {
100 ArgParser::NoArgs => None,
101 ArgParser::List(meta_item_list_parser) => {
102 if meta_item_list_parser.is_empty() {
103 None
104 } else if let Some(meta_item) = meta_item_list_parser.as_single() {
105 Some(meta_item)
106 } else {
107 let color_spans: Option<Vec<_>> = meta_item_list_parser
108 .mixed()
109 .map(|item| {
110 let meta = item.meta_item()?;
111 meta.path().word_is(sym::color).then(|| meta.path().span())
112 })
113 .collect();
114
115 if let Some(color_spans) = color_spans {
116 let first_span = color_spans[0];
117 let duplicate_spans = &color_spans[1..];
118
119 let mut spans = MultiSpan::from_spans(duplicate_spans.to_vec());
120 spans.push_span_label(first_span, "");
121
122 for &duplicate_span in duplicate_spans {
123 spans.push_span_label(duplicate_span, rustc_errors::DiagMessage::Inline(std::borrow::Cow::Borrowed("multiple colors specified"))msg!("multiple colors specified"));
124 }
125
126 cx.emit_lint(INVALID_DOC_ATTRIBUTES, DuplicateNotableTraitColor, spans);
127 } else {
128 let spans = meta_item_list_parser
129 .mixed()
130 .map(|item| match item.meta_item() {
131 Some(meta) => meta.path().span(),
132 None => item.span(),
133 })
134 .collect();
135
136 cx.emit_lint(
137 INVALID_DOC_ATTRIBUTES,
138 InvalidNotableTraitAttr,
139 MultiSpan::from_spans(spans),
140 );
141 }
142
143 return;
144 }
145 }
146 ArgParser::NameValue(_) => {
147 cx.emit_lint(INVALID_DOC_ATTRIBUTES, InvalidNotableTraitAttr, span);
150 return;
151 }
152 };
153
154 let notable_trait_color_and_span = if let Some(notable_trait_color_attr) =
155 notable_trait_color_attr
156 {
157 let Some(notable_trait_color_attr) = notable_trait_color_attr.meta_item() else {
158 cx.emit_lint(INVALID_DOC_ATTRIBUTES, InvalidNotableTraitAttr, span);
159 return;
160 };
161 if !notable_trait_color_attr.path().word_is(sym::color) {
162 cx.emit_lint(INVALID_DOC_ATTRIBUTES, InvalidNotableTraitAttr, span);
163 return;
164 }
165 let Some(notable_trait_color) = notable_trait_color_attr.args().as_name_value() else {
166 cx.emit_lint(
167 INVALID_DOC_ATTRIBUTES,
168 InvalidNotableTraitAttr,
169 notable_trait_color_attr.path().span(),
170 );
171 return;
172 };
173
174 let color_value_span = notable_trait_color.value_span;
175
176 let Some(notable_trait_color) = notable_trait_color.value_as_str() else {
177 cx.emit_lint(INVALID_DOC_ATTRIBUTES, InvalidNotableTraitAttr, span);
178 return;
179 };
180
181 let notable_trait_color = match notable_trait_color.as_str() {
182 "grey" | "gray" => NotableTraitColor::Grey,
183 "red" => NotableTraitColor::Red,
184 "green" => NotableTraitColor::Green,
185 "yellow" => NotableTraitColor::Yellow,
186 "blue" => NotableTraitColor::Blue,
187 "magenta" => NotableTraitColor::Magenta,
188 "cyan" => NotableTraitColor::Cyan,
189 "transparent" => NotableTraitColor::Transparent,
190 _ => {
191 cx.emit_lint(INVALID_DOC_ATTRIBUTES, InvalidNotableTraitColor, color_value_span);
192 return;
193 }
194 };
195 Some((notable_trait_color, notable_trait_color_attr.span()))
196 } else {
197 None
198 };
199
200 if cx.shared.target != Target::Trait {
201 cx.emit_lint(INVALID_DOC_ATTRIBUTES, DocAttrNotTraitLevel { span, attr_name }, span);
202 return;
203 }
204
205 *attr_value = Some((notable_trait_color_and_span, span));
206}
207
208fn parse_keyword_and_attribute(
209 cx: &mut AcceptContext<'_, '_>,
210 path: &OwnedPathParser,
211 args: &ArgParser,
212 attr_value: &mut Option<(Symbol, Span)>,
213 attr_name: Symbol,
214) {
215 let Some(nv) = args.as_name_value() else {
216 expected_name_value(cx, args.span().unwrap_or(path.span()), path.word_sym());
217 return;
218 };
219
220 let Some(value) = nv.value_as_str() else {
221 expected_string_literal(cx, nv.value_span, Some(nv.value_as_lit()));
222 return;
223 };
224
225 let ret = if attr_name == sym::keyword {
226 check_keyword(cx, value, nv.value_span)
227 } else {
228 check_attribute(cx, value, nv.value_span)
229 };
230 if !ret {
231 return;
232 }
233
234 let span = path.span();
235 if attr_value.is_some() {
236 cx.adcx().duplicate_key(span, path.word_sym().unwrap());
237 return;
238 }
239
240 if !check_attr_not_crate_level(cx, span, attr_name) {
241 return;
242 }
243
244 if !#[allow(non_exhaustive_omitted_patterns)] match cx.ast_target {
AstTarget::Const(ConstTypeAstTarget::ConstItem(item)) if
item.ident.name == kw::Underscore => true,
_ => false,
}matches!(
245 cx.ast_target,
246 AstTarget::Const(ConstTypeAstTarget::ConstItem(item))
247 if item.ident.name == kw::Underscore)
248 {
249 cx.emit_err(DocKeywordAttributeNotAnonConst { span, attr_name });
250 return;
251 }
252
253 *attr_value = Some((value, span));
254}
255
256#[derive(#[automatically_derived]impl ::core::default::Default for DocParser {
#[inline]
fn default() -> Self {
DocParser {
attribute: ::core::default::Default::default(),
nb_doc_attrs: ::core::default::Default::default(),
}
}
}Default, #[automatically_derived]impl ::core::fmt::Debug for DocParser {
#[inline]
#[rustc_trivial_field_reads]
fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
::core::fmt::Formatter::debug_struct_field2_finish(f,
"DocParser attribute nb_doc_attrs", &self.attribute,
&&self.nb_doc_attrs)
}
}Debug)]
257pub(crate) struct DocParser {
258 attribute: DocAttribute,
259 nb_doc_attrs: usize,
260}
261
262impl DocParser {
263 fn parse_single_test_doc_attr_item(
264 &mut self,
265 cx: &mut AcceptContext<'_, '_>,
266 mip: &MetaItemParser,
267 ) {
268 let path = mip.path();
269 let args = mip.args();
270
271 match path.word_sym() {
272 Some(sym::no_crate_inject) => {
273 if let Err(span) = args.as_no_args() {
274 expected_no_args(cx, span);
275 return;
276 }
277
278 if let Some(used_span) = self.attribute.no_crate_inject {
279 let unused_span = path.span();
280 cx.emit_lint(
281 INVALID_DOC_ATTRIBUTES,
282 UnusedDuplicate { this: unused_span, other: used_span, warning: true },
283 unused_span,
284 );
285 return;
286 }
287
288 cx.check_target(
289 sym::no_crate_inject.as_str(),
290 &AllowedTargets::AllowListWarnRest(&[
291 Allow(Target::Crate),
292 AllowSilent(Target::Param),
293 ]),
294 );
295
296 self.attribute.no_crate_inject = Some(path.span())
297 }
298 Some(sym::attr) => {
299 let Some(list) = args.as_list() else {
300 let span = cx.attr_span;
303 cx.emit_lint(INVALID_DOC_ATTRIBUTES, MalformedDoc, span);
304 return;
305 };
306 for attr in list.mixed() {
309 attr.ignore_args();
311 self.attribute.test_attrs.push(attr.span());
312 }
313 }
314 Some(name) => {
315 cx.emit_lint(INVALID_DOC_ATTRIBUTES, DocTestUnknown { name }, path.span());
316 }
317 None => {
318 cx.emit_lint(INVALID_DOC_ATTRIBUTES, DocTestLiteral, path.span());
319 }
320 }
321 }
322
323 fn add_alias(&mut self, cx: &mut AcceptContext<'_, '_>, alias: Symbol, span: Span) {
324 let attr_str = "`#[doc(alias = \"...\")]`";
325 if alias == sym::empty {
326 cx.emit_err(DocAliasEmpty { span, attr_str });
327 return;
328 }
329
330 let alias_str = alias.as_str();
331 if let Some(c) =
332 alias_str.chars().find(|&c| c == '"' || c == '\'' || (c.is_whitespace() && c != ' '))
333 {
334 cx.emit_err(DocAliasBadChar { span, attr_str, char_: c });
335 return;
336 }
337 if alias_str.starts_with(' ') || alias_str.ends_with(' ') {
338 cx.emit_err(DocAliasStartEnd { span, attr_str });
339 return;
340 }
341 if !check_attr_not_crate_level(cx, span, sym::alias) {
342 return;
343 }
344
345 if let Some(first_definition) = self.attribute.aliases.get(&alias).copied() {
346 cx.emit_lint(UNUSED_ATTRIBUTES, DocAliasDuplicated { first_definition }, span);
347 }
348
349 self.attribute.aliases.insert(alias, span);
350 }
351
352 fn parse_alias(
353 &mut self,
354 cx: &mut AcceptContext<'_, '_>,
355 path: &OwnedPathParser,
356 args: &ArgParser,
357 ) {
358 match args {
359 ArgParser::NoArgs => {
360 cx.emit_err(DocAliasMalformed { span: args.span().unwrap_or(path.span()) });
361 }
362 ArgParser::List(list) => {
363 for i in list.mixed() {
364 let Some(alias) = cx.expect_string_literal(i) else {
365 continue;
366 };
367
368 self.add_alias(cx, alias, i.span());
369 }
370 }
371 ArgParser::NameValue(nv) => {
372 let Some(alias) = cx.expect_string_literal(nv) else {
373 return;
374 };
375 self.add_alias(cx, alias, nv.value_span);
376 }
377 }
378 }
379
380 fn parse_inline(
381 &mut self,
382 cx: &mut AcceptContext<'_, '_>,
383 path: &OwnedPathParser,
384 args: &ArgParser,
385 inline: DocInline,
386 ) {
387 if let Err(span) = args.as_no_args() {
388 expected_no_args(cx, span);
389 return;
390 }
391
392 let span = path.span();
393 if let Some((previous_inline, previous_span)) = self.attribute.inline {
394 if previous_inline != inline {
395 let mut spans = MultiSpan::from_spans(::alloc::boxed::box_assume_init_into_vec_unsafe(::alloc::intrinsics::write_box_via_move(::alloc::boxed::Box::new_uninit(),
[previous_span, span]))vec![previous_span, span]);
396 spans.push_span_label(previous_span, rustc_errors::DiagMessage::Inline(std::borrow::Cow::Borrowed("this attribute..."))msg!("this attribute..."));
397 spans.push_span_label(span, rustc_errors::DiagMessage::Inline(std::borrow::Cow::Borrowed("{\".\"}..conflicts with this attribute"))msg!("{\".\"}..conflicts with this attribute"));
398 cx.emit_err(DocInlineConflict { spans });
399 }
400 } else {
401 self.attribute.inline = Some((inline, span));
402 }
403
404 match cx.target {
405 Target::Use | Target::ExternCrate | Target::Param => {} _ => {
407 let item_span = cx.target_span;
408 cx.emit_lint(
409 INVALID_DOC_ATTRIBUTES,
410 DocInlineOnlyUse { attr_span: span, item_span },
411 span,
412 );
413 }
414 }
415 }
416
417 fn parse_cfg(&mut self, cx: &mut AcceptContext<'_, '_>, args: &ArgParser) {
418 fn simplify_cfg(cfg_entry: &mut CfgEntry) {
420 match cfg_entry {
421 CfgEntry::All(cfgs, span) if cfgs.is_empty() => {
422 *cfg_entry = CfgEntry::Bool(true, *span)
423 }
424 CfgEntry::Any(cfgs, span) if cfgs.is_empty() => {
425 *cfg_entry = CfgEntry::Bool(false, *span)
426 }
427 CfgEntry::Not(cfg, _) => simplify_cfg(cfg),
428 _ => {}
429 }
430 }
431 if let Some(mut cfg_entry) = super::cfg::parse_cfg(cx, args) {
432 simplify_cfg(&mut cfg_entry);
433 self.attribute.cfg.push(cfg_entry);
434 }
435 }
436
437 fn parse_auto_cfg_values(
439 &self,
440 cx: &mut AcceptContext<'_, '_>,
441 list: &MetaItemListParser,
442 values: &mut Option<DocCfgHideShow>,
443 ) {
444 let mut cfg_values = DocCfgHideShow::new();
445
446 let mut values_set = FxHashSet::default();
447 for item in list.mixed() {
448 match item {
449 MetaItemOrLitParser::Lit(MetaItemLit {
451 kind: LitKind::Str(symbol, _),
452 span,
453 ..
454 }) => match &mut cfg_values {
455 DocCfgHideShow::Any(any_span) => {
456 cx.emit_lint(
457 INVALID_DOC_ATTRIBUTES,
458 DocAutoCfgHideShowValuesMix { value_span: *span },
459 *any_span,
460 );
461 }
462 DocCfgHideShow::List(symbols) => {
463 if values_set.insert(symbol) {
464 symbols.push(DocCfgHideShowValue::new(*symbol, *span));
465 }
466 }
467 },
468 MetaItemOrLitParser::Lit(lit) => cx.emit_lint(
470 INVALID_DOC_ATTRIBUTES,
471 DocAutoCfgHideShowUnexpectedItem { attr_name: lit.symbol },
472 lit.span,
473 ),
474 MetaItemOrLitParser::MetaItemParser(sub_item) => {
477 let Some(ident) = sub_item.ident() else {
478 cx.adcx().expected_identifier(sub_item.path().span());
479 continue;
480 };
481 if [sym::any, sym::none].contains(&ident.name)
482 && let ArgParser::List(list) = sub_item.args()
483 && list.mixed().count() == 0
484 {
485 if ident.name == sym::any {
486 if let DocCfgHideShow::List(values) = &cfg_values
487 && let Some(value) = values.first()
488 {
489 cx.emit_lint(
490 INVALID_DOC_ATTRIBUTES,
491 DocAutoCfgHideShowValuesMix { value_span: value.span },
492 sub_item.span(),
493 );
494 } else {
495 cfg_values.merge_with(&DocCfgHideShow::Any(sub_item.span()));
496 }
497 } else {
498 cfg_values.push_none(sub_item.span());
499 }
500 } else {
501 cx.emit_lint(
502 INVALID_DOC_ATTRIBUTES,
503 DocAutoCfgHideShowUnexpectedItem { attr_name: ident.name },
504 sub_item.span(),
505 );
506 }
507 }
508 }
509 }
510 *values = Some(cfg_values);
511 }
512
513 fn parse_auto_cfg(
514 &mut self,
515 cx: &mut AcceptContext<'_, '_>,
516 path: &OwnedPathParser,
517 args: &ArgParser,
518 ) {
519 match args {
520 ArgParser::NoArgs => {
521 self.attribute.auto_cfg_change.push((true, path.span()));
522 }
523 ArgParser::List(list) => {
524 'main: for meta in list.mixed() {
525 let MetaItemOrLitParser::MetaItemParser(item) = meta else {
526 cx.emit_lint(
527 INVALID_DOC_ATTRIBUTES,
528 DocAutoCfgExpectsHideOrShow,
529 meta.span(),
530 );
531 continue;
532 };
533 let (kind, attr_name) = match item.path().word_sym() {
536 Some(sym::hide) => (HideOrShow::Hide, sym::hide),
537 Some(sym::show) => (HideOrShow::Show, sym::show),
538 _ => {
539 cx.emit_lint(
540 INVALID_DOC_ATTRIBUTES,
541 DocAutoCfgExpectsHideOrShow,
542 item.span(),
543 );
544 continue;
545 }
546 };
547 let ArgParser::List(list) = item.args() else {
548 cx.emit_lint(
549 INVALID_DOC_ATTRIBUTES,
550 DocAutoCfgHideShowExpectsList { attr_name },
551 item.span(),
552 );
553 continue;
554 };
555
556 let mut cfg_hide_show = CfgHideShow { kind, values: FxIndexMap::default() };
557
558 let mut cfg_names = FxHashSet::default();
559 let mut values = None;
560 for item in list.mixed() {
561 let MetaItemOrLitParser::MetaItemParser(sub_item) = item else {
562 cx.emit_lint(
563 INVALID_DOC_ATTRIBUTES,
564 DocAutoCfgHideShowUnexpectedItem { attr_name },
565 item.span(),
566 );
567 continue 'main;
568 };
569 match sub_item.args() {
570 ArgParser::NoArgs if values.is_none() => {
571 let Some(name) = sub_item.path().word_sym() else {
572 cx.adcx().expected_identifier(sub_item.path().span());
573 continue 'main;
574 };
575 cfg_names.insert(name);
576 }
577 ArgParser::List(list) if values.is_none() => {
579 let Some(sym::values) = sub_item.path().word_sym() else {
580 cx.adcx().expected_identifier(sub_item.path().span());
581 continue 'main;
582 };
583 if cfg_names.is_empty() {
584 cx.emit_lint(
585 INVALID_DOC_ATTRIBUTES,
586 DocAutoCfgHideShowNoIdentBeforeValues,
587 sub_item.span(),
588 );
589 continue 'main;
590 }
591 self.parse_auto_cfg_values(cx, list, &mut values);
592 }
593 ArgParser::NameValue(_) => {
595 cx.emit_lint(
596 INVALID_DOC_ATTRIBUTES,
597 DocAutoCfgHideShowUnexpectedItem { attr_name },
598 sub_item.span(),
599 );
600 }
601 _ => {
603 cx.emit_lint(
604 INVALID_DOC_ATTRIBUTES,
605 DocAutoCfgHideShowUnexpectedItemAfterValues,
606 sub_item.span(),
607 );
608 }
609 }
610 }
611
612 let values = values.unwrap_or(DocCfgHideShow::new_with_only_key(item.span()));
613 #[allow(rustc::potential_query_instability)]
614 for cfg_name in &cfg_names {
615 match cfg_hide_show.values.entry(*cfg_name) {
616 IndexEntry::Vacant(v) => {
617 v.insert(values.clone());
618 }
619 IndexEntry::Occupied(mut o) => {
620 o.get_mut().merge_with(&values);
621 }
622 }
623 }
624 self.attribute.auto_cfg.push((cfg_hide_show, path.span()));
625 }
626 }
627 ArgParser::NameValue(nv) => {
628 let MetaItemLit { kind: LitKind::Bool(bool_value), span, .. } = nv.value_as_lit()
629 else {
630 cx.emit_lint(INVALID_DOC_ATTRIBUTES, DocAutoCfgWrongLiteral, nv.value_span);
631 return;
632 };
633 self.attribute.auto_cfg_change.push((*bool_value, *span));
634 }
635 }
636 }
637
638 fn parse_single_doc_attr_item(&mut self, cx: &mut AcceptContext<'_, '_>, mip: &MetaItemParser) {
639 let path = mip.path();
640 let args = mip.args();
641
642 macro_rules! no_args {
643 ($ident: ident) => {{
644 if let Err(span) = args.as_no_args() {
645 expected_no_args(cx, span);
646 return;
647 }
648
649 self.attribute.$ident = Some(path.span());
659 }};
660 }
661 macro_rules! no_args_and_not_crate_level {
662 ($ident: ident) => {{
663 if let Err(span) = args.as_no_args() {
664 expected_no_args(cx, span);
665 return;
666 }
667 let span = path.span();
668 if !check_attr_not_crate_level(cx, span, sym::$ident) {
669 return;
670 }
671 self.attribute.$ident = Some(span);
672 }};
673 }
674 macro_rules! no_args_and_crate_level {
675 ($ident: ident) => {{
676 if let Err(span) = args.as_no_args() {
677 expected_no_args(cx, span);
678 return;
679 }
680 let span = path.span();
681 cx.check_target(
682 concat!("(", stringify!($ident), ")"),
683 &AllowedTargets::AllowListWarnRest(&[
684 Allow(Target::Crate),
685 AllowSilent(Target::Param), ]),
687 );
688 self.attribute.$ident = Some(span);
689 }};
690 }
691 macro_rules! string_arg_and_crate_level {
692 ($ident: ident) => {{
693 let Some(nv) = args.as_name_value() else {
694 expected_name_value(cx, args.span().unwrap_or(path.span()), path.word_sym());
695 return;
696 };
697
698 let Some(s) = nv.value_as_str() else {
699 expected_string_literal(cx, nv.value_span, Some(nv.value_as_lit()));
700 return;
701 };
702
703 cx.check_target(
704 s.as_str(),
705 &AllowedTargets::AllowListWarnRest(&[
706 Allow(Target::Crate),
707 AllowSilent(Target::Param), ]),
709 );
710
711 self.attribute.$ident = Some((s, path.span()));
721 }};
722 }
723 macro_rules! gated {
724 ($feature:ident $(,$notes:expr)*) => {
725 let stability = $crate::unstable!($feature $(, $notes)*);
726 cx.shared.cx.check_attribute_stability(&cx.attr_path, path.span(), stability);
727 };
728 }
729
730 match path.word_sym() {
731 Some(sym::alias) => self.parse_alias(cx, path, args),
732 Some(sym::hidden) => {
if let Err(span) = args.as_no_args() {
expected_no_args(cx, span);
return;
}
self.attribute.hidden = Some(path.span());
}no_args!(hidden),
733 Some(sym::html_favicon_url) => {
let Some(nv) =
args.as_name_value() else {
expected_name_value(cx, args.span().unwrap_or(path.span()),
path.word_sym());
return;
};
let Some(s) =
nv.value_as_str() else {
expected_string_literal(cx, nv.value_span,
Some(nv.value_as_lit()));
return;
};
cx.check_target(s.as_str(),
&AllowedTargets::AllowListWarnRest(&[Allow(Target::Crate),
AllowSilent(Target::Param)]));
self.attribute.html_favicon_url = Some((s, path.span()));
}string_arg_and_crate_level!(html_favicon_url),
734 Some(sym::html_logo_url) => {
let Some(nv) =
args.as_name_value() else {
expected_name_value(cx, args.span().unwrap_or(path.span()),
path.word_sym());
return;
};
let Some(s) =
nv.value_as_str() else {
expected_string_literal(cx, nv.value_span,
Some(nv.value_as_lit()));
return;
};
cx.check_target(s.as_str(),
&AllowedTargets::AllowListWarnRest(&[Allow(Target::Crate),
AllowSilent(Target::Param)]));
self.attribute.html_logo_url = Some((s, path.span()));
}string_arg_and_crate_level!(html_logo_url),
735 Some(sym::html_no_source) => {
if let Err(span) = args.as_no_args() {
expected_no_args(cx, span);
return;
}
let span = path.span();
cx.check_target("(html_no_source)",
&AllowedTargets::AllowListWarnRest(&[Allow(Target::Crate),
AllowSilent(Target::Param)]));
self.attribute.html_no_source = Some(span);
}no_args_and_crate_level!(html_no_source),
736 Some(sym::html_playground_url) => {
let Some(nv) =
args.as_name_value() else {
expected_name_value(cx, args.span().unwrap_or(path.span()),
path.word_sym());
return;
};
let Some(s) =
nv.value_as_str() else {
expected_string_literal(cx, nv.value_span,
Some(nv.value_as_lit()));
return;
};
cx.check_target(s.as_str(),
&AllowedTargets::AllowListWarnRest(&[Allow(Target::Crate),
AllowSilent(Target::Param)]));
self.attribute.html_playground_url = Some((s, path.span()));
}string_arg_and_crate_level!(html_playground_url),
737 Some(sym::html_root_url) => {
let Some(nv) =
args.as_name_value() else {
expected_name_value(cx, args.span().unwrap_or(path.span()),
path.word_sym());
return;
};
let Some(s) =
nv.value_as_str() else {
expected_string_literal(cx, nv.value_span,
Some(nv.value_as_lit()));
return;
};
cx.check_target(s.as_str(),
&AllowedTargets::AllowListWarnRest(&[Allow(Target::Crate),
AllowSilent(Target::Param)]));
self.attribute.html_root_url = Some((s, path.span()));
}string_arg_and_crate_level!(html_root_url),
738 Some(sym::issue_tracker_base_url) => {
739 {
let Some(nv) =
args.as_name_value() else {
expected_name_value(cx, args.span().unwrap_or(path.span()),
path.word_sym());
return;
};
let Some(s) =
nv.value_as_str() else {
expected_string_literal(cx, nv.value_span,
Some(nv.value_as_lit()));
return;
};
cx.check_target(s.as_str(),
&AllowedTargets::AllowListWarnRest(&[Allow(Target::Crate),
AllowSilent(Target::Param)]));
self.attribute.issue_tracker_base_url = Some((s, path.span()));
}string_arg_and_crate_level!(issue_tracker_base_url)
740 }
741 Some(sym::inline) => self.parse_inline(cx, path, args, DocInline::Inline),
742 Some(sym::no_inline) => self.parse_inline(cx, path, args, DocInline::NoInline),
743 Some(sym::masked) => {
744 let stability =
{
_ = rustc_feature::Features::doc_masked;
AttributeStability::Unstable {
gate_name: rustc_span::sym::doc_masked,
notes: &[],
}
};
cx.shared.cx.check_attribute_stability(&cx.attr_path, path.span(), stability);gated!(doc_masked);
745 {
if let Err(span) = args.as_no_args() {
expected_no_args(cx, span);
return;
}
self.attribute.masked = Some(path.span());
}no_args!(masked)
746 }
747 Some(sym::cfg) => {
748 let stability =
{
_ = rustc_feature::Features::doc_cfg;
AttributeStability::Unstable {
gate_name: rustc_span::sym::doc_cfg,
notes: &[],
}
};
cx.shared.cx.check_attribute_stability(&cx.attr_path, path.span(), stability);gated!(doc_cfg);
749 self.parse_cfg(cx, args)
750 }
751 Some(sym::notable_trait) => {
752 let stability =
{
_ = rustc_feature::Features::doc_notable_trait;
AttributeStability::Unstable {
gate_name: rustc_span::sym::doc_notable_trait,
notes: &[],
}
};
cx.shared.cx.check_attribute_stability(&cx.attr_path, path.span(), stability);gated!(doc_notable_trait);
753 parse_notable_trait(
754 cx,
755 path,
756 args,
757 &mut self.attribute.notable_trait,
758 sym::notable_trait,
759 )
760 }
761 Some(sym::keyword) => {
762 let stability =
{
_ = rustc_feature::Features::rustdoc_internals;
AttributeStability::Unstable {
gate_name: rustc_span::sym::rustdoc_internals,
notes: &[],
}
};
cx.shared.cx.check_attribute_stability(&cx.attr_path, path.span(), stability);gated!(rustdoc_internals);
763 parse_keyword_and_attribute(
764 cx,
765 path,
766 args,
767 &mut self.attribute.keyword,
768 sym::keyword,
769 )
770 }
771 Some(sym::attribute) => {
772 let stability =
{
_ = rustc_feature::Features::rustdoc_internals;
AttributeStability::Unstable {
gate_name: rustc_span::sym::rustdoc_internals,
notes: &[],
}
};
cx.shared.cx.check_attribute_stability(&cx.attr_path, path.span(), stability);gated!(rustdoc_internals);
773 parse_keyword_and_attribute(
774 cx,
775 path,
776 args,
777 &mut self.attribute.attribute,
778 sym::attribute,
779 )
780 }
781 Some(sym::fake_variadic) => {
782 let stability =
{
_ = rustc_feature::Features::rustdoc_internals;
AttributeStability::Unstable {
gate_name: rustc_span::sym::rustdoc_internals,
notes: &[],
}
};
cx.shared.cx.check_attribute_stability(&cx.attr_path, path.span(), stability);gated!(rustdoc_internals);
783 {
if let Err(span) = args.as_no_args() {
expected_no_args(cx, span);
return;
}
let span = path.span();
if !check_attr_not_crate_level(cx, span, sym::fake_variadic) { return; }
self.attribute.fake_variadic = Some(span);
}no_args_and_not_crate_level!(fake_variadic)
784 }
785 Some(sym::search_unbox) => {
786 let stability =
{
_ = rustc_feature::Features::rustdoc_internals;
AttributeStability::Unstable {
gate_name: rustc_span::sym::rustdoc_internals,
notes: &[],
}
};
cx.shared.cx.check_attribute_stability(&cx.attr_path, path.span(), stability);gated!(rustdoc_internals);
787 {
if let Err(span) = args.as_no_args() {
expected_no_args(cx, span);
return;
}
let span = path.span();
if !check_attr_not_crate_level(cx, span, sym::search_unbox) { return; }
self.attribute.search_unbox = Some(span);
}no_args_and_not_crate_level!(search_unbox)
788 }
789 Some(sym::rust_logo) => {
790 let stability =
{
_ = rustc_feature::Features::rustdoc_internals;
AttributeStability::Unstable {
gate_name: rustc_span::sym::rustdoc_internals,
notes: &["the `#[doc(rust_logo)]` attribute is used for Rust branding"],
}
};
cx.shared.cx.check_attribute_stability(&cx.attr_path, path.span(), stability);gated!(
791 rustdoc_internals,
792 "the `#[doc(rust_logo)]` attribute is used for Rust branding"
793 );
794
795 {
if let Err(span) = args.as_no_args() {
expected_no_args(cx, span);
return;
}
self.attribute.rust_logo = Some(path.span());
};no_args!(rust_logo);
796 cx.check_target("", &AllowedTargets::AllowList(&[Allow(Target::Crate)]));
797 }
798 Some(sym::auto_cfg) => {
799 let stability =
{
_ = rustc_feature::Features::doc_cfg;
AttributeStability::Unstable {
gate_name: rustc_span::sym::doc_cfg,
notes: &[],
}
};
cx.shared.cx.check_attribute_stability(&cx.attr_path, path.span(), stability);gated!(doc_cfg);
800 self.parse_auto_cfg(cx, path, args)
801 }
802 Some(sym::test) => {
803 let Some(list) = args.as_list() else {
804 cx.emit_lint(
805 INVALID_DOC_ATTRIBUTES,
806 DocTestTakesList,
807 args.span().unwrap_or(path.span()),
808 );
809 return;
810 };
811
812 for i in list.mixed() {
813 match i {
814 MetaItemOrLitParser::MetaItemParser(mip) => {
815 self.parse_single_test_doc_attr_item(cx, mip);
816 }
817 MetaItemOrLitParser::Lit(lit) => {
818 cx.emit_lint(INVALID_DOC_ATTRIBUTES, MalformedDoc, lit.span);
822 }
823 }
824 }
825 }
826 Some(sym::spotlight) => {
827 let span = path.span();
828 cx.emit_lint(INVALID_DOC_ATTRIBUTES, DocUnknownSpotlight { sugg_span: span }, span);
829 }
830 Some(sym::include) if let Some(nv) = args.as_name_value() => {
831 let inner = match cx.attr_style {
832 AttrStyle::Outer => "",
833 AttrStyle::Inner => "!",
834 };
835 let value = nv.value_as_lit().symbol;
836 let span = path.span();
837 cx.emit_lint(
838 INVALID_DOC_ATTRIBUTES,
839 DocUnknownInclude { inner, value, sugg: (span, Applicability::MaybeIncorrect) },
840 span,
841 );
842 }
843 Some(name @ (sym::passes | sym::no_default_passes)) => {
844 let span = path.span();
845 cx.emit_lint(
846 INVALID_DOC_ATTRIBUTES,
847 DocUnknownPasses { name, note_span: span },
848 span,
849 );
850 }
851 Some(sym::plugins) => {
852 let span = path.span();
853 cx.emit_lint(INVALID_DOC_ATTRIBUTES, DocUnknownPlugins { label_span: span }, span);
854 }
855 Some(name) => {
856 cx.emit_lint(INVALID_DOC_ATTRIBUTES, DocUnknownAny { name }, path.span());
857 }
858 None => {
859 let full_name =
860 path.segments().map(|s| s.as_str()).intersperse("::").collect::<String>();
861 let name = Symbol::intern(&full_name);
862 cx.emit_lint(INVALID_DOC_ATTRIBUTES, DocUnknownAny { name }, path.span());
863 }
864 }
865 }
866
867 fn accept_single_doc_attr(&mut self, cx: &mut AcceptContext<'_, '_>, args: &ArgParser) {
868 match args {
869 ArgParser::List(items) if !items.is_empty() => {
870 for i in items.mixed() {
871 match i {
872 MetaItemOrLitParser::MetaItemParser(mip) => {
873 if self.nb_doc_attrs == 0 {
874 self.attribute.first_span = cx.attr_span;
875 }
876 self.nb_doc_attrs += 1;
877 self.parse_single_doc_attr_item(cx, mip);
878 }
879 MetaItemOrLitParser::Lit(lit) => {
880 expected_name_value(cx, lit.span, None);
881 }
882 }
883 }
884 }
885 ArgParser::NameValue(nv) => {
886 if nv.value_as_str().is_none() {
887 expected_string_literal(cx, nv.value_span, Some(nv.value_as_lit()));
888 } else {
889 {
::core::panicking::panic_fmt(format_args!("internal error: entered unreachable code: {0}",
format_args!("Should have been handled at the same time as sugar-syntaxed doc comments")));
};unreachable!(
890 "Should have been handled at the same time as sugar-syntaxed doc comments"
891 );
892 }
893 }
894 _ => {
895 let suggestions = cx.adcx().suggestions();
896 let span = cx.inner_span;
897 cx.emit_lint(
898 INVALID_DOC_ATTRIBUTES,
899 IllFormedAttributeInput::new(&suggestions, None, None),
900 span,
901 );
902 }
903 }
904 }
905}
906
907impl AttributeParser for DocParser {
908 const ATTRIBUTES: AcceptMapping<Self> = &[(
909 &[sym::doc],
910 crate::AttributeTemplate {
word: false,
list: Some(&["alias", "hidden", "html_favicon_url", "html_logo_url",
"html_no_source", "html_playground_url", "html_root_url",
"issue_tracker_base_url", "inline", "no_inline", "masked",
"cfg", "notable_trait", "auto_cfg", "test"]),
one_of: &[],
name_value_str: Some(&["doc comment"]),
docs: None,
}template!(
911 List: &[
912 "alias",
913 "hidden",
914 "html_favicon_url",
915 "html_logo_url",
916 "html_no_source",
917 "html_playground_url",
918 "html_root_url",
919 "issue_tracker_base_url",
920 "inline",
921 "no_inline",
922 "masked",
923 "cfg",
924 "notable_trait",
925 "auto_cfg",
926 "test",
927 ],
928 NameValueStr: "doc comment"
929 ),
930 AttributeStability::Stable, |this, cx, args| {
932 this.accept_single_doc_attr(cx, args);
933 },
934 )];
935 const ALLOWED_TARGETS: AllowedTargets<'_> = DOC_TARGETS;
936
937 fn finalize(self, _cx: &FinalizeContext<'_, '_>) -> Option<AttributeKind> {
938 if self.nb_doc_attrs != 0 {
939 Some(AttributeKind::Doc(Box::new(self.attribute)))
940 } else {
941 None
942 }
943 }
944}