better way to keep required features and documentation synced
!681 (merged) added annotations so rustdoc print what features need to be enabled to get access to a given function/module/structure/field, and a script to help keeping everything in sync. That script is far from perfect, in !713 (closed) I tried making it learn new tricks, and in !721 (closed) Diziet tried to replace it with something that does more than pattern matching and actually understand a bit of rust. The first approach won't ever be exhaustive and has edge case everywhere (like at line-breaks), and the second will probably be more work than it's worth, while possibly not being exhaustive either.
On !721 (closed) I proposed a different scheme, instead of trying to parse rust ourselves, what if we let rustdoc do what it does (1) with no feature, (2) with all features, and (3) ask it about what it thinks requires feature. If (2) - (1) == (3)
, everything is fine. If not, some cfg_attr
needs to be updated.
The main issue with that approach is it won't tell us if the cfg_attr
is exactly the good one (doing so would be very expensive), and it will fail to acknowledge target_family
, target_arch
and target_os
. That second part is not as bad as it could be given we use these mostly in context where feature(doc_auto_cfg)
works, and we don't use many of these on our public interface.