rustc_attr_parsing/attributes/

doc.rs

use rustc_ast::ast::{AttrStyle, LitKind, MetaItemLit};
use rustc_feature::template;
use rustc_hir::Target;
use rustc_hir::attrs::{
    AttributeKind, CfgEntry, CfgHideShow, CfgInfo, DocAttribute, DocInline, HideOrShow,
};
use rustc_hir::lints::AttributeLintKind;
use rustc_span::{Span, Symbol, edition, sym};
use thin_vec::ThinVec;

use super::prelude::{ALL_TARGETS, AllowedTargets};
use super::{AcceptMapping, AttributeParser};
use crate::context::{AcceptContext, FinalizeContext, Stage};
use crate::parser::{ArgParser, MetaItemOrLitParser, MetaItemParser, OwnedPathParser};
use crate::session_diagnostics::{
    DocAliasBadChar, DocAliasEmpty, DocAliasMalformed, DocAliasStartEnd, DocAttrNotCrateLevel,
    DocAttributeNotAttribute, DocKeywordNotKeyword,
};

fn check_keyword<S: Stage>(cx: &mut AcceptContext<'_, '_, S>, keyword: Symbol, span: Span) -> bool {
    // FIXME: Once rustdoc can handle URL conflicts on case insensitive file systems, we
    // can remove the `SelfTy` case here, remove `sym::SelfTy`, and update the
    // `#[doc(keyword = "SelfTy")` attribute in `library/std/src/keyword_docs.rs`.
    if keyword.is_reserved(|| edition::LATEST_STABLE_EDITION)
        || keyword.is_weak()
        || keyword == sym::SelfTy
    {
        return true;
    }
    cx.emit_err(DocKeywordNotKeyword { span, keyword });
    false
}

fn check_attribute<S: Stage>(
    cx: &mut AcceptContext<'_, '_, S>,
    attribute: Symbol,
    span: Span,
) -> bool {
    // FIXME: This should support attributes with namespace like `diagnostic::do_not_recommend`.
    if rustc_feature::BUILTIN_ATTRIBUTE_MAP.contains_key(&attribute) {
        return true;
    }
    cx.emit_err(DocAttributeNotAttribute { span, attribute });
    false
}

/// Checks that an attribute is *not* used at the crate level. Returns `true` if valid.
fn check_attr_not_crate_level<S: Stage>(
    cx: &mut AcceptContext<'_, '_, S>,
    span: Span,
    attr_name: Symbol,
) -> bool {
    if cx.shared.target == Target::Crate {
        cx.emit_err(DocAttrNotCrateLevel { span, attr_name });
        return false;
    }
    true
}

/// Checks that an attribute is used at the crate level. Returns `true` if valid.
fn check_attr_crate_level<S: Stage>(cx: &mut AcceptContext<'_, '_, S>, span: Span) -> bool {
    if cx.shared.target != Target::Crate {
        cx.emit_lint(
            rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
            AttributeLintKind::AttrCrateLevelOnly,
            span,
        );
        return false;
    }
    true
}

fn parse_keyword_and_attribute<S: Stage>(
    cx: &mut AcceptContext<'_, '_, S>,
    path: &OwnedPathParser,
    args: &ArgParser,
    attr_value: &mut Option<(Symbol, Span)>,
    attr_name: Symbol,
) {
    let Some(nv) = args.name_value() else {
        cx.expected_name_value(args.span().unwrap_or(path.span()), path.word_sym());
        return;
    };

    let Some(value) = nv.value_as_str() else {
        cx.expected_string_literal(nv.value_span, Some(nv.value_as_lit()));
        return;
    };

    let ret = if attr_name == sym::keyword {
        check_keyword(cx, value, nv.value_span)
    } else {
        check_attribute(cx, value, nv.value_span)
    };
    if !ret {
        return;
    }

    let span = path.span();
    if attr_value.is_some() {
        cx.duplicate_key(span, path.word_sym().unwrap());
        return;
    }

    if !check_attr_not_crate_level(cx, span, attr_name) {
        return;
    }

    *attr_value = Some((value, span));
}

#[derive(Default, Debug)]
pub(crate) struct DocParser {
    attribute: DocAttribute,
    nb_doc_attrs: usize,
}

