Doc comments and attributes on macro arms

[notriddle]

Proposal

Allow attributes on macro_rules and macros 2.0 arms. Only outer attributes would be supported, since the meaning of an inner attribute on a macro arm isn't obvious.

I want this for documentation:

• this MCP is a follow-up for https://github.com/rust-lang/rust/pull/148005, and it is meant to be used with RFC 3697 and RFC 3698 mixed-syntax macro rules macros.
• we've also been straight-up asked for this feature

macro_rules! mixed_syntax_macro {
    /// This macro can be used as an attribute. For example:
    ///
    /// ```
    /// #[mixed_syntax_macro(key = value)]
    /// pub struct Foo;
    /// ```
    attr(key = $value:tt) ($attached_to:item) => {
        $item
    };
    #[doc=include_str!("derive.md")]
    derive() ($attached_to:item) => {};
}

To make this work, significantly more parsing would need done in the AST, and LateResolutionVisitor::resolve_doc_links would need to visit each macro arm. This probably also means there would be an hir::MacroArm node, similar to how hir::Stmt works (statements, like macro arms, have no name, but they do have an HirId, and you can attach attributes to them).

AST

/// Represents a declarative macro definition.
#[derive(Clone, Encodable, Decodable, Debug, Walkable)]
pub struct MacroDef<A=ast::Attribute> {
    pub arms: ThinVec<MacroArm<A>>,
    /// `true` if macro was defined with `macro_rules`.
    pub macro_rules: bool,
}

/// Represents part of a macro definition.
///
/// ```text
/// attrs? pattern => body;
/// ```
#[derive(Clone, Encodable, Decodable, Debug, Walkable)]
pub struct MacroArm<A=ast::Attribute> {
    pub attrs: ThinVec<A>,
    pub pattern: MacroArmPattern,
    pub arrow: Span,
    pub body: DelimArgs,
}

#[derive(Clone, Encodable, Decodable, Debug, Walkable)]
pub enum MacroArmPattern {
    Bang(TokenTree),
    Derive(TokenTree, TokenTree),
    Attr(TokenTree, TokenTree),
}

HIR

Each macro arm winds up holding its attributes, instead of giving each node an HirId. This lets us serialize the parsed attributes the same way they're already done for macro defs.

pub type MacroDef = ast::MacroDef<hir::Attribute>;

Lowering an AST MacroDef into an HIR MacroDef will, of course, include converting the attributes.

The reason I don't think we should actually try to lower these things more? Because the primary purpose of HIR is just to extract the doc comments. I don't actually want to use HIR MacroDef to run macros, because that would be a circular dependency (we can't generate HIR until after we've already done all the AST lowering).

Mentors or Reviewers

If you have a reviewer or mentor in mind for this work, mention them here. You can put your own name here if you are planning to mentor the work.

Process

The main points of the Major Change Process are as follows:

• [x] File an issue describing the proposal.
• [ ] A compiler team member who is knowledgeable in the area can second by writing @rustbot second or kickoff a team FCP with @rfcbot fcp $RESOLUTION.
  • Refer to Proposals, Approvals and Stabilization docs for when a second is sufficient, or when a full team FCP is required.
• [ ] Once an MCP is seconded, the Final Comment Period begins.
  • Final Comment Period lasts for 10 days after all outstanding concerns are solved.
  • Outstanding concerns will block the Final Comment Period from finishing. Once all concerns are resolved, the 10 day countdown is restarted.
  • If no concerns are raised after 10 days since the resolution of the last outstanding concern, the MCP is considered approved.

You can read more about Major Change Proposals on forge.

[!CAUTION]

Concerns (1 active)

• lang

Managed by @rustbot—see help for details.

[rustbot]

[!IMPORTANT] This issue is not meant to be used for technical discussion. There is a Zulip stream for that. Use this issue to leave procedural comments, such as volunteering to review, indicating that you second the proposal (or third, etc), or raising a concern that you would like to be addressed.

Concerns or objections can formally be registered here by adding a comment.

@rustbot concern reason-for-concern
<description of the concern>

Concerns can be lifted with:

@rustbot resolve reason-for-concern

See documentation at https://forge.rust-lang.org

cc @rust-lang/compiler

[fmease]

@rustbot concern lang

This proposal affects the language and as such it is first and foremost a T-lang matter, not a T-compiler one. This should be refiled as a request for a lang experiment in r-l/r or r-l/lang-team.