Tracking Issue for #[diagnostic::on_unmatched_args] #155642

Feature gate: #![feature(diagnostic_on_unmatched_args)]

The diagnostic_on_unmatched_args feature adds the
#[diagnostic::on_unmatched_args(...)] attribute for declarative macros.

This attribute lets macro definitions customize diagnostics emitted when a
macro invocation does not match any macro arm because the provided arguments
do not match the macro matcher. This includes cases such as missing tokens,
extra tokens, or otherwise invalid macro arguments.

Public API

The feature exposes the diagnostic attribute:

#![feature(diagnostic_on_unmatched_args)]

#[diagnostic::on_unmatched_args(
    message = "invalid arguments to {This} macro invocation",
    label = "expected a type and value here",
    note = "this macro expects a type and a value, like `pair!(u8, 0)`",
)]
macro_rules! pair {
    ($ty:ty, $value:expr) => {};
}

pair!(u8);

Supported options:

• message: overrides the primary diagnostic message.
• label: overrides the label attached to the macro invocation span.
• note: adds one note to the diagnostic. Multiple note entries are allowed.

Supported format parameters:

• {This} refers to the macro name.

The attribute currently applies to declarative macros such as macro_rules!
and pub macro.

Steps / History

(Remember to update the S-tracking-* label when checking boxes.)

• Implementation:
  • Add on_unmatch_args #154794
  • Rename diagnostic::on_unmatch_args to diagnostic::on_unmatched_args #157887
• Add or document tests for behavior on unsupported macro kinds
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

• Should this attribute remain limited to declarative macros, or should similar customization be supported for procedural macros?
• Should this feature eventually be generalized beyond macro argument mismatch diagnostics?