gfx-rs
Consider not preferring `pub(super)`
Copied from review discussion:
@cwfitzgerald Convention here is just pub(super)
@kpreid IMO, using super, particularly across files, is fragile and best kept to a minimum, because it means that module-moving refactors can have surprising effects. I’ll change it anyway, but I am noting that I disagree with this policy.
@cwfitzgerald Yeah that makes sense - I don't really have much of a preference either way, just following existing convention. Might be worth an issue about changing it. While hal backends have historically been a single mod + submodules, as we split things up more, we might see deeper splits.
Default private visibility is to this module (and children). pub(crate) limits visibilty to this crate. pub(in path) visibility is explicit about its purpose. pub(super) visibility is an oddball which limits visibility to whichever module happens to be this module’s parent. This is undesirable action-at-a-distance which can lead to, after refactoring, items being visible where they aren’t intended to be. I don’t think that this is a very serious problem, but I think that a policy of using pub(super) instead of pub(in path) is an unwise policy.
I don't consider the stance of pub(in …) by default controversial, myself. 🙂
For most functionality I've seen in my lifetime as a Rustacean, I've not seen a compelling case for pub(super). Usually, a visibility associated with a specific path is the intent. Using it in those cases makes it clearer why things stopped compiling during changes—pub(super) on a suddenly missing symbol offers a lot less clear of a compiler diagnostic than, say, pub(in crate::front::wgsl), for example.
I will resist any dogmatic assertion that pub(super) is never to be used, particularly for code generation and inline modules. However, I think it's make a policy that, by default, pub(in …) should be preferred, where pub(super) needs good justification before being merged.
Thoughts, @gfx-rs/wgpu?
This is undesirable action-at-a-distance which can lead to, after refactoring, items being visible where they aren’t intended to be.
I'm actually not sure if I understand how this case is problematic, at least for imports accidental being more visible within the crate. Are you referring to accidental exposing an item via pub and, say, pub use …::* glob imports?
I'm actually not sure if I understand how this case is problematic, at least for imports accidental being more visible within the crate.
In a sense, all visibilities lower than pub(crate) are solely documentation of authors’ intent (except when macros generate unsafe code). So, there is no technical problem, but the pub(super) is now mis-documenting the intent.