doc: misc updates (#30837)

* include docstrings from #30716, #30745 and #30747
in the manual, and misc cross references.

* fix doctest for =

base/docs/basedocs.jl

@@ -249,7 +249,7 @@ julia> a, b
 Assignment can operate on multiple variables in series, and will return the value of the right-hand-most expression:
 ```jldoctest
 julia> a = [1]; b = [2]; c = [3]; a = b = c
-1-element Array{Int64,1}
+1-element Array{Int64,1}:
  3
 
 julia> b[1] = 2; a, b, c
@@ -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

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.
 """

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.
 """

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...`.
 

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

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

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

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

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
 ```

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`
 

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:
 

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

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))`.
 

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

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.
 

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.
 

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