Numerous times I forgot that RUSTFLAGS != RUSTDOCFLAGS and got bit by it. I've also seen other people with the same problem. Annoyingly, in addition to wasting my time, today I've also wasted some of Ralf's time reporting "a bug in miri" and I'd be surprised if I'm the only one who have done such thing. These two variables being different is a footgun also because cargo test runs both so we need to set both variables.
Can we do something like print a warning if RUSTFLAGS is set but not RUSTDOCFLAGSand doc tests are being compiled? That'd already help a lot, I think.
That's also a good perspective but it needs addressing the reasons why people use RUSTFLAGS in the first place (there are multiple of them) - exposing the configuration by cargo itself.