impl DocParser {
    fn parse_single_test_doc_attr_item<S: Stage>(
        &mut self,
        cx: &mut AcceptContext<'_, '_, S>,
        mip: &MetaItemParser,
    ) {
        let path = mip.path();
        let args = mip.args();

        match path.word_sym() {
            Some(sym::no_crate_inject) => {
                if let Err(span) = args.no_args() {
                    cx.expected_no_args(span);
                    return;
                }

                if self.attribute.no_crate_inject.is_some() {
                    cx.duplicate_key(path.span(), sym::no_crate_inject);
                    return;
                }

                if !check_attr_crate_level(cx, path.span()) {
                    return;
                }

                self.attribute.no_crate_inject = Some(path.span())
            }
            Some(sym::attr) => {
                let Some(list) = args.list() else {
                    cx.expected_list(cx.attr_span, args);
                    return;
                };

                // FIXME: convert list into a Vec of `AttributeKind` because current code is awful.
                for attr in list.mixed() {
                    self.attribute.test_attrs.push(attr.span());
                }
            }
            Some(name) => {
                cx.emit_lint(
                    rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
                    AttributeLintKind::DocTestUnknown { name },
                    path.span(),
                );
            }
            None => {
                cx.emit_lint(
                    rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
                    AttributeLintKind::DocTestLiteral,
                    path.span(),
                );
            }
        }
    }

    fn add_alias<S: Stage>(
        &mut self,
        cx: &mut AcceptContext<'_, '_, S>,
        alias: Symbol,
        span: Span,
    ) {
        let attr_str = "`#[doc(alias = \"...\")]`";
        if alias == sym::empty {
            cx.emit_err(DocAliasEmpty { span, attr_str });
            return;
        }

        let alias_str = alias.as_str();
        if let Some(c) =
            alias_str.chars().find(|&c| c == '"' || c == '\'' || (c.is_whitespace() && c != ' '))
        {
            cx.emit_err(DocAliasBadChar { span, attr_str, char_: c });
            return;
        }
        if alias_str.starts_with(' ') || alias_str.ends_with(' ') {
            cx.emit_err(DocAliasStartEnd { span, attr_str });
            return;
        }
        if !check_attr_not_crate_level(cx, span, sym::alias) {
            return;
        }

        if let Some(first_definition) = self.attribute.aliases.get(&alias).copied() {
            cx.emit_lint(
                rustc_session::lint::builtin::UNUSED_ATTRIBUTES,
                AttributeLintKind::DuplicateDocAlias { first_definition },
                span,
            );
        }

        self.attribute.aliases.insert(alias, span);
    }

    fn parse_alias<S: Stage>(
        &mut self,
        cx: &mut AcceptContext<'_, '_, S>,
        path: &OwnedPathParser,
        args: &ArgParser,
    ) {
        match args {
            ArgParser::NoArgs => {
                cx.emit_err(DocAliasMalformed { span: args.span().unwrap_or(path.span()) });
            }
            ArgParser::List(list) => {
                for i in list.mixed() {
                    let Some(alias) = i.lit().and_then(|i| i.value_str()) else {
                        cx.expected_string_literal(i.span(), i.lit());
                        continue;
                    };

                    self.add_alias(cx, alias, i.span());
                }
            }
            ArgParser::NameValue(nv) => {
                let Some(alias) = nv.value_as_str() else {
                    cx.expected_string_literal(nv.value_span, Some(nv.value_as_lit()));
                    return;
                };
                self.add_alias(cx, alias, nv.value_span);
            }
        }
    }

    fn parse_inline<S: Stage>(
        &mut self,
        cx: &mut AcceptContext<'_, '_, S>,
        path: &OwnedPathParser,
        args: &ArgParser,
        inline: DocInline,
    ) {
        if let Err(span) = args.no_args() {
            cx.expected_no_args(span);
            return;
        }

        self.attribute.inline.push((inline, path.span()));
    }

    fn parse_cfg<S: Stage>(&mut self, cx: &mut AcceptContext<'_, '_, S>, args: &ArgParser) {
        // This function replaces cases like `cfg(all())` with `true`.
        fn simplify_cfg(cfg_entry: &mut CfgEntry) {
            match cfg_entry {
                CfgEntry::All(cfgs, span) if cfgs.is_empty() => {
                    *cfg_entry = CfgEntry::Bool(true, *span)
                }
                CfgEntry::Any(cfgs, span) if cfgs.is_empty() => {
                    *cfg_entry = CfgEntry::Bool(false, *span)
                }
                CfgEntry::Not(cfg, _) => simplify_cfg(cfg),
                _ => {}
            }
        }
        if let Some(mut cfg_entry) = super::cfg::parse_cfg(cx, args) {
            simplify_cfg(&mut cfg_entry);
            self.attribute.cfg.push(cfg_entry);
        }
    }

