this post was submitted on 20 Dec 2025
73 points (97.4% liked)
Rust
7601 readers
34 users here now
Welcome to the Rust community! This is a place to discuss about the Rust programming language.
Wormhole
Credits
- The icon is a modified version of the official rust logo (changing the colors to a gradient and black background)
founded 2 years ago
MODERATORS
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
Yeah, as I'm implementing this, I'm also now noticing how problematic that crate split is.
If you want to generate code which uses (non-generated) types that your crate provides in its public API, you have to re-export the macro from a separate crate that also re-exports the types.
That in itself is clunky, but it's just complexity for the implementer, not the user, so it's fine.
But where it stops being fine is that this means you cannot easily provide a usage example in the macro's documentation.
If you try to use it like normal, it has to generate code referring to your API crate, which will not be defined in your macro crate, so the documentation test won't compile.
So, basically your choices are:
And yeah... if you've coded Rust for long enough, you will recognize these patterns of bad/missing usage examples, which is particularly problematic, because proc-macros are rarely terribly obvious to use. Really hope they can fix this sooner rather than later.
As far as I can tell, it would even be a valid fix, if editors and such consistently showed the documentation declared on top of the re-export, then you could write out your usage example there.