Merge pull request #31039 from JuliaLang/backport-1.1.1

Backports for 1.1.1

base/Enums.jl

@@ -7,6 +7,11 @@ export Enum, @enum
 
 function basetype end
 
+"""
+    Enum{T<:Integer}
+
+The abstract supertype of all enumerated types defined with [`@enum`](@ref).
+"""
 abstract type Enum{T<:Integer} end
 
 (::Type{T})(x::Enum{T2}) where {T<:Integer,T2<:Integer} = T(bitcast(T2, x))::T

base/arrayshow.jl

@@ -434,10 +434,11 @@ function show_vector(io::IO, v, opn='[', cls=']')
     io = IOContext(io, :typeinfo => eltype(v), :compact => get(io, :compact, true))
     limited = get(io, :limit, false)
     if limited && length(v) > 20
-        inds = axes1(v)
-        show_delim_array(io, v, opn, ",", "", false, inds[1], inds[1]+9)
+        axs1 = axes1(v)
+        f, l = first(axs1), last(axs1)
+        show_delim_array(io, v, opn, ",", "", false, f, f+9)
         print(io, "  …  ")
-        show_delim_array(io, v, "", ",", cls, false, inds[end-9], inds[end])
+        show_delim_array(io, v, "", ",", cls, false, l-9, l)
     else
         show_delim_array(io, v, opn, ",", cls, false)
     end

base/compiler/abstractinterpretation.jl

@@ -910,7 +910,7 @@ function abstract_eval(@nospecialize(e), vtypes::VarTable, sv::InferenceState)
                     isconst = false
                 end
             end
-            if isconst
+            if isconst && fieldcount(t) == length(e.args) - 1
                 t = Const(ccall(:jl_new_structv, Any, (Any, Ptr{Cvoid}, UInt32), t, args, length(args)))
             end
         end

base/deepcopy.jl

@@ -27,7 +27,7 @@ updated as appropriate before returning.
 """
 deepcopy(x) = deepcopy_internal(x, IdDict())::typeof(x)
 
-deepcopy_internal(x::Union{Symbol,Core.MethodInstance,Method,GlobalRef,DataType,Union,Task},
+deepcopy_internal(x::Union{Symbol,Core.MethodInstance,Method,GlobalRef,DataType,Union,UnionAll,Task},
                   stackdict::IdDict) = x
 deepcopy_internal(x::Tuple, stackdict::IdDict) =
     ntuple(i->deepcopy_internal(x[i], stackdict), length(x))

base/docs/basedocs.jl

@@ -129,10 +129,13 @@ kw"primitive type"
 """
     macro
 
-`macro` defines a method to include generated code in the final body of a program. A
-macro maps a tuple of arguments to a returned expression, and the resulting expression
-is compiled directly rather than requiring a runtime `eval` call. Macro arguments may
-include expressions, literal values, and symbols. For example:
+`macro` defines a method for inserting generated code into a program.
+A macro maps a sequence of argument expressions to a returned expression, and the
+resulting expression is substituted directly into the program at the point where
+the macro is invoked.
+Macros are a way to run generated code without calling `eval`, since the generated
+code instead simply becomes part of the surrounding program.
+Macro arguments may include expressions, literal values, and symbols.
 
 # Examples
 ```jldoctest
@@ -197,6 +200,91 @@ julia> z
 """
 kw"global"
 
+"""
+    =
+
+`=` is the assignment operator.
+* For variable `a` and expression `b`, `a = b` makes `a` refer to the value of `b`.
+* For functions `f(x)`, `f(x) = x` defines a new function constant `f`, or adds a new method to `f` if `f` is already defined; this usage is equivalent to `function f(x); x; end`.
+* `a[i] = v` calls [`setindex!`](@ref)`(a,v,i)`.
+* `a.b = c` calls [`setproperty!`](@ref)`(a,:b,c)`.
+* Inside a function call, `f(a=b)` passes `b` as the value of keyword argument `a`.
+* Inside parentheses with commas, `(a=1,)` constructs a [`NamedTuple`](@ref).
+
+# Examples
+Assigning `a` to `b` does not create a copy of `b`; instead use [`copy`](@ref) or [`deepcopy`](@ref).
+
+```jldoctest
+julia> b = [1]; a = b; b[1] = 2; a
+1-element Array{Int64,1}:
+ 2
+
+julia> b = [1]; a = copy(b); b[1] = 2; a
+1-element Array{Int64,1}:
+ 1
+
+```
+Collections passed to functions are also not copied. Functions can modify (mutate) the contents of the objects their arguments refer to. (The names of functions which do this are conventionally suffixed with '!'.)
+```jldoctest
+julia> function f!(x); x[:] .+= 1; end
+f! (generic function with 1 method)
+
+julia> a = [1]; f!(a); a
+1-element Array{Int64,1}:
+ 2
+
+```
+Assignment can operate on multiple variables in parallel, taking values from an iterable:
+```jldoctest
+julia> a, b = 4, 5
+(4, 5)
+
+julia> a, b = 1:3
+1:3
+
+julia> a, b
+(1, 2)
+
+```
+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}
+ 3
+
+julia> b[1] = 2; a, b, c
+([2], [2], [2])
+
+```
+Assignment at out-of-bounds indices does not grow a collection. If the collection is a [`Vector`](@ref) it can instead be grown with [`push!`](@ref) or [`append!`](@ref).
+```jldoctest
+julia> a = [1, 1]; a[3] = 2
+ERROR: BoundsError: attempt to access 2-element Array{Int64,1} at index [3]
+[...]
+
+julia> push!(a, 2, 3)
+4-element Array{Int64,1}:
+ 1
+ 1
+ 2
+ 3
+
+```
+Assigning `[]` does not eliminate elements from a collection; instead use `filter!`.
+```jldoctest
+julia> a = collect(1:3); a[a .<= 1] = []
+ERROR: DimensionMismatch("tried to assign 0 elements to 1 destinations")
+[...]
+
+julia> filter!(x -> x > 1, a) # in-place & thus more efficient than a = a[a .> 1]
+2-element Array{Int64,1}:
+ 2
+ 3
+
+```
+"""
+kw"="
+
 """
     let
 
