Split traits by crate-local and crate-non-local by MeetThePatel · Pull Request #130418 · rust-lang/rust (original) (raw)
The main problem that I am trying to solve is to make more clear in the documentation the distinction between:
- functionality of the current struct/enum that is defined outside the crate, typically in
stdorcore(what I'll call "standardized behaviour"). - functionality that is defined inside the crate (although in cases like GTK, like @notriddle mentioned above, I think it makes more sense to check if the trait is from the current workspace, as opposed to the current crate) (what I'll call "non-standardized behaviour").
Note: Perhaps there is better terminology than standardized/non-standardized to describe this distinction.
Motivating Example: typed-floats
I had been working with the typed-floats crate a few weeks back. Due to the fact that there are a lot of trait implementations, it can be quite a challenge to see at a glance the set of functionality that typed-floats introduces (e.g. Atan2, Copysign, DivEuclid, etc.), vs. the set of functionality that typed-floats provides compatibility for (e.g. From<f32>, Display, Default).
Essentially, "non-standardized behaviour" is encapsulating behaviour that you would need to understand first if you really want to understand how the struct/enum relates to and works within the crate. "standardized behaviour" would then encapsulate everything else.
To address some of the other concerns:
How does this behave when a trait is inlined from another crate? Does it count as the crate that originally defined it, or the crate that holds its documentation?
I tested this out in this repo. In the implementation I have, it is recognizing the re-exported trait as a foreign trait. I'm not sure if this should be the correct behaviour, as if the trait is being re-exported, it would be considered essential enough to the crate to deem as non-standardized behaviour. Would love input on this choice.
How does this relate to the auto / blanket impl sections? Should there be separate "External Blanket Traits / Crate Blanket Traits" sections? I don't see them in your screenshot, but why not?
Yes. Apologies, I missed this.
There's an existing feature that sort of mirrors this, where "Foreign Types" are listed on the trait pages. We had to special-case the standard library to simplify things for new users. Should we do the same thing here?
After going through the case of GTK like @notriddle suggested above, I think that a similar fix would be needed. When I generated GTK's docs with my PR, it didn't wind up changing much (at least in the files that I checked). The structs that I looked at were organized such that traits (internal to GTK, but external to the current trait) would be recognized as external. I don't think this makes sense, as the whole point of the suggested distinction is to separate out current-project behaviour from external behaviour. So, unless there is a way to check if Items are from the current workspace, I think the fix above will have to be done.
Maybe it should be called "Foreign Trait Implementations"?
This makes a lot more sense.
For example, dividing the impls up by the crate itself (so std and glib both get their own sections), or specifically dividing standard library traits from all others (so Standard Library traits get a separate section from other traits)
For the former, I believe that this would create too many subheadings in the sidebar, ultimately adding confusion to the reader. I think that the latter is a much better option. Again, this would have to be done using the method linked (separate std, alloc and core, and then split the remaining).
I hope this answers the concerns raised. I'd appreciate input on the proposed changes, as perhaps there is a way to, as @GuillaumeGomez mentioned, avoid negatively impacting workspace projects like GTK and Bevy.