Doc comments and attributes on macro arms #935
Description
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 rustdoc: add support for macro_rules macros of multiple kinds rust#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:
- File an issue describing the proposal.
- A compiler team member who is knowledgeable in the area can second by writing
@rustbot secondor 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.