    fn parse_auto_cfg<S: Stage>(
        &mut self,
        cx: &mut AcceptContext<'_, '_, S>,
        path: &OwnedPathParser,
        args: &ArgParser,
    ) {
        match args {
            ArgParser::NoArgs => {
                self.attribute.auto_cfg_change.push((true, path.span()));
            }
            ArgParser::List(list) => {
                for meta in list.mixed() {
                    let MetaItemOrLitParser::MetaItemParser(item) = meta else {
                        cx.emit_lint(
                            rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
                            AttributeLintKind::DocAutoCfgExpectsHideOrShow,
                            meta.span(),
                        );
                        continue;
                    };
                    let (kind, attr_name) = match item.path().word_sym() {
                        Some(sym::hide) => (HideOrShow::Hide, sym::hide),
                        Some(sym::show) => (HideOrShow::Show, sym::show),
                        _ => {
                            cx.emit_lint(
                                rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
                                AttributeLintKind::DocAutoCfgExpectsHideOrShow,
                                item.span(),
                            );
                            continue;
                        }
                    };
                    let ArgParser::List(list) = item.args() else {
                        cx.emit_lint(
                            rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
                            AttributeLintKind::DocAutoCfgHideShowExpectsList { attr_name },
                            item.span(),
                        );
                        continue;
                    };

                    let mut cfg_hide_show = CfgHideShow { kind, values: ThinVec::new() };

                    for item in list.mixed() {
                        let MetaItemOrLitParser::MetaItemParser(sub_item) = item else {
                            cx.emit_lint(
                                rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
                                AttributeLintKind::DocAutoCfgHideShowUnexpectedItem { attr_name },
                                item.span(),
                            );
                            continue;
                        };
                        match sub_item.args() {
                            a @ (ArgParser::NoArgs | ArgParser::NameValue(_)) => {
                                let Some(name) = sub_item.path().word_sym() else {
                                    cx.expected_identifier(sub_item.path().span());
                                    continue;
                                };
                                if let Ok(CfgEntry::NameValue { name, value, .. }) =
                                    super::cfg::parse_name_value(
                                        name,
                                        sub_item.path().span(),
                                        a.name_value(),
                                        sub_item.span(),
                                        cx,
                                    )
                                {
                                    cfg_hide_show.values.push(CfgInfo {
                                        name,
                                        name_span: sub_item.path().span(),
                                        // If `value` is `Some`, `a.name_value()` will always return
                                        // `Some` as well.
                                        value: value
                                            .map(|v| (v, a.name_value().unwrap().value_span)),
                                    })
                                }
                            }
                            _ => {
                                cx.emit_lint(
                                    rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
                                    AttributeLintKind::DocAutoCfgHideShowUnexpectedItem {
                                        attr_name,
                                    },
                                    sub_item.span(),
                                );
                                continue;
                            }
                        }
                    }
                    self.attribute.auto_cfg.push((cfg_hide_show, path.span()));
                }
            }
            ArgParser::NameValue(nv) => {
                let MetaItemLit { kind: LitKind::Bool(bool_value), span, .. } = nv.value_as_lit()
                else {
                    cx.emit_lint(
                        rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
                        AttributeLintKind::DocAutoCfgWrongLiteral,
                        nv.value_span,
                    );
                    return;
                };
                self.attribute.auto_cfg_change.push((*bool_value, *span));
            }
        }
    }

