a bunch of random doctests (#20608)

* add more doctests

* fixup bugged doctests

* fixup line numbers and printing

* fix indices [ci skip]

* fix type -> mutable struct [ci skip]

Author: KristofferC

base/abstractarray.jl

@@ -301,6 +301,22 @@ if they need to provide custom bounds checking behaviors; however, in
 many cases one can rely on `A`'s indices and [`checkindex`](@ref).
 
 See also [`checkindex`](@ref).
+
+```jldoctest
+julia> A = rand(3, 3);
+
+julia> checkbounds(Bool, A, 2)
+true
+
+julia> checkbounds(Bool, A, 3, 4)
+false
+
+julia> checkbounds(Bool, A, 1:3)
+true
+
+julia> checkbounds(Bool, A, 1:3, 2:4)
+false
+```
 """
 function checkbounds(::Type{Bool}, A::AbstractArray, I...)
     @_inline_meta
@@ -346,6 +362,8 @@ bounds-check for a single dimension of the array.
 There are two important exceptions to the 1-1 rule: linear indexing and
 CartesianIndex{N}, both of which may "consume" more than one element
 of `IA`.
+
+See also [`checkbounds`](@ref).
 """
 function checkbounds_indices(::Type{Bool}, IA::Tuple, I::Tuple)
     @_inline_meta
@@ -443,25 +461,31 @@ default is an `Array{element_type}(dims...)`.
 For example, `similar(1:10, 1, 4)` returns an uninitialized `Array{Int,2}` since ranges are
 neither mutable nor support 2 dimensions:
 
-    julia> similar(1:10, 1, 4)
-    1×4 Array{Int64,2}:
-     4419743872  4374413872  4419743888  0
+```julia
+julia> similar(1:10, 1, 4)
+1×4 Array{Int64,2}:
+ 4419743872  4374413872  4419743888  0
+```
 
 Conversely, `similar(trues(10,10), 2)` returns an uninitialized `BitVector` with two
 elements since `BitArray`s are both mutable and can support 1-dimensional arrays:
 
-    julia> similar(trues(10,10), 2)
-    2-element BitArray{1}:
-     false
-     false
+```julia
+julia> similar(trues(10,10), 2)
+2-element BitArray{1}:
+ false
+ false
+```
 
 Since `BitArray`s can only store elements of type `Bool`, however, if you request a
 different element type it will create a regular `Array` instead:
 
-    julia> similar(falses(10), Float64, 2, 4)
-    2×4 Array{Float64,2}:
-     2.18425e-314  2.18425e-314  2.18425e-314  2.18425e-314
-     2.18425e-314  2.18425e-314  2.18425e-314  2.18425e-314
+```julia
+julia> similar(falses(10), Float64, 2, 4)
+2×4 Array{Float64,2}:
+ 2.18425e-314  2.18425e-314  2.18425e-314  2.18425e-314
+ 2.18425e-314  2.18425e-314  2.18425e-314  2.18425e-314
+```
 
 """
 similar{T}(a::AbstractArray{T})                             = similar(a, T)
@@ -675,6 +699,17 @@ Make a mutable copy of an array or iterable `a`.  For `a::Array`,
 this is equivalent to `copy(a)`, but for other array types it may
 differ depending on the type of `similar(a)`.  For generic iterables
 this is equivalent to `collect(a)`.
+
+```jldoctest
+julia> tup = (1, 2, 3)
+(1, 2, 3)
+
+julia> Base.copymutable(tup)
+3-element Array{Int64,1}:
+ 1
+ 2
+ 3
+```
 """
 function copymutable(a::AbstractArray)
     @_propagate_inbounds_meta
@@ -1629,7 +1664,7 @@ needed, for example in `foreach(println, array)`.
 ```jldoctest
 julia> a = 1:3:7;
 
-julia> foreach(x->println(x^2),a)
+julia> foreach(x -> println(x^2), a)
 1
 16
 49
@@ -1783,7 +1818,7 @@ Transform collection `c` by applying `f` to each element. For multiple collectio
 apply `f` elementwise.
 
 ```jldoctest
-julia> map((x) -> x * 2, [1, 2, 3])
+julia> map(x -> x * 2, [1, 2, 3])
 3-element Array{Int64,1}:
  2
  4
@@ -1823,6 +1858,18 @@ end
 
 Like [`map`](@ref), but stores the result in `destination` rather than a new
 collection. `destination` must be at least as large as the first collection.
+
+```jldoctest
+julia> x = zeros(3);
+
+julia> map!(x -> x * 2, x, [1, 2, 3]);
+
+julia> x
+3-element Array{Float64,1}:
+ 2.0
+ 4.0
+ 6.0
+```
 """
 map!{F}(f::F, dest::AbstractArray, As::AbstractArray...) = map_n!(f, dest, As)
 

base/array.jl

@@ -838,7 +838,8 @@ julia> deleteat!([6, 5, 4, 3, 2, 1], [true, false, true, false, true, false])
 julia> deleteat!([6, 5, 4, 3, 2, 1], (2, 2))
 ERROR: ArgumentError: indices must be unique and sorted
 Stacktrace:
- [1] deleteat!(::Array{Int64,1}, ::Tuple{Int64,Int64}) at ./array.jl:808
+ [1] _deleteat!(::Array{Int64,1}, ::Tuple{Int64,Int64}) at ./array.jl:858
+ [2] deleteat!(::Array{Int64,1}, ::Tuple{Int64,Int64}) at ./array.jl:845
 ```
 """
 deleteat!(a::Vector, inds) = _deleteat!(a, inds)

base/associative.jl

@@ -122,6 +122,20 @@ end
 
 Update collection with pairs from the other collections.
 See also [`merge`](@ref).
+
+```jldoctest
+julia> d1 = Dict(1 => 2, 3 => 4);
+
+julia> d2 = Dict(1 => 4, 4 => 5);
+
+julia> merge!(d1, d2);
+
+julia> d1
+Dict{Int64,Int64} with 3 entries:
+  4 => 5
+  3 => 4
+  1 => 4
+```
 """
 function merge!(d::Associative, others::Associative...)
     for other in others
@@ -145,6 +159,11 @@ end
     keytype(type)
 
 Get the key type of an associative collection type. Behaves similarly to [`eltype`](@ref).
+
+```jldoctest
+julia> keytype(Dict(Int32(1) => "foo"))
+Int32
+```
 """
 keytype{K,V}(::Type{Associative{K,V}}) = K
 keytype(a::Associative) = keytype(typeof(a))
@@ -154,6 +173,11 @@ keytype{A<:Associative}(::Type{A}) = keytype(supertype(A))
     valtype(type)
 
 Get the value type of an associative collection type. Behaves similarly to [`eltype`](@ref).
+
+```jldoctest
+julia> valtype(Dict(Int32(1) => "foo"))
+String
+```
 """
 valtype{K,V}(::Type{Associative{K,V}}) = V
 valtype{A<:Associative}(::Type{A}) = valtype(supertype(A))

base/base64.jl

@@ -21,6 +21,23 @@ Returns a new write-only I/O stream, which converts any bytes written to it into
 base64-encoded ASCII bytes written to `ostream`.
 Calling [`close`](@ref) on the `Base64EncodePipe` stream
 is necessary to complete the encoding (but does not close `ostream`).
+
+```jldoctest
+julia> io = IOBuffer();
+
+julia> iob64_encode = Base64EncodePipe(io);
+
+julia> write(iob64_encode, "Hello!")
+6
+
+julia> close(iob64_encode);
+
+julia> str = String(take!(io))
+"SGVsbG8h"
+
+julia> String(base64decode(str))
+"Hello!"
+```
 """
 mutable struct Base64EncodePipe <: IO
     io::IO
@@ -171,6 +188,8 @@ Given a [`write`](@ref)-like function `writefunc`, which takes an I/O stream as
 string, and returns the string. `base64encode(args...)` is equivalent to `base64encode(write, args...)`:
 it converts its arguments into bytes using the standard [`write`](@ref) functions and returns the
 base64-encoded string.
+
+See also [`base64decode`](@ref).
 """
 function base64encode(f::Function, args...)
     s = IOBuffer()
@@ -187,6 +206,20 @@ base64encode(x...) = base64encode(write, x...)
     Base64DecodePipe(istream)
 
 Returns a new read-only I/O stream, which decodes base64-encoded data read from `istream`.
+
+```jldoctest
+julia> io = IOBuffer();
+
+julia> iob64_decode = Base64DecodePipe(io);
+
+julia> write(io, "SGVsbG8h")
+0x0000000000000008
+
+julia> seekstart(io);
+
+julia> String(read(iob64_decode))
+"Hello!"
+```
 """
 mutable struct Base64DecodePipe <: IO
     io::IO
@@ -225,6 +258,22 @@ close(b::Base64DecodePipe) = nothing
     base64decode(string)
 
 Decodes the base64-encoded `string` and returns a `Vector{UInt8}` of the decoded bytes.
+
+See also [`base64encode`](@ref)
+
+```jldoctest
+julia> b = base64decode("SGVsbG8h")
+6-element Array{UInt8,1}:
+ 0x48
+ 0x65
+ 0x6c
+ 0x6c
+ 0x6f
+ 0x21
+
+julia> String(b)
+"Hello!"
+```
 """
 function base64decode(s)
     b = IOBuffer(s)

base/bool.jl

@@ -26,7 +26,7 @@ false
 julia> !false
 true
 
-julia> ![true false true]
+julia> .![true false true]
 1×3 BitArray{2}:
  false  true  false
 ```

base/cartesian.jl

@@ -13,22 +13,22 @@ export @nloops, @nref, @ncall, @nexprs, @nextract, @nall, @nany, @ntuple, @nif
 
 Generate `N` nested loops, using `itersym` as the prefix for the iteration variables.
 `rangeexpr` may be an anonymous-function expression, or a simple symbol `var` in which case
-the range is `1:size(var,d)` for dimension `d`.
+the range is `indices(var, d)` for dimension `d`.
 
 Optionally, you can provide "pre" and "post" expressions. These get executed first and last,
 respectively, in the body of each loop. For example:
 
-    @nloops 2 i A d->j_d=min(i_d,5) begin
+    @nloops 2 i A d -> j_d = min(i_d, 5) begin
         s += @nref 2 A j
     end
 
 would generate:
 
-    for i_2 = 1:size(A, 2)
+    for i_2 = indices(A, 2)
         j_2 = min(i_2, 5)
-        for i_1 = 1:size(A, 1)
+        for i_1 = indices(A, 1)
             j_1 = min(i_1, 5)
-            s += A[j_1,j_2]
+            s += A[j_1, j_2]
         end
     end
 

base/docs/helpdb/Base.jl

@@ -341,7 +341,7 @@ If `T` does not have a specific size, an error is thrown.
 julia> sizeof(Base.LinAlg.LU)
 ERROR: argument is an abstract type; size is indeterminate
 Stacktrace:
- [1] sizeof(::Type{T} where T) at ./essentials.jl:147
+ [1] sizeof(::Type{T} where T) at ./essentials.jl:160
 ```
 """
 sizeof(::Type)

base/essentials.jl

@@ -215,6 +215,7 @@ end
 Eliminates array bounds checking within expressions.
 
 In the example below the bound check of array A is skipped to improve performance.
+
 ```julia
 function sum(A::AbstractArray)
     r = zero(eltype(A))
@@ -224,6 +225,7 @@ function sum(A::AbstractArray)
     return r
 end
 ```
+
 !!! Warning
 
     Using `@inbounds` may return incorrect results/crashes/corruption
@@ -281,6 +283,25 @@ getindex(v::SimpleVector, I::AbstractArray) = Core.svec(Any[ v[i] for i in I ]..
 
 Tests whether the given array has a value associated with index `i`. Returns `false`
 if the index is out of bounds, or has an undefined reference.
+
+```jldoctest
+julia> isassigned(rand(3, 3), 5)
+true
+
+julia> isassigned(rand(3, 3), 3 * 3 + 1)
+false
+
+julia> mutable struct Foo end
+
+julia> v = similar(rand(3), Foo)
+3-element Array{Foo,1}:
+ #undef
+ #undef
+ #undef
+
+julia> isassigned(v, 1)
+false
+```
 """
 function isassigned end
 

base/expr.jl

@@ -117,6 +117,7 @@ Small functions typically do not need the `@inline` annotation,
 as the compiler does it automatically. By using `@inline` on bigger functions,
 an extra nudge can be given to the compiler to inline it.
 This is shown in the following example:
+
 ```julia
 @inline function bigfunction(x)
     #=
@@ -137,6 +138,7 @@ Prevents the compiler from inlining a function.
 Small functions are typically inlined automatically.
 By using `@noinline` on small functions, auto-inlining can be
 prevented. This is shown in the following example:
+
 ```julia
 @noinline function smallfunction(x)
     #=

base/int.jl

@@ -94,6 +94,17 @@ resulting in the return of a negative value. This overflow occurs only
 when `abs` is applied to the minimum representable value of a signed
 integer. That is, when `x == typemin(typeof(x))`, `abs(x) == x < 0`,
 not `-x` as might be expected.
+
+```jldoctest
+julia> abs(-3)
+3
+
+julia> abs(1 + im)
+1.4142135623730951
+
+julia> abs(typemin(Int64))
+-9223372036854775808
+```
 """
 function abs end