dtolnay / dtolnay/proc-macro-workshop

confusing readme explanation about enabling syn "extra-traits" feature during development

Open Beginner friendly
#82 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.