    fn parse_single_doc_attr_item<S: Stage>(
        &mut self,
        cx: &mut AcceptContext<'_, '_, S>,
        mip: &MetaItemParser,
    ) {
        let path = mip.path();
        let args = mip.args();

        macro_rules! no_args {
            ($ident: ident) => {{
                if let Err(span) = args.no_args() {
                    cx.expected_no_args(span);
                    return;
                }

                // FIXME: It's errorring when the attribute is passed multiple times on the command
                // line.
                // The right fix for this would be to only check this rule if the attribute is
                // not set on the command line but directly in the code.
                // if self.attribute.$ident.is_some() {
                //     cx.duplicate_key(path.span(), path.word_sym().unwrap());
                //     return;
                // }

                self.attribute.$ident = Some(path.span());
            }};
        }
        macro_rules! no_args_and_not_crate_level {
            ($ident: ident) => {{
                if let Err(span) = args.no_args() {
                    cx.expected_no_args(span);
                    return;
                }
                let span = path.span();
                if !check_attr_not_crate_level(cx, span, sym::$ident) {
                    return;
                }
                self.attribute.$ident = Some(span);
            }};
        }
        macro_rules! no_args_and_crate_level {
            ($ident: ident) => {{
                if let Err(span) = args.no_args() {
                    cx.expected_no_args(span);
                    return;
                }
                let span = path.span();
                if !check_attr_crate_level(cx, span) {
                    return;
                }
                self.attribute.$ident = Some(span);
            }};
        }
        macro_rules! string_arg_and_crate_level {
            ($ident: ident) => {{
                let Some(nv) = args.name_value() else {
                    cx.expected_name_value(args.span().unwrap_or(path.span()), path.word_sym());
                    return;
                };

                let Some(s) = nv.value_as_str() else {
                    cx.expected_string_literal(nv.value_span, Some(nv.value_as_lit()));
                    return;
                };

                if !check_attr_crate_level(cx, path.span()) {
                    return;
                }

                // FIXME: It's errorring when the attribute is passed multiple times on the command
                // line.
                // The right fix for this would be to only check this rule if the attribute is
                // not set on the command line but directly in the code.
                // if self.attribute.$ident.is_some() {
                //     cx.duplicate_key(path.span(), path.word_sym().unwrap());
                //     return;
                // }

                self.attribute.$ident = Some((s, path.span()));
            }};
        }

        match path.word_sym() {
            Some(sym::alias) => self.parse_alias(cx, path, args),
            Some(sym::hidden) => no_args!(hidden),
            Some(sym::html_favicon_url) => string_arg_and_crate_level!(html_favicon_url),
            Some(sym::html_logo_url) => string_arg_and_crate_level!(html_logo_url),
            Some(sym::html_no_source) => no_args_and_crate_level!(html_no_source),
            Some(sym::html_playground_url) => string_arg_and_crate_level!(html_playground_url),
            Some(sym::html_root_url) => string_arg_and_crate_level!(html_root_url),
            Some(sym::issue_tracker_base_url) => {
                string_arg_and_crate_level!(issue_tracker_base_url)
            }
            Some(sym::inline) => self.parse_inline(cx, path, args, DocInline::Inline),
            Some(sym::no_inline) => self.parse_inline(cx, path, args, DocInline::NoInline),
            Some(sym::masked) => no_args!(masked),
            Some(sym::cfg) => self.parse_cfg(cx, args),
            Some(sym::notable_trait) => no_args!(notable_trait),
            Some(sym::keyword) => parse_keyword_and_attribute(
                cx,
                path,
                args,
                &mut self.attribute.keyword,
                sym::keyword,
            ),
            Some(sym::attribute) => parse_keyword_and_attribute(
                cx,
                path,
                args,
                &mut self.attribute.attribute,
                sym::attribute,
            ),
            Some(sym::fake_variadic) => no_args_and_not_crate_level!(fake_variadic),
            Some(sym::search_unbox) => no_args_and_not_crate_level!(search_unbox),
            Some(sym::rust_logo) => no_args_and_crate_level!(rust_logo),
            Some(sym::auto_cfg) => self.parse_auto_cfg(cx, path, args),
            Some(sym::test) => {
                let Some(list) = args.list() else {
                    cx.emit_lint(
                        rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
                        AttributeLintKind::DocTestTakesList,
                        args.span().unwrap_or(path.span()),
                    );
                    return;
                };

                for i in list.mixed() {
                    match i {
                        MetaItemOrLitParser::MetaItemParser(mip) => {
                            self.parse_single_test_doc_attr_item(cx, mip);
                        }
                        MetaItemOrLitParser::Lit(lit) => {
                            cx.unexpected_literal(lit.span);
                        }
                    }
                }
            }
            Some(sym::spotlight) => {
                cx.emit_lint(
                    rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
                    AttributeLintKind::DocUnknownSpotlight { span: path.span() },
                    path.span(),
                );
            }
            Some(sym::include) if let Some(nv) = args.name_value() => {
                let inner = match cx.attr_style {
                    AttrStyle::Outer => "",
                    AttrStyle::Inner => "!",
                };
                cx.emit_lint(
                    rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
                    AttributeLintKind::DocUnknownInclude {
                        inner,
                        value: nv.value_as_lit().symbol,
                        span: path.span(),
                    },
                    path.span(),
                );
            }
            Some(name @ (sym::passes | sym::no_default_passes)) => {
                cx.emit_lint(
                    rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
                    AttributeLintKind::DocUnknownPasses { name, span: path.span() },
                    path.span(),
                );
            }
            Some(sym::plugins) => {
                cx.emit_lint(
                    rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
                    AttributeLintKind::DocUnknownPlugins { span: path.span() },
                    path.span(),
                );
            }
            Some(name) => {
                cx.emit_lint(
                    rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
                    AttributeLintKind::DocUnknownAny { name },
                    path.span(),
                );
            }
            None => {
                let full_name =
                    path.segments().map(|s| s.as_str()).intersperse("::").collect::<String>();
                cx.emit_lint(
                    rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
                    AttributeLintKind::DocUnknownAny { name: Symbol::intern(&full_name) },
                    path.span(),
                );
            }
        }
    }

