Reorganize the Modules chapter of the manual. (#38271)

* Reorganize the Modules chapter of the manual.

Main changes

Namespaces, export, import, using

- explain namespaces, qualified symbol names, and export lists
- consolidate examples where applicable
- fix examples which were outdated after #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 #38011 (also another example by @rdeits [from Discourse](https://discourse.julialang.org/t/problem-with-using-in-submodules/42321/2))
- 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 is left unchanged.

Co-authored-by: Tim Holy <[email protected]>
Co-authored-by: Simon Byrne <[email protected]>

base/initdefs.jl

@@ -83,7 +83,7 @@ Here is an overview of some of the subdirectories that may exist in a depot:
 
 See also:
 [`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH), and
-[Code Loading](@ref Code-Loading).
+[Code Loading](@ref code-loading).
 """
 const DEPOT_PATH = String[]
 
@@ -165,7 +165,7 @@ See also:
 [`JULIA_LOAD_PATH`](@ref JULIA_LOAD_PATH),
 [`JULIA_PROJECT`](@ref JULIA_PROJECT),
 [`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH), and
-[Code Loading](@ref Code-Loading).
+[Code Loading](@ref code-loading).
 """
 const LOAD_PATH = copy(DEFAULT_LOAD_PATH)
 # HOME_PROJECT is no longer used, here just to avoid breaking things

doc/src/manual/code-loading.md

@@ -1,4 +1,4 @@
-# Code Loading
+# [Code Loading](@id code-loading)
 
 !!! note
  This chapter covers the technical details of package loading. To install packages, use [`Pkg`](@ref Pkg), Julia's built-in package manager, to add packages to your active environment. To use packages already in your active environment, write `import X` or `using X`, as described in the [Modules documentation](@ref modules).

doc/src/manual/environment-variables.md

@@ -80,7 +80,7 @@ Setting this environment variable has the same effect as specifying the `--proje
 start-up option, but `--project` has higher precedence. If the variable is set to `@.`
 then Julia tries to find a project directory that contains `Project.toml` or
 `JuliaProject.toml` file from the current directory and its parents. See also
-the chapter on [Code Loading](@ref).
+the chapter on [Code Loading](@ref code-loading).
 
 !!! note
 
@@ -91,7 +91,7 @@ the chapter on [Code Loading](@ref).
 
 The `JULIA_LOAD_PATH` environment variable is used to populate the global Julia
 [`LOAD_PATH`](@ref) variable, which determines which packages can be loaded via
-`import` and `using` (see [Code Loading](@ref)).
+`import` and `using` (see [Code Loading](@ref code-loading)).
 
 Unlike the shell `PATH` variable, empty entries in `JULIA_LOAD_PATH` are expanded to
 the default value of `LOAD_PATH`, `["@", "@v#.#", "@stdlib"]` when populating

doc/src/manual/methods.md

@@ -40,6 +40,11 @@ for structuring and organizing programs.
  an explicit method argument. When the current `this` object is the receiver of a method call,
  it can be omitted altogether, writing just `meth(arg1,arg2)`, with `this` implied as the receiving
  object.
+!!! note
+ All the examples in this chapter assume that you are defining modules for a function in the *same*
+ module. If you want to add methods to a function in *another* module, you have to `import` it or
+ use the name qualified with module names. See the section on [namespace management](@ref
+ namespace-management).
 
 ## Defining Methods