@@ -237,6 +325,34 @@ For other purposes, `:( ... )` and `quote .. end` blocks are treated identically
 """
 kw"quote"
 
+"""
+    Expr(head::Symbol, args...)
+
+A type representing compound expressions in parsed julia code (ASTs).
+Each expression consists of a `head` Symbol identifying which kind of
+expression it is (e.g. a call, for loop, conditional statement, etc.),
+and subexpressions (e.g. the arguments of a call).
+The subexpressions are stored in a `Vector{Any}` field called `args`.
+
+See the manual chapter on [Metaprogramming](@ref) and the developer
+documentation [Julia ASTs](@ref).
+
+# Examples
+```jldoctest
+julia> Expr(:call, :+, 1, 2)
+:(1 + 2)
+
+julia> dump(:(a ? b : c))
+Expr
+  head: Symbol if
+  args: Array{Any}((3,))
+    1: Symbol a
+    2: Symbol b
+    3: Symbol c
+```
+"""
+Expr
+
 """
     '
 
@@ -314,7 +430,9 @@ kw"function"
 """
     return
 
-`return` can be used in function bodies to exit early and return a given value, e.g.
+`return x` causes the enclosing function to exit early, passing the given value `x`
+back to its caller. `return` by itself with no value is equivalent to `return nothing`
+(see [`nothing`](@ref)).
 
 ```julia
 function compare(a, b)
@@ -340,12 +458,15 @@ function test2(xs)
     end
 end
 ```
-In the first example, the return breaks out of its enclosing function as soon as it hits
+In the first example, the return breaks out of `test1` as soon as it hits
 an even number, so `test1([5,6,7])` returns `12`.
 
 You might expect the second example to behave the same way, but in fact the `return`
 there only breaks out of the *inner* function (inside the `do` block) and gives a value
 back to `map`. `test2([5,6,7])` then returns `[5,12,7]`.
+
+When used in a top-level expression (i.e. outside any function), `return` causes
+the entire current top-level expression to terminate early.
 """
 kw"return"
 
@@ -376,7 +497,7 @@ kw"if", kw"elseif", kw"else"
 """
     for
 
-`for` loops repeatedly evaluate the body of the loop by
+`for` loops repeatedly evaluate a block of statements while
 iterating over a sequence of values.
 
 # Examples
@@ -394,8 +515,8 @@ kw"for"
 """
     while
 
-`while` loops repeatedly evaluate a conditional expression, and continues evaluating the
-body of the while loop so long as the expression remains `true`. If the condition
+`while` loops repeatedly evaluate a conditional expression, and continue evaluating the
+body of the while loop as long as the expression remains true. If the condition
 expression is false when the while loop is first reached, the body is never evaluated.
 
 # Examples