    fn accept_single_doc_attr<S: Stage>(
        &mut self,
        cx: &mut AcceptContext<'_, '_, S>,
        args: &ArgParser,
    ) {
        match args {
            ArgParser::NoArgs => {
                let suggestions = cx.suggestions();
                let span = cx.attr_span;
                cx.emit_lint(
                    rustc_session::lint::builtin::ILL_FORMED_ATTRIBUTE_INPUT,
                    AttributeLintKind::IllFormedAttributeInput { suggestions, docs: None },
                    span,
                );
            }
            ArgParser::List(items) => {
                for i in items.mixed() {
                    match i {
                        MetaItemOrLitParser::MetaItemParser(mip) => {
                            self.nb_doc_attrs += 1;
                            self.parse_single_doc_attr_item(cx, mip);
                        }
                        MetaItemOrLitParser::Lit(lit) => {
                            cx.expected_name_value(lit.span, None);
                        }
                    }
                }
            }
            ArgParser::NameValue(nv) => {
                if nv.value_as_str().is_none() {
                    cx.expected_string_literal(nv.value_span, Some(nv.value_as_lit()));
                } else {
                    unreachable!(
                        "Should have been handled at the same time as sugar-syntaxed doc comments"
                    );
                }
            }
        }
    }
}

impl<S: Stage> AttributeParser<S> for DocParser {
    const ATTRIBUTES: AcceptMapping<Self, S> = &[(
        &[sym::doc],
        template!(
            List: &[
                "alias",
                "attribute",
                "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",
                "keyword",
                "fake_variadic",
                "search_unbox",
                "rust_logo",
                "auto_cfg",
                "test",
                "spotlight",
                "include",
                "no_default_passes",
                "passes",
                "plugins",
            ],
            NameValueStr: "string"
        ),
        |this, cx, args| {
            this.accept_single_doc_attr(cx, args);
        },
    )];
    // FIXME: Currently emitted from 2 different places, generating duplicated warnings.
    const ALLOWED_TARGETS: AllowedTargets = AllowedTargets::AllowList(ALL_TARGETS);
    // const ALLOWED_TARGETS: AllowedTargets = AllowedTargets::AllowListWarnRest(&[
    //     Allow(Target::ExternCrate),
    //     Allow(Target::Use),
    //     Allow(Target::Static),
    //     Allow(Target::Const),
    //     Allow(Target::Fn),
    //     Allow(Target::Mod),
    //     Allow(Target::ForeignMod),
    //     Allow(Target::TyAlias),
    //     Allow(Target::Enum),
    //     Allow(Target::Variant),
    //     Allow(Target::Struct),
    //     Allow(Target::Field),
    //     Allow(Target::Union),
    //     Allow(Target::Trait),
    //     Allow(Target::TraitAlias),
    //     Allow(Target::Impl { of_trait: true }),
    //     Allow(Target::Impl { of_trait: false }),
    //     Allow(Target::AssocConst),
    //     Allow(Target::Method(MethodKind::Inherent)),
    //     Allow(Target::Method(MethodKind::Trait { body: true })),
    //     Allow(Target::Method(MethodKind::Trait { body: false })),
    //     Allow(Target::Method(MethodKind::TraitImpl)),
    //     Allow(Target::AssocTy),
    //     Allow(Target::ForeignFn),
    //     Allow(Target::ForeignStatic),
    //     Allow(Target::ForeignTy),
    //     Allow(Target::MacroDef),
    //     Allow(Target::Crate),
    //     Error(Target::WherePredicate),
    // ]);

    fn finalize(self, _cx: &FinalizeContext<'_, '_, S>) -> Option<AttributeKind> {
        if self.nb_doc_attrs != 0 {
            Some(AttributeKind::Doc(Box::new(self.attribute)))
        } else {
            None
        }
    }
}