From be739892b1b535e9d6e372e77c6f432cad5553bf Mon Sep 17 00:00:00 2001 From: Jan Weidner Date: Thu, 21 Feb 2019 09:48:36 +0100 Subject: [PATCH 1/3] docstrings for Base, Core, Main, Module --- base/docs/basedocs.jl | 41 ++++++++++++++++++++++++++++++++------- doc/src/base/base.md | 1 - doc/src/manual/modules.md | 19 +++++++++--------- 3 files changed, 44 insertions(+), 17 deletions(-) diff --git a/base/docs/basedocs.jl b/base/docs/basedocs.jl index fac9e263eacaa..b678fab9f2676 100644 --- a/base/docs/basedocs.jl +++ b/base/docs/basedocs.jl @@ -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 @@ -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" @@ -2012,11 +2012,6 @@ See the manual section on [Tuple Types](@ref). """ Tuple -""" -The base library of Julia. -""" -kw"Base" - """ typeassert(x, type) @@ -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" + end diff --git a/doc/src/base/base.md b/doc/src/base/base.md index 3a1df621f1bff..aae785945f6dc 100644 --- a/doc/src/base/base.md +++ b/doc/src/base/base.md @@ -89,7 +89,6 @@ where ## Base Modules ```@docs -Base.Base Base.Broadcast Base.Docs Base.Iterators diff --git a/doc/src/manual/modules.md b/doc/src/manual/modules.md index 16ebfdb1ac9dd..2800969738b59 100644 --- a/doc/src/manual/modules.md +++ b/doc/src/manual/modules.md @@ -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 +``` + ## Summary of module usage To load a module, two main keywords can be used: `using` and `import`. To understand their differences, @@ -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 +``` ### Default top-level definitions and bare modules From cc7a616f3f3a526578ad2a80856cc9276e94c199 Mon Sep 17 00:00:00 2001 From: Jan Weidner Date: Sat, 23 Feb 2019 23:05:44 +0100 Subject: [PATCH 2/3] fix --- base/docs/basedocs.jl | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/base/docs/basedocs.jl b/base/docs/basedocs.jl index b678fab9f2676..a283c5855d9b6 100644 --- a/base/docs/basedocs.jl +++ b/base/docs/basedocs.jl @@ -2110,7 +2110,7 @@ Module `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" +Core.Core """ Main @@ -2121,13 +2121,13 @@ julia> @__MODULE__ Main ``` """ -kw"Main" +Main.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" +Base.Base end From b1bb96bb218f1b38d285906c804b495b81279c48 Mon Sep 17 00:00:00 2001 From: Jan Weidner Date: Wed, 27 Feb 2019 12:03:42 +0100 Subject: [PATCH 3/3] fix --- base/docs/basedocs.jl | 2 +- doc/src/base/base.md | 10 +++++++++- doc/src/manual/modules.md | 16 ++++------------ 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/base/docs/basedocs.jl b/base/docs/basedocs.jl index a283c5855d9b6..ce193e2f2b8c7 100644 --- a/base/docs/basedocs.jl +++ b/base/docs/basedocs.jl @@ -2124,7 +2124,7 @@ Main Main.Main """ - `Base` + 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. """ diff --git a/doc/src/base/base.md b/doc/src/base/base.md index aae785945f6dc..6d15600de6720 100644 --- a/doc/src/base/base.md +++ b/doc/src/base/base.md @@ -87,7 +87,14 @@ where = ``` -## Base Modules +## Standard Modules +```@docs +Main +Core +Base +``` + +## Base Submodules ```@docs Base.Broadcast Base.Docs @@ -210,6 +217,7 @@ Base.Enums.@enum Core.Expr Core.Symbol Core.Symbol(x...) +Core.Module ``` ## Generic Functions diff --git a/doc/src/manual/modules.md b/doc/src/manual/modules.md index 2800969738b59..80f59fff0a7d2 100644 --- a/doc/src/manual/modules.md +++ b/doc/src/manual/modules.md @@ -57,11 +57,6 @@ 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 -``` - ## Summary of module usage To load a module, two main keywords can be used: `using` and `import`. To understand their differences, @@ -122,13 +117,10 @@ end ### Standard modules -There are three important standard modules: `Main`, `Core`, and `Base`. - -```@docs -Main -Core -Base -``` +There are three important standard modules: +* [`Core`](@ref) contains all functionality "built into" the language. +* [`Base`](@ref) contains basic functionality that is useful in almost all cases. +* [`Main`](@ref) is the top-level module and the current module, when Julia is started. ### Default top-level definitions and bare modules