Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

document module docstring scope #54429

Merged
merged 3 commits into from
May 25, 2024
Merged

document module docstring scope #54429

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2d1eb5a
Document the scope of module docstrings.
tpapp May 10, 2024
a6f31e1
add a basic test
tpapp May 10, 2024
5c9e2cb
Merge branch 'master' into tp/document-module-docstring-scope
fingolfin May 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 14 additions & 4 deletions doc/src/manual/documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
4 changes: 2 additions & 2 deletions test/docs.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down