[ch07-03] clarify private items usage inside child modules

[said026]

Add some clarification regarding the usage of private items inside child modules

[chriskrycho]

Thanks for the suggestion! I think in this case we'll leave it as is. It's actually not just about where the items are defined, but about what privacy they have in that module. Consider:

// pub or not does not matter to children
struct InRoot;

mod child {
    mod grandchild {
        // public anywhere that `child` module chooses to expose them
        pub struct PubInGrandchildAndChild;
        pub struct OnlyPubInGrandchild;
        
        // *only* public where
        pub(super) struct CanOnlyBeUsedInChild;
        
        // Not accessible outside `grandchild`;
        struct PrivateInGrandchild;
    }
    
    // This makes `PubInGrandchildAndChild` visible outside `child`
    pub use grandchild::PubInGrandchildAndChild;
    
    // this is not legal
    // pub use grandchild::PrivateInGrandchild;
    
    // neither is this, though:
    // pub use grandchild::CanOnlyBeUsedInChild;
}

Notice that we can use PubInGrandchildAndChild in the root regardless of where it was defined (in this case, in child::grandchild) because it was defined in a way that it could be exported to a level of visibility that allows the root to see it. By the same token, even though OnlyPubInGrandchild is defined exactly the same way as PubInGrandchildAndChild, it is not visible in the root because child does not re-export it. The same basic dynamics are in play in general throughout the module system. You can mess around with this example and these details in this playground.

Hope that helps clarify; Rust’s module system is definitely a bit confusing at times! And thanks again for the suggestion!