document module docstring scope (#54429)

doc/src/manual/documentation.md

@@ -511,6 +511,20 @@ end
 Adds docstring `"..."` to the `Module` `M`. Adding the docstring above the `Module` is the preferred
 syntax, however both are equivalent.
 
+The module docstring is evaluated *inside* the scope of the module, allowing
+access to all the symbols defined in and imported into the module:
+
+```julia
+"The magic number is $(MAGIC)."
+module DocStringEval
+const MAGIC = 42
+end
+```
+
+Documenting a `baremodule` by placing a docstring above the expression automatically imports
+`@doc` into the module. These imports must be done manually when the module expression is not
+documented:
+
 ```julia
 "..."
 baremodule M
@@ -527,10 +541,6 @@ f(x) = x
 end
 ```
 
-Documenting a `baremodule` by placing a docstring above the expression automatically imports
-`@doc` into the module. These imports must be done manually when the module expression is not
-documented.
-
 ### Global Variables
 
 ```julia

test/docs.jl

@@ -120,7 +120,7 @@ module NoDocStrings end
 # General tests for docstrings.
 
 const LINE_NUMBER = @__LINE__() + 1
-"DocsTest"
+"DocsTest, evaluating $(K)" # test that module docstring is evaluated within module
 module DocsTest
 
 using Markdown
@@ -265,7 +265,7 @@ fnospecialize(@nospecialize(x::AbstractArray)) = 2
 end
 
 let md = meta(DocsTest)[@var(DocsTest)]
- @test docstrings_equal(md.docs[Union{}], doc"DocsTest")
+ @test docstrings_equal(md.docs[Union{}], doc"DocsTest, evaluating K")
  # Check that plain docstrings store a module reference.
  # https://github.com/JuliaLang/julia/pull/13017#issuecomment-138618663
  @test md.docs[Union{}].data[:module] == DocsTest