Reorganize the Modules chapter of the manual.

[tpapp]

Motivation

Many users, especially from languages which either don't have namespaces or do not use them widely, are confused by various aspects of Julia's namespace management. This is a reorganization (and partial rewrite) or the relevant chapter, with the intention that it should tide us over until (if) breaking changes like #8000 happen.

I have searched the issues and the Discourse forum for related topics and tried to address every issue that comes up in a concise but occasionally introductory/pedagogical manner, going into details and corner cases when relevant after conveying the main idea. Each particular change/addition was motivated by people running into problems with some feature. I combined and modified examples from various contributors, and only reference the original when I use it unchanged.

Since this is a substantial rewrite, thorough reviews would be appreciated. If, despite best effort, I missed some commonly used scenarios or made mistakes, please comment and I am happy to address them.

Main changes

Namespaces, export, import, using

• explain namespaces, qualified symbol names, and export lists
• consolidate examples where applicable
• fix examples which were outdated after make using A.B only for modules, using A: B only for single bindings #25306
• distribute the “Namespace miscellanea” section into parts in the appropriate sections
• break up the summary table and explain each case in detail with examples
• subsection on various strategies to handle symbol conflicts
• use “bring into the namespace/scope” instead of “import” in the text, as readers confuse it with import
• explicitly document what happens with multiple using / import statements
• add relevant style / best practices suggestions which are now widely used in the Julia ecosystem

Submodules

• discuss usage of using ParentModule.SubModule etc (relies on code loading)
• add submodule examples where order matters, fixes What is the semantics of importing a top-level module from a sub-module? #38011 (also another example by @rdeits from Discourse)
• mention that submodules do not “inherit” scope from parent

Misc incidental changes

• in the Methods chapter, add a note about adding methods to functions in other modules
• add a markdown id to the code-loading chapter

The “Module initialization and precompilation” section was reviewed, but is left unchanged.

[timholy]

This is great, thanks for doing this!

[simonbyrne]

Thank you!

[timholy]

Awesome, thanks!