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

docstrings for Base, Core, Main, Module #31131

Merged
merged 4 commits into from
Mar 3, 2019
Merged

docstrings for Base, Core, Main, Module #31131

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
be73989
docstrings for Base, Core, Main, Module
jw3126 Feb 21, 2019
cc7a616
fix
jw3126 Feb 23, 2019
b1bb96b
fix
jw3126 Feb 27, 2019
45c7028
Merge branch 'master' into doc
jw3126 Mar 2, 2019
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
41 changes: 34 additions & 7 deletions base/docs/basedocs.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ kw"abstract type"
"""
module

`module` declares a `Module`, which is a separate global variable workspace. Within a
`module` declares a [`Module`](@ref), which is a separate global variable workspace. Within a
module, you can control which names from other modules are visible (via importing), and
specify which of your names are intended to be public (via exporting).
Modules allow you to create top-level definitions without worrying about name conflicts
Expand Down Expand Up @@ -103,7 +103,7 @@ kw"module"
"""
baremodule

`baremodule` declares a module that does not contain `using Base`
`baremodule` declares a [`Module`](@ref) that does not contain `using Base`
or a definition of `eval`. It does still import `Core`.
"""
kw"baremodule"
Expand Down Expand Up @@ -2012,11 +2012,6 @@ See the manual section on [Tuple Types](@ref).
"""
Tuple

"""
The base library of Julia.
"""
kw"Base"

"""
typeassert(x, type)

Expand Down Expand Up @@ -2103,4 +2098,36 @@ Union type of [`StridedVector`](@ref) and [`StridedMatrix`](@ref) with elements
"""
StridedVecOrMat

"""
Module

A `Module` is a separate global variable workspace. See [`module`](@ref) and the [manual section about modules](@ref modules) for details.
"""
Module

"""
Core

`Core` is the module that contains all identifiers considered "built in" to the language, i.e. part of the core language and not libraries. Every module implicitly specifies `using Core`, since you can't do anything without those definitions.
"""
kw"Core"

"""
Main

`Main` is the top-level module, and Julia starts with `Main` set as the current module. Variables defined at the prompt go in `Main`, and `varinfo` lists variables in `Main`.
```jldoctest
julia> @__MODULE__
Main
```
"""
kw"Main"

"""
`Base`

The base library of Julia. `Base` is a module that contains basic functionality (the contents of `base/`). All modules implicitly contain `using Base`, since this is needed in the vast majority of cases.
"""
kw"Base"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure why these would be handled like keywords. Can we attach the doc strings to the modules themselves instead?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that kw"Base" was introduced before this PR. I guess maybe for some kind of bootstrap reason? Anyway in case of Main and Core I needed to do this in order to make e.g.

help?> Core

work.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is what I get, if I remove kw:

help?> Base
search: Base basename AbstractSet Broadcast broadcast broadcast! AbstractString AbstractDisplay set_zero_subnormals get_zero_subnormals

  No documentation found.

  No docstring found for module Base.

help?> Main
search: Main DomainError maxintfloat SegmentationFault maximum maximum! Matrix BitMatrix mapslices DenseMatrix timedwait StridedMatrix

  No documentation found.

  No docstring found for module Main.

help?> Core
search: Core isconcretetype searchsorted searchsortedlast searchsortedfirst code_lowered @code_lowered StackOverflowError code_warntype

  No documentation found.

  No docstring found for module Core.

help?> Main.Core
  No documentation found.

  No docstring found for module Core.

help?> Core.Main
  Main

  Main is the top-level module, and Julia starts with Main set as the current module. Variables defined at the prompt go in Main, and
  varinfo lists variables in Main.

  julia> @__MODULE__
  Main

help?> Main.Base
  No documentation found.

  No docstring found for module Base.

help?> Base
search: Base basename AbstractSet Broadcast broadcast broadcast! AbstractString AbstractDisplay set_zero_subnormals get_zero_subnormals

  No documentation found.

  No docstring found for module Base.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see. It seems to work if you document a module's "self binding", i.e. Base.Base, Core.Core, and Core.Main.Main.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cool, it works!


end
1 change: 0 additions & 1 deletion doc/src/base/base.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,6 @@ where

## Base Modules
```@docs
Base.Base
Base.Broadcast
Base.Docs
Base.Iterators
Expand Down
19 changes: 10 additions & 9 deletions doc/src/manual/modules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,11 @@ Once a variable is made visible via `using` or `import`, a module may not create
with the same name. Imported variables are read-only; assigning to a global variable always affects
a variable owned by the current module, or else raises an error.

Modules are first class citizens in Julia and are represented by a `Module`.
```@docs
Module
```
jw3126 marked this conversation as resolved.
Show resolved Hide resolved

## Summary of module usage

To load a module, two main keywords can be used: `using` and `import`. To understand their differences,
Expand Down Expand Up @@ -119,15 +124,11 @@ end

There are three important standard modules: `Main`, `Core`, and `Base`.

`Main` is the top-level module, and Julia starts with `Main` set as the current module. Variables
defined at the prompt go in `Main`, and [`varinfo()`](@ref) lists variables in `Main`.

`Core` contains all identifiers considered "built in" to the language, i.e. part of the core language
and not libraries. Every module implicitly specifies `using Core`, since you can't do anything
without those definitions.

`Base` is a module that contains basic functionality (the contents of `base/`). All modules implicitly contain `using Base`,
since this is needed in the vast majority of cases.
```@docs
Main
Core
Base
```
jw3126 marked this conversation as resolved.
Show resolved Hide resolved

### Default top-level definitions and bare modules

Expand Down