Crate proc_macro2_diagnostic 

Provides a DiagnosticResult which makes it easy to implement multi-level compiler messages based upon the experimental proc_macro::Diagnostic and allows simple idiomatic error handling via ? while ensuring errors & warnings are properly emitted by the compiler.

Note

This crate is deliberately opinionated and focusses on making it easy to create good compiler errors and handle them easily:

• Top level diagnostics must be either an Error or a Warning
• (Only) Help & Notes can be added to a diagnostic
• Errors always span the original call site - add a Help or Note to add information related to other spans
• Warnings will always finish with a Note detailing the original call site
• Multi-level nesting is not possible
• We do not provide a implementation of the full proc_macro::Diagnostic API. Other crates attempt to do this, if that is what you are after.

Stability & MSRV

Given that this crate exposes an experimental API from std it makes use of experimental features which require a nightly toolchain.

🔬 Experimental Features

This crate makes use of the following experimental features:

• #![feature(assert_matches)] (stable since 2026-02-12)
• #![feature(never_type)]
• #![feature(proc_macro_diagnostic)]
• #![feature(try_trait_v2)]

This list includes any unstable features used by direct & transitive dependencies (currently, none).

The authors consider all of the above features to be reliable and already well advanced in the stabilisation process.

You do not need to enable these in your own code, the list is for information only.

Stability guarantees

We run automated tests every month to ensure no fundamental changes affect this crate and test every PR against the current nightly, as well as the current equivalent beta & stable. If you find an issue before we do, please raise an issue on github.

MSRV

For those of you working with a pinned nightly (etc.) this crate supports every version of edition 2024 (rust 1.85.1 onwards, released as stable on 20225-03-18). We use autocfg to seamlessly handle features which have been stabilised since then.

Dependencies

We deliberately keep the dependency list short and pay attention to any transitive dependencies we bring in.

Current dependency tree:

proc_macro2_diagnostic <- This crate
└── proc-macro2
    └── unicode-ident

Modules

prelude

Prelude for easy *`` imports: use proc_macro2_diagnostic::prelude::*`

Structs

DiagnosticResult

Result-like type which can represent a valid return value, an error or a warning accompanying a valid return value. Warnings will be emitted upon ?, allowing your code to continue with the valid value. Errors will short-circuit upon ? and be emitted upon final conversion to a proc_macro::TokenStream

Enums

DiagnosticResultKind

The type of top-level message contained in the DiagnosticResult

Functions

Ok

Create an Ok result.

error

Create an error spanning the macro call_site

error_spanned

Create an error at the given Spans.

warn_spanned

Create a warning which will emit a message at the given Spans and deconstruct to a valid value via ?.

Type Aliases

DiagnosticStream

A convenience type which is designed to be returned from a proc_macro2-based macro implementation.