@@ -442,19 +563,23 @@ kw"end"
 """
     try/catch
 
-A `try`/`catch` statement allows for `Exception`s to be tested for. For example, a
-customized square root function can be written to automatically call either the real or
-complex square root method on demand using `Exception`s:
+A `try`/`catch` statement allows intercepting errors (exceptions) thrown
+by [`throw`](@ref) so that program execution can continue.
+For example, the following code attempts to write a file, but warns the user
+and proceeds instead of terminating execution if the file cannot be written:
 
 ```julia
-f(x) = try
-    sqrt(x)
+try
+    open("/danger", "w") do f
+        println(f, "Hello")
+    end
 catch
-    sqrt(complex(x, 0))
+    @warn "Could not write file."
 end
 ```
 
-`try`/`catch` statements also allow the `Exception` to be saved in a variable, e.g. `catch y`.
+The syntax `catch e` (where `e` is any variable) assigns the thrown
+exception object to the given variable within the `catch` block.
 
 The power of the `try`/`catch` construct lies in the ability to unwind a deeply
 nested computation immediately to a much higher level in the stack of calling functions.
@@ -530,7 +655,9 @@ kw"continue"
 """
     do
 
-Create an anonymous function. For example:
+Create an anonymous function and pass it as the first argument to
+a function call.
+For example:
 
 ```julia
 map(1:10) do x
@@ -811,7 +938,7 @@ nothing
 """
     Core.TypeofBottom
 
-The singleton type containing only the value `Union{}`.
+The singleton type containing only the value `Union{}` (which represents the empty type).
 """
 Core.TypeofBottom
 
@@ -1215,7 +1342,7 @@ Unsigned
 """
     Bool <: Integer
 
-Boolean type.
+Boolean type, containing the values `true` and `false`.
 """
 Bool
 
@@ -1248,10 +1375,41 @@ for bit in (8, 16, 32, 64, 128)
     end
 end
 
+"""
+    Symbol
+
+The type of object used to represent identifiers in parsed julia code (ASTs).
+Also often used as a name or label to identify an entity (e.g. as a dictionary key).
+`Symbol`s can be entered using the `:` quote operator:
+```jldoctest
+julia> :name
+:name
+
+julia> typeof(:name)
+Symbol
+
+julia> x = 42
+42
+
+julia> eval(:x)
+42
+```
+`Symbol`s can also be constructed from strings or other values by calling the
+constructor `Symbol(x...)`.
+
+`Symbol`s are immutable and should be compared using `===`.
+The implementation re-uses the same object for all `Symbol`s with the same name,
+so comparison tends to be efficient (it can just compare pointers).
+
+Unlike strings, `Symbol`s are "atomic" or "scalar" entities that do not support
+iteration over characters.
+"""
+Symbol
+
 """
     Symbol(x...) -> Symbol
 
-Create a `Symbol` by concatenating the string representations of the arguments together.
+Create a [`Symbol`](@ref) by concatenating the string representations of the arguments together.
 
 # Examples
 ```jldoctest
@@ -1262,7 +1420,7 @@ julia> Symbol("day", 4)
 :day4
 ```
 """
-Symbol
+Symbol(x...)
 
 """
     tuple(xs...)
@@ -1351,9 +1509,11 @@ typeof
     isdefined(object, s::Symbol)
     isdefined(object, index::Int)
 
-Tests whether an assignable location is defined. The arguments can be a module and a symbol
+Tests whether a global variable or object field is defined. The arguments can be a module and a symbol
 or a composite object and field name (as a symbol) or index.
 
+To test whether an array element is defined, use [`isassigned`](@ref) instead.
+
 # Examples
 ```jldoctest
 julia> isdefined(Base, :sum)

base/floatfuncs.jl

@@ -231,7 +231,8 @@ the square root of [`eps`](@ref) of the type of `x` or `y`, whichever is bigger
 This corresponds to requiring equality of about half of the significand digits. Otherwise,
 e.g. for integer arguments or if an `atol > 0` is supplied, `rtol` defaults to zero.
 
-`x` and `y` may also be arrays of numbers, in which case `norm` defaults to `vecnorm` but
+`x` and `y` may also be arrays of numbers, in which case `norm` defaults to the usual
+`norm` function in LinearAlgebra, but
 may be changed by passing a `norm::Function` keyword argument. (For numbers, `norm` is the
 same thing as `abs`.) When `x` and `y` are arrays, if `norm(x-y)` is not finite (i.e. `±Inf`
 or `NaN`), the comparison falls back to checking whether all elements of `x` and `y` are

base/iostream.jl

@@ -4,6 +4,12 @@
 
 const sizeof_ios_t = Int(ccall(:jl_sizeof_ios_t, Cint, ()))
 
+"""
+    IOStream
+
+A buffered IO stream wrapping an OS file descriptor.
+Mostly used to represent files returned by [`open`](@ref).
+"""
 mutable struct IOStream <: IO
     handle::Ptr{Cvoid}
     ios::Array{UInt8,1}