dtolnay / dtolnay/proc-macro-workshop
confusing readme explanation about enabling syn "extra-traits" feature during development
- Dominant language
- Rust
- Stars
- 4.9k
- Forks
- 1.2k
- PR merge metrics
- No merged PRs in 30d
Description
In the readme the [Debugging tips](https://github.com/dtolnay/proc-macro-workshop#debugging-tips) section suggests:
> Note that in order for Syn's syntax tree types to provide Debug impls, you will
> need to set `features = ["extra-traits"]` on the dependency on Syn. This is
> because adding hundreds of Debug impls adds an appreciable amount of compile
> time to Syn, and we really only need this enabled while doing development on a
> macro rather than when the finished macro is published to users.
While it isn't clearly stated, this gives the impression that the `extra-traits` feature should be enabled via:
```toml
[dev-dependencies]
syn = { version = "2.0.118", features = ["extra-traits"] }
[dependencies]
syn = "2.0.118"
```
This doesn't work on Rust edition `2021` and above because they use Cargo Resolver version `"2"` or `"3"` which [ignores `[dev-dependencies]` for non-workspace members](https://doc.rust-lang.org/cargo/reference/resolver.html#dependency-kinds).
Experienced Rustaceans will probably already know this but newbies like myself might end up spending a lot of time trying to figure out what is going on.
From what I understand the workaround is to enable the `syn` `extra-traits` feature via a crate feature like:
```toml
[features]
__dev = ["syn/extra-traits"]
```
And then use `cargo test --features=__dev` and `cargo check --features=__dev`.
Perhaps this could be more clearly presented in the readme?
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the README's Debugging tips section and verify the stated Syn feature behavior under Rust editions using the Cargo resolver documentation. Clarify how to enable `extra-traits` during development and which commands to run; done means a newcomer can follow the README without relying on dev-dependencies that are ignored.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100