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

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:
  • rust-lang/rust#154794
  • rust-lang/rust#157887
• Add or document tests for behavior on unsupported macro kinds
• Final comment period (FCP)^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?

Start by reviewing the implementation in rust-lang/rust#154794 and rust-lang/rust#157887, then inspect existing tests or documentation for unsupported macro kinds. Add or document the missing behavior and verify it with the relevant compiler tests. The checklist is complete when unsupported macro kinds are covered and the remaining stabilization work is ready for review.