Skip to main content

rustc_attr_parsing/attributes/
doc.rs

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    // FIXME: Once rustdoc can handle URL conflicts on case insensitive file systems, we
36    // can remove the `SelfTy` case here, remove `sym::SelfTy`, and update the
37    // `#[doc(keyword = "SelfTy")` attribute in `library/std/src/keyword_docs.rs`.
38    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    // FIXME: This should support attributes with namespace like `diagnostic::do_not_recommend`.
50    if rustc_feature::BUILTIN_ATTRIBUTE_SET.contains(&attribute) {
51        return true;
52    }
53    cx.emit_err(DocAttributeNotAttribute { span, attribute });
54    false
55}
56
57/// Checks that an attribute is *not* used at the crate level. Returns `true` if valid.
58fn 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
70// FIXME: To be removed once merged and replace with `cx.expected_name_value(span, _name)`.
71fn expected_name_value(cx: &mut AcceptContext<'_, '_>, span: Span, _name: Option<Symbol>) {
72    cx.emit_lint(INVALID_DOC_ATTRIBUTES, ExpectedNameValue, span);
73}
74
75// FIXME: remove this method once merged and use `cx.expected_no_args(span)` instead.
76fn expected_no_args(cx: &mut AcceptContext<'_, '_>, span: Span) {
77    cx.emit_lint(INVALID_DOC_ATTRIBUTES, ExpectedNoArgs, span);
78}
79
80// FIXME: remove this method once merged and use `cx.expected_no_args(span)` instead.
81// cx.expected_string_literal(span, _actual_literal);
82fn 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            // FIXME(164728): every invalid notable trait attribute lint produces exactly
148            // the same warning and we should switch to more specific diagnostics
149            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                    // FIXME(164728): remove this method once merged and uncomment the line
301                    // below instead. cx.expected_list(cx.attr_span, args);
302                    let span = cx.attr_span;
303                    cx.emit_lint(INVALID_DOC_ATTRIBUTES, MalformedDoc, span);
304                    return;
305                };
306                // FIXME(164728): remove this method once merged and uncomment the line
307                // below instead. cx.expected_list(cx.attr_span, args);
308                for attr in list.mixed() {
309                    // Arguments of `attr` are checked via the span, so can be safely ignored
310                    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 => {} // Param has a custom error
406            _ => {
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        // This function replaces cases like `cfg(all())` with `true`.
419        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    // Parses the `doc(auto_cfg(hide/show(..., values())))` attribute.
438    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                // If it's a string literal, all good.
450                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                // If it's any other kind of literal, then it's wrong and we emit a lint.
469                MetaItemOrLitParser::Lit(lit) => cx.emit_lint(
470                    INVALID_DOC_ATTRIBUTES,
471                    DocAutoCfgHideShowUnexpectedItem { attr_name: lit.symbol },
472                    lit.span,
473                ),
474                // If it's a list, then only `any()` and `none()` are allowed and they must not
475                // contain any item.
476                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                    // Only `hide` and `show` are allowed in `auto_cfg` if it's a list, and both
534                    // must be a list.
535                    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                            // The only accepted list is `values()`.
578                            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                            // No `name = value` is allowed.
594                            ArgParser::NameValue(_) => {
595                                cx.emit_lint(
596                                    INVALID_DOC_ATTRIBUTES,
597                                    DocAutoCfgHideShowUnexpectedItem { attr_name },
598                                    sub_item.span(),
599                                );
600                            }
601                            // If `values()` was already used, no item should come after it.
602                            _ => {
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                // FIXME: It's errorring when the attribute is passed multiple times on the command
650                // line.
651                // The right fix for this would be to only check this rule if the attribute is
652                // not set on the command line but directly in the code.
653                // if self.attribute.$ident.is_some() {
654                //     cx.duplicate_key(path.span(), path.word_sym().unwrap());
655                //     return;
656                // }
657
658                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), // Param has a custom error
686                    ]),
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), // Param has a custom error
708                    ]),
709                );
710
711                // FIXME: It's errorring when the attribute is passed multiple times on the command
712                // line.
713                // The right fix for this would be to only check this rule if the attribute is
714                // not set on the command line but directly in the code.
715                // if self.attribute.$ident.is_some() {
716                //     cx.duplicate_key(path.span(), path.word_sym().unwrap());
717                //     return;
718                // }
719
720                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                            // FIXME: remove this method once merged and uncomment the line
819                            // below instead.
820                            // cx.unexpected_literal(lit.span);
821                            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, // Some parts of the attribute are unstable, manually checked in parser
931        |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}