diff --git a/base/docs/basedocs.jl b/base/docs/basedocs.jl index e58f0f51913fb..596a3bd21e24b 100644 --- a/base/docs/basedocs.jl +++ b/base/docs/basedocs.jl @@ -309,8 +309,8 @@ kw"let" """ quote -`quote` creates multiple expression objects in a block without using the explicit `Expr` -constructor. For example: +`quote` creates multiple expression objects in a block without using the explicit +[`Expr`](@ref) constructor. For example: ```julia ex = quote diff --git a/base/essentials.jl b/base/essentials.jl index 984ef41ff0129..036b71ebb2ca6 100644 --- a/base/essentials.jl +++ b/base/essentials.jl @@ -434,7 +434,7 @@ end """ esc(e) -Only valid in the context of an `Expr` returned from a macro. Prevents the macro hygiene +Only valid in the context of an [`Expr`](@ref) returned from a macro. Prevents the macro hygiene pass from turning embedded variables into gensym variables. See the [Macros](@ref man-macros) section of the Metaprogramming chapter of the manual for more details and examples. """ diff --git a/base/iostream.jl b/base/iostream.jl index bbb13632747ab..e24458b4f4bf0 100644 --- a/base/iostream.jl +++ b/base/iostream.jl @@ -205,7 +205,7 @@ eof(s::IOStream) = ccall(:ios_eof_blocking, Cint, (Ptr{Cvoid},), s.ios)!=0 """ fdio([name::AbstractString, ]fd::Integer[, own::Bool=false]) -> IOStream -Create an `IOStream` object from an integer file descriptor. If `own` is `true`, closing +Create an [`IOStream`](@ref) object from an integer file descriptor. If `own` is `true`, closing this object will close the underlying descriptor. By default, an `IOStream` is closed when it is garbage collected. `name` allows you to associate the descriptor with a named file. """ diff --git a/base/logging.jl b/base/logging.jl index ef6ca0380d12f..2aaa0b2d0b5c3 100644 --- a/base/logging.jl +++ b/base/logging.jl @@ -33,7 +33,7 @@ abstract type AbstractLogger ; end Log a message to `logger` at `level`. The logical location at which the message was generated is given by module `_module` and `group`; the source -location by `file` and `line`. `id` is an arbitrary unique `Symbol` to be used +location by `file` and `line`. `id` is an arbitrary unique [`Symbol`](@ref) to be used as a key to identify the log statement when filtering. """ function handle_message end @@ -150,7 +150,7 @@ formatted as markdown when presented. The optional list of `key=value` pairs supports arbitrary user defined metadata which will be passed through to the logging backend as part of the log record. If only a `value` expression is supplied, a key representing the -expression will be generated using `Symbol`. For example, `x` becomes `x=x`, +expression will be generated using [`Symbol`](@ref). For example, `x` becomes `x=x`, and `foo(10)` becomes `Symbol("foo(10)")=foo(10)`. For splatting a list of key value pairs, use the normal splatting syntax, `@info "blah" kws...`. diff --git a/base/namedtuple.jl b/base/namedtuple.jl index d2d64cbf8e351..eb920f9cbdf73 100644 --- a/base/namedtuple.jl +++ b/base/namedtuple.jl @@ -5,7 +5,7 @@ `NamedTuple`s are, as their name suggests, named [`Tuple`](@ref)s. That is, they're a tuple-like collection of values, where each entry has a unique name, represented as a -`Symbol`. Like `Tuple`s, `NamedTuple`s are immutable; neither the names nor the values +[`Symbol`](@ref). Like `Tuple`s, `NamedTuple`s are immutable; neither the names nor the values can be modified in place after construction. Accessing the value associated with a name in a named tuple can be done using field diff --git a/base/reflection.jl b/base/reflection.jl index d201ecdff72c9..7fa0dfb85cc12 100644 --- a/base/reflection.jl +++ b/base/reflection.jl @@ -5,7 +5,7 @@ """ nameof(m::Module) -> Symbol -Get the name of a `Module` as a `Symbol`. +Get the name of a `Module` as a [`Symbol`](@ref). # Examples ```jldoctest diff --git a/doc/src/base/base.md b/doc/src/base/base.md index 2e057cb142112..205a6708e5e43 100644 --- a/doc/src/base/base.md +++ b/doc/src/base/base.md @@ -84,6 +84,7 @@ primitive type where ... ; += ``` ## Base Modules @@ -203,7 +204,11 @@ Core.Nothing Base.isnothing Base.Some Base.something +Base.Enums.Enum Base.Enums.@enum +Core.Expr +Core.Symbol +Core.Symbol(x...) ``` ## Generic Functions diff --git a/doc/src/base/io-network.md b/doc/src/base/io-network.md index 377ee41c5bf6a..f3f29e623fe21 100644 --- a/doc/src/base/io-network.md +++ b/doc/src/base/io-network.md @@ -7,6 +7,7 @@ Base.stdout Base.stderr Base.stdin Base.open +Base.IOStream Base.IOBuffer Base.take!(::Base.GenericIOBuffer) Base.fdio @@ -94,6 +95,8 @@ Base.Multimedia.displayable Base.show(::Any, ::Any, ::Any) Base.Multimedia.showable Base.repr(::MIME, ::Any) +Base.MIME +Base.@MIME_str ``` As mentioned above, one can also define new display backends. For example, a module that can display diff --git a/doc/src/base/strings.md b/doc/src/base/strings.md index 95e07e3180542..f7bfc665e6079 100644 --- a/doc/src/base/strings.md +++ b/doc/src/base/strings.md @@ -24,6 +24,7 @@ Base.@r_str Base.SubstitutionString Base.@s_str Base.@raw_str +Base.@b_str Base.Docs.@html_str Base.Docs.@text_str Base.isvalid(::Any) @@ -75,7 +76,6 @@ Base.ispunct Base.isspace Base.isuppercase Base.isxdigit -Core.Symbol Base.escape_string Base.unescape_string ``` diff --git a/doc/src/devdocs/ast.md b/doc/src/devdocs/ast.md index f81ccad54c270..b89b4db12b724 100644 --- a/doc/src/devdocs/ast.md +++ b/doc/src/devdocs/ast.md @@ -12,7 +12,7 @@ First we will focus on the AST, since it is needed to write macros. ## Surface syntax AST -Front end ASTs consist almost entirely of `Expr`s and atoms (e.g. symbols, numbers). +Front end ASTs consist almost entirely of [`Expr`](@ref)s and atoms (e.g. symbols, numbers). There is generally a different expression head for each visually distinct syntactic form. Examples will be given in s-expression syntax. Each parenthesized list corresponds to an Expr, where the first element is the head. @@ -287,9 +287,9 @@ The following data types exist in lowered form: Marks a point where a variable (slot) is created. This has the effect of resetting a variable to undefined. -### Expr types +### `Expr` types -These symbols appear in the `head` field of `Expr`s in lowered form. +These symbols appear in the `head` field of [`Expr`](@ref)s in lowered form. * `call` diff --git a/doc/src/devdocs/reflection.md b/doc/src/devdocs/reflection.md index 3e41b146ad09b..350fda7f77df1 100644 --- a/doc/src/devdocs/reflection.md +++ b/doc/src/devdocs/reflection.md @@ -77,7 +77,7 @@ table may be searched for methods accepting a given type using [`methodswith`](@ ## Expansion and lowering As discussed in the [Metaprogramming](@ref) section, the [`macroexpand`](@ref) function gives -the unquoted and interpolated expression (`Expr`) form for a given macro. To use `macroexpand`, +the unquoted and interpolated expression ([`Expr`](@ref)) form for a given macro. To use `macroexpand`, `quote` the expression block itself (otherwise, the macro will be evaluated and the result will be passed instead!). For example: diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md index 4f80dc4e47765..8d12c62c69625 100644 --- a/doc/src/manual/documentation.md +++ b/doc/src/manual/documentation.md @@ -549,7 +549,8 @@ Macro authors should take note that only macros that generate a single expressio support docstrings. If a macro returns a block containing multiple subexpressions then the subexpression that should be documented must be marked using the [`@__doc__`](@ref Core.@__doc__) macro. -The `@enum` macro makes use of `@__doc__` to allow for documenting `Enum`s. Examining its definition +The [`@enum`](@ref) macro makes use of `@__doc__` to allow for documenting [`Enum`](@ref)s. +Examining its definition should serve as an example of how to use `@__doc__` correctly. ```@docs diff --git a/doc/src/manual/metaprogramming.md b/doc/src/manual/metaprogramming.md index 917102cf074bf..f6911cf206184 100644 --- a/doc/src/manual/metaprogramming.md +++ b/doc/src/manual/metaprogramming.md @@ -23,7 +23,7 @@ julia> prog = "1 + 1" **What happens next?** The next step is to [parse](https://en.wikipedia.org/wiki/Parsing#Computer_languages) each string -into an object called an expression, represented by the Julia type `Expr`: +into an object called an expression, represented by the Julia type [`Expr`](@ref): ```jldoctest prog julia> ex1 = Meta.parse(prog) @@ -144,7 +144,7 @@ julia> :(::) ### Quoting The second syntactic purpose of the `:` character is to create expression objects without using -the explicit `Expr` constructor. This is referred to as *quoting*. The `:` character, followed +the explicit [`Expr`](@ref) constructor. This is referred to as *quoting*. The `:` character, followed by paired parentheses around a single statement of Julia code, produces an `Expr` object based on the enclosed code. Here is example of the short form used to quote an arithmetic expression: @@ -198,7 +198,7 @@ Expr ### Interpolation -Direct construction of `Expr` objects with value arguments is powerful, but `Expr` constructors +Direct construction of [`Expr`](@ref) objects with value arguments is powerful, but `Expr` constructors can be tedious compared to "normal" Julia syntax. As an alternative, Julia allows *interpolation* of literals or expressions into quoted expressions. Interpolation is indicated by a prefix `$`. @@ -310,7 +310,7 @@ equivalent of `eval(eval(:x))`. ### QuoteNode -The usual representation of a `quote` form in an AST is an `Expr` with head `:quote`: +The usual representation of a `quote` form in an AST is an [`Expr`](@ref) with head `:quote`: ```jldoctest interp1 julia> dump(Meta.parse(":(1+2)")) @@ -415,7 +415,7 @@ value 1 and the variable `b`. Note the important distinction between the way `a` ### Functions on `Expr`essions As hinted above, one extremely useful feature of Julia is the capability to generate and manipulate -Julia code within Julia itself. We have already seen one example of a function returning `Expr` +Julia code within Julia itself. We have already seen one example of a function returning [`Expr`](@ref) objects: the [`parse`](@ref) function, which takes a string of Julia code and returns the corresponding `Expr`. A function can also take one or more `Expr` objects as arguments, and return another `Expr`. Here is a simple, motivating example: @@ -837,7 +837,7 @@ This kind of manipulation of variables should be used judiciously, but is occasi Getting the hygiene rules correct can be a formidable challenge. Before using a macro, you might want to consider whether a function closure would be sufficient. Another useful strategy is to defer as much work as possible to runtime. -For example, many macros simply wrap their arguments in a QuoteNode or other similar Expr. +For example, many macros simply wrap their arguments in a `QuoteNode` or other similar [`Expr`](@ref). Some examples of this include `@task body` which simply returns `schedule(Task(() -> $body))`, and `@eval expr`, which simply returns `eval(QuoteNode(expr))`. diff --git a/doc/src/manual/networking-and-streams.md b/doc/src/manual/networking-and-streams.md index 272460a680890..e5bd1d0788a27 100644 --- a/doc/src/manual/networking-and-streams.md +++ b/doc/src/manual/networking-and-streams.md @@ -121,7 +121,7 @@ of common properties. ## Working with Files Like many other environments, Julia has an [`open`](@ref) function, which takes a filename and -returns an `IOStream` object that you can use to read and write things from the file. For example, +returns an [`IOStream`](@ref) object that you can use to read and write things from the file. For example, if we have a file, `hello.txt`, whose contents are `Hello, World!`: ```julia-repl diff --git a/stdlib/Distributed/src/clusterserialize.jl b/stdlib/Distributed/src/clusterserialize.jl index 9c0260fc2d83d..cbd799b284072 100644 --- a/stdlib/Distributed/src/clusterserialize.jl +++ b/stdlib/Distributed/src/clusterserialize.jl @@ -251,7 +251,7 @@ end clear!(syms, pids=workers(); mod=Main) Clears global bindings in modules by initializing them to `nothing`. -`syms` should be of type `Symbol` or a collection of `Symbol`s . `pids` and `mod` +`syms` should be of type [`Symbol`](@ref) or a collection of `Symbol`s . `pids` and `mod` identify the processes and the module in which global variables are to be reinitialized. Only those names found to be defined under `mod` are cleared. diff --git a/stdlib/Mmap/src/Mmap.jl b/stdlib/Mmap/src/Mmap.jl index 971f0d37d1d19..206f27aed078b 100644 --- a/stdlib/Mmap/src/Mmap.jl +++ b/stdlib/Mmap/src/Mmap.jl @@ -134,7 +134,7 @@ systems, not Julia). `dims` is a tuple or single [`Integer`](@ref) specifying the size or length of the array. -The file is passed via the stream argument, either as an open `IOStream` or filename string. +The file is passed via the stream argument, either as an open [`IOStream`](@ref) or filename string. When you initialize the stream, use `"r"` for a "read-only" array, and `"w+"` to create a new array used to write values to disk. diff --git a/stdlib/Printf/src/Printf.jl b/stdlib/Printf/src/Printf.jl index 7c56910331d93..0165dd5402274 100644 --- a/stdlib/Printf/src/Printf.jl +++ b/stdlib/Printf/src/Printf.jl @@ -19,7 +19,7 @@ Print `args` using C `printf` style format specification string, with some cavea equally close to the numeric values of two possible output strings, the output string further away from zero is chosen. -Optionally, an `IOStream` +Optionally, an [`IOStream`](@ref) may be passed as the first argument to redirect output. # Examples