WIP: [DOC] Fix some doctest errors (#23331)

* [DOC] Fix some doctest errors

Running `make -C doc checks` gives a bunch of warnings and errors. This
removes some of them.

* Fix doctest error in base/channels.jl

* [DOC] Fix more doctest errors

* [DOC] Fix broken link in the manual

* [DOC] Clarify that redefining built-in is not recommended

* Fix more doctest errors

base/channels.jl

@@ -196,8 +196,8 @@ julia> take!(c)
 julia> put!(c,1);
 ERROR: foo
 Stacktrace:
- [1] check_channel_state(::Channel{Any}) at ./channels.jl:131
- [2] put!(::Channel{Any}, ::Int64) at ./channels.jl:261
+ [1] check_channel_state at ./channels.jl:132 [inlined]
+ [2] put!(::Channel{Any}, ::Int64) at ./channels.jl:263
 ```
 """
 function bind(c::Channel, task::Task)

base/docs/basedocs.jl

@@ -808,19 +808,19 @@ julia> A = ones(7);
 julia> A[8]
 ERROR: BoundsError: attempt to access 7-element Array{Float64,1} at index [8]
 Stacktrace:
- [1] getindex(::Array{Float64,1}, ::Int64) at ./array.jl:586
+ [1] getindex(::Array{Float64,1}, ::Int64) at ./array.jl:763
 
 julia> B = ones(2, 3);
 
 julia> B[2, 4]
 ERROR: BoundsError: attempt to access 2×3 Array{Float64,2} at index [2, 4]
 Stacktrace:
- [1] getindex(::Array{Float64,2}, ::Int64, ::Int64) at ./array.jl:587
+ [1] getindex(::Array{Float64,2}, ::Int64, ::Int64) at ./array.jl:764
 
 julia> B[9]
 ERROR: BoundsError: attempt to access 2×3 Array{Float64,2} at index [9]
 Stacktrace:
- [1] getindex(::Array{Float64,2}, ::Int64) at ./array.jl:586
+ [1] getindex(::Array{Float64,2}, ::Int64) at ./array.jl:763
 ```
 """
 BoundsError
@@ -982,7 +982,7 @@ Inf
 julia> div(2, 0)
 ERROR: DivideError: integer division error
 Stacktrace:
- [1] div(::Int64, ::Int64) at ./int.jl:183
+ [1] div(::Int64, ::Int64) at ./int.jl:220
 ```
 """
 DivideError

base/essentials.jl

@@ -78,7 +78,7 @@ julia> convert(Int, 3.0)
 julia> convert(Int, 3.5)
 ERROR: InexactError: convert(Int64, 3.5)
 Stacktrace:
- [1] convert(::Type{Int64}, ::Float64) at ./float.jl:680
+ [1] convert(::Type{Int64}, ::Float64) at ./float.jl:701
 ```
 
 If `T` is a [`AbstractFloat`](@ref) or [`Rational`](@ref) type,
@@ -361,7 +361,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:150
+ [1] sizeof(::Type{T} where T) at ./essentials.jl:367
 ```
 """
 sizeof(x) = Core.sizeof(x)

base/nullable.jl

@@ -13,7 +13,7 @@ Nullable{Int64}()
 julia> get(a)
 ERROR: NullException()
 Stacktrace:
- [1] get(::Nullable{Int64}) at ./nullable.jl:92
+ [1] get(::Nullable{Int64}) at ./nullable.jl:118
 ```
 """
 struct NullException <: Exception
@@ -140,7 +140,7 @@ Nullable{String}()
 julia> unsafe_get(x)
 ERROR: UndefRefError: access to undefined reference
 Stacktrace:
- [1] unsafe_get(::Nullable{String}) at ./nullable.jl:136
+ [1] unsafe_get(::Nullable{String}) at ./nullable.jl:152
 
 julia> x = 1
 1

base/number.jl

@@ -306,8 +306,10 @@ julia> factorial(6)
 720
 
 julia> factorial(21)
-ERROR: OverflowError()
-[...]
+ERROR: OverflowError: 21 is too large to look up in the table
+Stacktrace:
+ [1] factorial_lookup at ./combinatorics.jl:19 [inlined]
+ [2] factorial(::Int64) at ./combinatorics.jl:27
 
 julia> factorial(21.0)
 5.109094217170944e19

base/test.jl

@@ -1140,7 +1140,7 @@ Body:
 julia> @inferred f(1,2,3)
 ERROR: return type Int64 does not match inferred return type Union{Float64, Int64}
 Stacktrace:
- [1] error(::String) at ./error.jl:21
+ [1] error(::String) at ./error.jl:33
 
 julia> @inferred max(1,2)
 2

doc/src/devdocs/types.md

@@ -28,7 +28,7 @@ julia> typeintersect(Int, Float64)
 Union{}
 
 julia> Union{Int, Float64}
-Union{Float64, Int64}
+Union{Int64, Float64}
 
 julia> typejoin(Int, Float64)
 Real

doc/src/manual/arrays.md

@@ -600,8 +600,8 @@ it also handles tuples and treats any argument that is not an array, tuple or `R
 ```jldoctest
 julia> convert.(Float32, [1, 2])
 2-element Array{Float32,1}:
- 1.0
- 2.0
+ 1.0f0
+ 2.0f0
 
 julia> ceil.((UInt8,), [1.2 3.4; 5.6 6.7])
 2×2 Array{UInt8,2}:

doc/src/manual/dates.md

@@ -350,7 +350,7 @@ little as possible when doing [`Period`](@ref) arithmetic. This approach is also
 *calendrical* arithmetic or what you would probably guess if someone were to ask you the same
 calculation in a conversation. Why all the fuss about this? Let's take a classic example: add
 1 month to January 31st, 2014. What's the answer? Javascript will say [March 3](http:https://www.markhneedham.com/blog/2009/01/07/javascript-add-a-month-to-a-date/)
-(assumes 31 days). PHP says [March 2](http:https://stackoverflow.com/questions/5760262/php-adding-months-to-a-date-while-not-exceeding-the-last-day-of-the-month)
+(assumes 31 days). PHP says [March 2](https:https://stackoverflow.com/questions/5760262/php-adding-months-to-a-date-while-not-exceeding-the-last-day-of-the-month)
 (assumes 30 days). The fact is, there is no right answer. In the `Dates` module, it gives
 the result of February 28th. How does it figure that out? I like to think of the classic 7-7-7
 gambling game in casinos.

doc/src/manual/faq.md

@@ -235,10 +235,10 @@ ERROR: DomainError with -5:
 Cannot raise an integer x to a negative power -5.
 Make x a float by adding a zero decimal (e.g., 2.0^-5 instead of 2^-5), or write 1/x^5, float(x)^-5, or (x//1)^-5
 Stacktrace:
- [1] throw_domerr_powbysq(::Int64) at ./intfuncs.jl:163
- [2] power_by_squaring at ./intfuncs.jl:178 [inlined]
- [3] ^ at ./intfuncs.jl:202 [inlined]
- [4] literal_pow(::Base.#^, ::Int64, ::Val{-5}) at ./intfuncs.jl:213
+ [1] throw_domerr_powbysq(::Int64) at ./intfuncs.jl:164
+ [2] power_by_squaring at ./intfuncs.jl:179 [inlined]
+ [3] ^ at ./intfuncs.jl:203 [inlined]
+ [4] literal_pow(::Base.#^, ::Int64, ::Val{-5}) at ./intfuncs.jl:214
 ```
 
 This behavior is an inconvenient consequence of the requirement for type-stability. In the case

doc/src/manual/networking-and-streams.md

@@ -226,8 +226,8 @@ Base.PipeServer(active)
 Note that the return type of the last invocation is different. This is because this server does not
 listen on TCP, but rather on a named pipe (Windows) or UNIX domain socket. Also note that Windows
 named pipe format has to be a specific pattern such that the name prefix (`\\.\pipe\`) uniquely
-identifies the [file type](https://msdn.microsoft.com/en-
-us/library/windows/desktop/aa365783(v=vs.85).aspx). The difference between TCP and named pipes or
+identifies the [file type](https://msdn.microsoft.com/en-us/library/windows/desktop/aa365783(v=vs.85).aspx).
+The difference between TCP and named pipes or
 UNIX domain sockets is subtle and has to do with the [`accept()`](@ref) and [`connect()`](@ref)
 methods. The [`accept()`](@ref) method retrieves a connection to the client that is connecting on
 the server we just created, while the [`connect()`](@ref) function connects to a server using the

doc/src/manual/noteworthy-differences.md

@@ -140,7 +140,7 @@ For users coming to Julia from R, these are some noteworthy differences:
  * Julia cannot assign to the results of function calls on the left hand side of an assignment operation:
  you cannot write `diag(M) = ones(n)`.
  * Julia discourages populating the main namespace with functions. Most statistical functionality
- for Julia is found in [packages](http:https://pkg.julialang.org/) under the [JuliaStats organization](https://github.com/JuliaStats).
+ for Julia is found in [packages](https:https://pkg.julialang.org/) under the [JuliaStats organization](https://github.com/JuliaStats).
  For example:
 
  * Functions pertaining to probability distributions are provided by the [Distributions package](https://github.com/JuliaStats/Distributions.jl).

doc/src/manual/strings.md

@@ -648,7 +648,7 @@ julia> m.match
 "acd"
 
 julia> m.captures
-3-element Array{Union{SubString{String}, Void},1}:
+3-element Array{Union{Void, SubString{String}},1}:
  "a"
  "c"
  "d"
@@ -669,7 +669,7 @@ julia> m.match
 "ad"
 
 julia> m.captures
-3-element Array{Union{SubString{String}, Void},1}:
+3-element Array{Union{Void, SubString{String}},1}:
  "a"
  nothing
  "d"

doc/src/manual/types.md

@@ -69,7 +69,7 @@ an exception is thrown, otherwise, the left-hand value is returned:
 
 ```jldoctest
 julia> (1+2)::AbstractFloat
-ERROR: TypeError: typeassert: expected AbstractFloat, got Int64
+ERROR: TypeError: in typeassert, expected AbstractFloat, got Int64
 
 julia> (1+2)::Int
 3
@@ -345,7 +345,7 @@ must be convertible to `Int`:
 julia> Foo((), 23.5, 1)
 ERROR: InexactError: convert(Int64, 23.5)
 Stacktrace:
- [1] convert at ./float.jl:681 [inlined]
+ [1] convert at ./float.jl:701 [inlined]
  [2] Foo(::Tuple{}, ::Float64, ::Int64) at ./none:2
 ```
 
@@ -483,7 +483,7 @@ argument types, constructed using the special `Union` function:
 
 ```jldoctest
 julia> IntOrString = Union{Int,AbstractString}
-Union{AbstractString, Int64}
+Union{Int64, AbstractString}
 
 julia> 1 :: IntOrString
 1
@@ -492,7 +492,7 @@ julia> "Hello!" :: IntOrString
 "Hello!"
 
 julia> 1.0 :: IntOrString
-ERROR: TypeError: typeassert: expected Union{AbstractString, Int64}, got Float64
+ERROR: TypeError: in typeassert, expected Union{Int64, AbstractString}, got Float64
 ```
 
 The compilers for many languages have an internal union construct for reasoning about types; Julia
@@ -651,7 +651,7 @@ ERROR: MethodError: Cannot `convert` an object of type Float64 to an object of t
 This may have arisen from a call to the constructor Point{Float64}(...),
 since type constructors fall back to convert methods.
 Stacktrace:
- [1] Point{Float64}(::Float64) at ./sysimg.jl:102
+ [1] Point{Float64}(::Float64) at ./sysimg.jl:103
 
 julia> Point{Float64}(1.0,2.0,3.0)
 ERROR: MethodError: no method matching Point{Float64}(::Float64, ::Float64, ::Float64)
@@ -801,10 +801,10 @@ julia> Pointy{Real}
 Pointy{Real}
 
 julia> Pointy{AbstractString}
-ERROR: TypeError: Pointy: in T, expected T<:Real, got Type{AbstractString}
+ERROR: TypeError: in Pointy, in T, expected T<:Real, got Type{AbstractString}
 
 julia> Pointy{1}
-ERROR: TypeError: Pointy: in T, expected T<:Real, got Int64
+ERROR: TypeError: in Pointy, in T, expected T<:Real, got Int64
 ```
 
 Type parameters for parametric composite types can be restricted in the same manner:
@@ -1163,8 +1163,8 @@ is raised:
 julia> supertype(Union{Float64,Int64})
 ERROR: MethodError: no method matching supertype(::Type{Union{Float64, Int64}})
 Closest candidates are:
- supertype(!Matched::DataType) at operators.jl:41
- supertype(!Matched::UnionAll) at operators.jl:46
+ supertype(!Matched::DataType) at operators.jl:42
+ supertype(!Matched::UnionAll) at operators.jl:47
 ```
 
 ## Custom pretty-printing
@@ -1423,7 +1423,7 @@ You can safely access the value of a `Nullable` object using [`get()`](@ref):
 julia> get(Nullable{Float64}())
 ERROR: NullException()
 Stacktrace:
- [1] get(::Nullable{Float64}) at ./nullable.jl:92
+ [1] get(::Nullable{Float64}) at ./nullable.jl:118
 
 julia> get(Nullable(1.0))
 1.0

doc/src/manual/variables.md

@@ -59,29 +59,37 @@ name `δ` can be entered by typing `\delta`-*tab*, or even `α̂₂` by `\alpha`
 that you don't know how to type, the REPL help will tell you: just type `?` and
 then paste the symbol.)
 
-Julia will even let you redefine built-in constants and functions if needed:
+Julia will even let you redefine built-in constants and functions if needed (although
+this is not recommended to avoid potential confusions):
 
 ```jldoctest
-julia> pi
-π = 3.1415926535897...
-
 julia> pi = 3
-WARNING: imported binding for pi overwritten in module Main
 3
 
 julia> pi
 3
 
+julia> sqrt = 4
+4
+```
+
+However, if you try to redefine a built-in constant or function already in use, Julia will give
+you an error:
+
+```jldoctest
+julia> pi
+π = 3.1415926535897...
+
+julia> pi = 3
+ERROR: cannot assign variable Base.pi from module Main
+
 julia> sqrt(100)
 10.0
 
 julia> sqrt = 4
-WARNING: imported binding for sqrt overwritten in module Main
-4
+ERROR: cannot assign variable Base.sqrt from module Main
 ```
 
-However, this is obviously not recommended to avoid potential confusion.
-
 ## Allowed Variable Names
 
 Variable names must begin with a letter (A-Z or a-z), underscore, or a subset of Unicode code