Skip to content

rework handling of doc attributes on macro calls #161514

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mejrs wants to merge 1 commit into
base: main
Choose a base branch
from
Open

rework handling of doc attributes on macro calls #161514

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion Cargo.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4013,7 +4013,6 @@ name = "rustc_expand"
version = "0.0.0"
dependencies = [
"rustc_ast",
"rustc_ast_passes",
"rustc_ast_pretty",
"rustc_attr_ir",
"rustc_attr_parsing",
Expand Down
3 changes: 1 addition & 2 deletions compiler/rustc_ast_lowering/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ use rustc_ast::mut_visit::{self, MutVisitor};
use rustc_ast::node_id::NodeMap;
use rustc_ast::visit::{self, Visitor};
use rustc_ast::{self as ast, *};
use rustc_attr_parsing::{AttributeParser, OmitDoc, Recovery, ShouldEmit};
use rustc_attr_parsing::{AttributeParser, Recovery, ShouldEmit};
use rustc_data_structures::fx::FxIndexMap;
use rustc_data_structures::sorted_map::SortedMap;
use rustc_data_structures::stable_hash::{StableHash, StableHasher};
Expand Down Expand Up @@ -1231,7 +1231,6 @@ impl<'hir> LoweringContext<'_, 'hir> {
attrs,
target_span,
target,
OmitDoc::Lower,
|s| l.lower(s),
|lint_id, span, kind| {
self.delayed_lints.push(DelayedLint {
Expand Down
34 changes: 3 additions & 31 deletions compiler/rustc_ast_passes/src/feature_gate.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,10 +46,6 @@ macro_rules! gate_multi {
}};
}

pub fn check_attribute(attr: &ast::Attribute, sess: &Session, features: &Features) {
PostExpansionVisitor { sess, features }.visit_attribute(attr)
}

struct PostExpansionVisitor<'a> {
sess: &'a Session,

Expand Down Expand Up @@ -152,33 +148,9 @@ impl<'a> PostExpansionVisitor<'a> {
}

impl<'a> Visitor<'a> for PostExpansionVisitor<'a> {
fn visit_attribute(&mut self, attr: &ast::Attribute) {
// Check unstable flavors of the `#[doc]` attribute.
if attr.has_name(sym::doc) {
for meta_item_inner in attr.meta_item_list().unwrap_or_default() {
macro_rules! gate_doc { ($($s:literal { $($name:ident => $feature:ident)* })*) => {
$($(if meta_item_inner.has_name(sym::$name) {
let msg = concat!("`#[doc(", stringify!($name), ")]` is ", $s);
gate!(self, $feature, attr.span, msg);
})*)*
}}

gate_doc!(
"experimental" {
cfg => doc_cfg
auto_cfg => doc_cfg
masked => doc_masked
notable_trait => doc_notable_trait
}
"meant for internal use only" {
attribute => rustdoc_internals
keyword => rustdoc_internals
fake_variadic => rustdoc_internals
search_unbox => rustdoc_internals
}
);
}
}
fn visit_attribute(&mut self, attr: &'a ast::Attribute) {
// Checked in attribute parsers, do NOT add checks here
visit::walk_attribute(self, attr)
}

fn visit_item(&mut self, i: &'a ast::Item) {
Expand Down
102 changes: 63 additions & 39 deletions compiler/rustc_attr_parsing/src/attributes/doc.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,9 @@ use rustc_attr_ir::{
DocInline, HideOrShow,
};
use rustc_data_structures::fx::{FxHashSet, FxIndexMap, IndexEntry};
use rustc_errors::{Applicability, msg};
use rustc_errors::Applicability;
use rustc_feature::AttributeStability;
use rustc_lint_defs::builtin::{INVALID_DOC_ATTRIBUTES, UNUSED_ATTRIBUTES};
use rustc_session::diagnostics::feature_err;
use rustc_span::{Span, Symbol, edition, sym};

use super::prelude::{ALL_TARGETS, AllowedTargets};
Expand Down Expand Up @@ -526,19 +525,15 @@ impl DocParser {
}
macro_rules! no_args_and_crate_level {
($ident: ident) => {{
no_args_and_crate_level!($ident, |span| {});
}};
($ident: ident, |$span:ident| $extra_validation:block) => {{
if let Err(span) = args.as_no_args() {
expected_no_args(cx, span);
return;
}
let $span = path.span();
if !check_attr_crate_level(cx, $span) {
let span = path.span();
if !check_attr_crate_level(cx, span) {
return;
}
$extra_validation
self.attribute.$ident = Some($span);
self.attribute.$ident = Some(span);
}};
}
macro_rules! string_arg_and_crate_level {
Expand Down Expand Up @@ -569,6 +564,12 @@ impl DocParser {
self.attribute.$ident = Some((s, path.span()));
}};
}
macro_rules! gated {
($feature:ident $(,$notes:expr)*) => {
let stability = $crate::unstable!($feature $(, $notes)*);
cx.shared.cx.check_attribute_stability(&cx.attr_path, path.span(), stability);
};
}

match path.word_sym() {
Some(sym::alias) => self.parse_alias(cx, path, args),
Expand All @@ -583,37 +584,60 @@ impl DocParser {
}
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, |span| {
if !cx.features().rustdoc_internals() {
feature_err(
cx.sess(),
sym::rustdoc_internals,
span,
msg!("the `#[doc(rust_logo)]` attribute is used for Rust branding"),
)
.emit();
Some(sym::masked) => {
gated!(doc_masked);
no_args!(masked)
}
Some(sym::cfg) => {
gated!(doc_cfg);
self.parse_cfg(cx, args)
}
Some(sym::notable_trait) => {
gated!(doc_notable_trait);
no_args!(notable_trait)
}
Some(sym::keyword) => {
gated!(rustdoc_internals);
parse_keyword_and_attribute(
cx,
path,
args,
&mut self.attribute.keyword,
sym::keyword,
)
}
Some(sym::attribute) => {
gated!(rustdoc_internals);
parse_keyword_and_attribute(
cx,
path,
args,
&mut self.attribute.attribute,
sym::attribute,
)
}
Some(sym::fake_variadic) => {
gated!(rustdoc_internals);
no_args_and_not_crate_level!(fake_variadic)
}
Some(sym::search_unbox) => {
gated!(rustdoc_internals);
no_args_and_not_crate_level!(search_unbox)
}
Some(sym::rust_logo) => {
// FIXME: Only feature gated at the crate level (!!)
if cx.target == Target::Crate {
gated!(
rustdoc_internals,
"the `#[doc(rust_logo)]` attribute is used for Rust branding"
);
}
}),
Some(sym::auto_cfg) => self.parse_auto_cfg(cx, path, args),
no_args_and_crate_level!(rust_logo)
}
Some(sym::auto_cfg) => {
gated!(doc_cfg);
self.parse_auto_cfg(cx, path, args)
}
Some(sym::test) => {
let Some(list) = args.as_list() else {
cx.emit_lint(
Expand Down
6 changes: 0 additions & 6 deletions compiler/rustc_attr_parsing/src/context.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -866,12 +866,6 @@ impl<'p, 'sess: 'p> DerefMut for SharedContext<'p, 'sess> {
}
}

#[derive(PartialEq, Clone, Copy, Debug)]
pub enum OmitDoc {
Lower,
Skip,
}

#[derive(Copy, Clone, Debug)]
pub enum ShouldEmit {
/// The operations will emit errors, and lints, and errors are fatal.
Expand Down
34 changes: 17 additions & 17 deletions compiler/rustc_attr_parsing/src/interface.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ use crate::context::{
use crate::diagnostics::ParsedDescription;
use crate::parser::{AllowExprMetavar, ArgParser, PathParser, RefPathParser};
use crate::synthetic::SyntheticAttrState;
use crate::{AttributeTemplate, OmitDoc, ShouldEmit};
use crate::{AttributeTemplate, ShouldEmit};

pub struct EmitAttribute(
pub Box<
Expand Down Expand Up @@ -161,7 +161,6 @@ impl<'sess> AttributeParser<'sess> {
attrs,
target_span,
target,
OmitDoc::Skip,
std::convert::identity,
|lint_id, span, kind| {
sess.psess.dyn_buffer_lint_sess(lint_id.lint, span, target_node_id, kind.0)
Expand Down Expand Up @@ -310,14 +309,12 @@ impl<'sess> AttributeParser<'sess> {

/// Parse a list of attributes.
///
/// `target_span` is the span of the thing this list of attributes is applied to,
/// and when `omit_doc` is set, doc attributes are filtered out.
/// `target_span` is the span of the thing this list of attributes is applied to.
pub fn parse_attribute_list(
&mut self,
attrs: &[ast::Attribute],
target_span: Span,
target: Target,
omit_doc: OmitDoc,
lower_span: impl Copy + Fn(Span) -> Span,
mut emit_lint: impl FnMut(LintId, MultiSpan, EmitAttribute),
) -> Vec<Attribute> {
Expand All @@ -335,23 +332,26 @@ impl<'sess> AttributeParser<'sess> {
}
}

// Sometimes, for example for `#![doc = include_str!("readme.md")]`,
// doc still contains a non-literal. You might say, when we're lowering attributes
// that's expanded right? But no, sometimes, when parsing attributes on macros,
// we already use the lowering logic and these are still there. So, when `omit_doc`
// is set we *also* want to ignore these.
let is_doc_attribute = attr.has_name(sym::doc);
if omit_doc == OmitDoc::Skip && is_doc_attribute {
fn is_doc_non_lit_expr(attr: &ast::Attribute) -> bool {
if !attr.has_name(sym::doc) {
return false;
}
let ast::AttrKind::Normal(n) = &attr.kind else { return false };
let ast::AttrArgs::Eq { expr, .. } = &n.item.args else { return false };
if matches!(expr.kind, ast::ExprKind::Lit(_)) {
return false;
};
true
}

// FIXME accidentally allowed on Stable Rust
if target == Target::MacroCall && is_doc_non_lit_expr(attr) {

@JonathanBrouwer JonathanBrouwer Aug 22, 2026 •
edited by rustbot
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is an independent change from the feature gate changes, I'd prefer this to be in an independent commit if it's not too much of a hassle

View changes since the review

@mejrs mejrs Aug 22, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd prefer if my commits can stand on their own, so I'd rather not do this.

Moving the feature parsing also requires changes to how OmitDoc is used, in order to correctly feature gate

    #[doc(fake_variadic)]
    //~^ ERROR this subset of the `doc` attribute is meant for internal use only [E0658]
    println!();

I think it would be simpler to just do it all in one commit.

continue;
}

let attr_span = lower_span(attr.span);
match &attr.kind {
ast::AttrKind::DocComment(comment_kind, symbol) => {
if omit_doc == OmitDoc::Skip {
continue;
}

attributes.push(Attribute::Parsed(AttributeKind::DocComment {
style: attr.style,
kind: DocFragmentKind::Sugared(*comment_kind),
Expand Down Expand Up @@ -407,7 +407,7 @@ impl<'sess> AttributeParser<'sess> {
// bla
// blob
// a
if is_doc_attribute
if attr.has_name(sym::doc)
&& let ArgParser::NameValue(nv) = &args
// If not a string key/value, it should emit an error, but to make
// things simpler, it's handled in `DocParser` because it's simpler to
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_attr_parsing/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ pub use attributes::cfg::{
};
pub use attributes::cfg_select::*;
pub use attributes::util::{is_builtin_attr, parse_version};
pub use context::{OmitDoc, ShouldEmit};
pub use context::ShouldEmit;
pub use diagnostics::ParsedDescription;
pub use interface::{AttributeParser, EmitAttribute};
pub use rustc_parse::parser::Recovery;
Expand Down
16 changes: 15 additions & 1 deletion compiler/rustc_attr_parsing/src/stability.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,10 +53,24 @@ impl<'sess> AttributeParser<'sess> {
sym::prelude_import => ("the `prelude_import` attribute is for use by rustc only".to_string(), &[]),
sym::profiler_runtime => ("the `profiler_runtime` attribute is used to identify the `profiler_builtins` crate which contains the profiler runtime and will never be stable".to_string(), &[]),
sym::thread_local => ("the `thread_local` attribute is an experimental feature, and does not currently handle destructors".to_string(), &[]),
sym::rustdoc_internals => ("this subset of the `doc` attribute is meant for internal use only".to_string(), &[]),
sym::doc_notable_trait => ("the `doc(notable_trait)` attribute is experimental".to_string(), &[]),
sym::doc_cfg => ("the `doc(cfg)` and `doc(auto_cfg)` attributes are experimental".to_string(), &[]),
sym::doc_masked => ("the `doc(masked)` attribute is experimental".to_string(), &[]),
_ => (format!("the `{attr_path}` attribute is an experimental feature"), &[]),
};

let mut diag = feature_err(self.sess, gate_name, attr_path.span, explain);
// For unstable subsets of an attribute, point at that
let err_span = if matches!(
gate_name,
sym::rustdoc_internals | sym::doc_notable_trait | sym::doc_cfg | sym::doc_masked
) {
attr_span
} else {
attr_path.span
};

let mut diag = feature_err(self.sess, gate_name, err_span, explain);

// Remove the suggestion for `#![feature(staged_api)]` as these attributes are currently
// not usable outside std. If we do ever expose `#[stable]` etc under a different feature
Expand Down
1 change: 0 additions & 1 deletion compiler/rustc_expand/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@ doctest = false
[dependencies]
# tidy-alphabetical-start
rustc_ast = { path = "../rustc_ast" }
rustc_ast_passes = { path = "../rustc_ast_passes" }
rustc_ast_pretty = { path = "../rustc_ast_pretty" }
rustc_attr_ir = { path = "../rustc_attr_ir" }
rustc_attr_parsing = { path = "../rustc_attr_parsing" }
Expand Down
4 changes: 1 addition & 3 deletions compiler/rustc_expand/src/expand.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2212,15 +2212,13 @@ impl<'a, 'b> InvocationCollector<'a, 'b> {
attr
}

// Detect use of feature-gated or invalid attributes on macro invocations
// Run attributes through the attribute parser
// since they will not be detected after macro expansion.
fn check_attributes(&self, attrs: &[ast::Attribute], call: &ast::MacCall) {
use SyntheticAttr::*;
let features = self.cx.ecfg.features;
let mut attrs = attrs.iter().peekable();
let mut span: Option<Span> = None;
while let Some(attr) = attrs.next() {
rustc_ast_passes::feature_gate::check_attribute(attr, self.cx.sess, features);
validate_attr::check_attr(&self.cx.sess.psess, attr);
AttributeParser::parse_limited_all(
self.cx.sess,
Expand Down
3 changes: 1 addition & 2 deletions compiler/rustc_resolve/src/def_collector.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ use std::mem;
use rustc_ast::visit::FnKind;
use rustc_ast::*;
use rustc_attr_parsing as attr;
use rustc_attr_parsing::{AttributeParser, OmitDoc, ShouldEmit};
use rustc_attr_parsing::{AttributeParser, ShouldEmit};
use rustc_expand::expand::AstFragment;
use rustc_hir as hir;
use rustc_hir::Target;
Expand Down Expand Up @@ -187,7 +187,6 @@ impl<'a, 'ra, 'tcx> visit::Visitor<'a> for DefCollector<'a, 'ra, 'tcx> {
&i.attrs,
i.span,
Target::MacroDef,
OmitDoc::Skip,
std::convert::identity,
|_lint_id, _span, _kind| {
// FIXME(jdonszelmann): emit lints here properly
Expand Down
Loading
Loading