purge doctest stacktraces (#23988)

* remove some noninformational stacktraces in doctests * add description for hiding parts of doctest * add back "Stacktrace"
JuliaLang · Oct 6, 2017 · b76c24e · b76c24e
1 parent 7504a38
commit b76c24e
Show file tree

Hide file tree

Showing 28 changed files with 52 additions and 58 deletions.
diff --git a/base/array.jl b/base/array.jl
@@ -1264,8 +1264,7 @@ 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:926
- [2] deleteat!(::Array{Int64,1}, ::Tuple{Int64,Int64}) at ./array.jl:913
+[...]
 ```
 """
 deleteat!(a::Vector, inds) = _deleteat!(a, inds)

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

diff --git a/base/dict.jl b/base/dict.jl
@@ -640,7 +640,7 @@ julia> pop!(d, "a")
 julia> pop!(d, "d")
 ERROR: KeyError: key "d" not found
 Stacktrace:
- [1] pop!(::Dict{String,Int64}, ::String) at ./dict.jl:539
+[...]
 
 julia> pop!(d, "e", 4)
 4

diff --git a/base/docs/basedocs.jl b/base/docs/basedocs.jl
@@ -962,9 +962,7 @@ julia> sqrt(-1)
 ERROR: DomainError with -1.0:
 sqrt will only return a complex result if called with a complex argument. Try sqrt(Complex(x)).
 Stacktrace:
- [1] throw_complex_domainerror(::Symbol, ::Float64) at ./math.jl:31
- [2] sqrt at ./math.jl:462 [inlined]
- [3] sqrt(::Int64) at ./math.jl:472
+[...]
 ```
 """
 DomainError
@@ -1092,7 +1090,7 @@ Inf
 julia> div(2, 0)
 ERROR: DivideError: integer division error
 Stacktrace:
- [1] div(::Int64, ::Int64) at ./int.jl:220
+[...]
 ```
 """
 DivideError

diff --git a/base/essentials.jl b/base/essentials.jl
@@ -369,7 +369,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:367
+[...]
 ```
 """
 sizeof(x) = Core.sizeof(x)

diff --git a/base/linalg/eigen.jl b/base/linalg/eigen.jl
@@ -225,8 +225,7 @@ julia> eigmax(A)
 ERROR: DomainError with Complex{Int64}[0+0im 0+1im; -1+0im 0+0im]:
 `A` cannot have complex eigenvalues.
 Stacktrace:
- [1] #eigmax#52(::Bool, ::Bool, ::Function, ::Array{Complex{Int64},2}) at ./linalg/eigen.jl:238
- [2] eigmax(::Array{Complex{Int64},2}) at ./linalg/eigen.jl:236
+[...]
 ```
 """
 function eigmax(A::Union{Number, StridedMatrix}; permute::Bool=true, scale::Bool=true)
@@ -267,8 +266,7 @@ julia> eigmin(A)
 ERROR: DomainError with Complex{Int64}[0+0im 0+1im; -1+0im 0+0im]:
 `A` cannot have complex eigenvalues.
 Stacktrace:
- [1] #eigmin#53(::Bool, ::Bool, ::Function, ::Array{Complex{Int64},2}) at ./linalg/eigen.jl:280
- [2] eigmin(::Array{Complex{Int64},2}) at ./linalg/eigen.jl:278
+[...]
 ```
 """
 function eigmin(A::Union{Number, StridedMatrix}; permute::Bool=true, scale::Bool=true)

diff --git a/base/linalg/qr.jl b/base/linalg/qr.jl
@@ -228,12 +228,7 @@ julia> a = [1 2; 3 4]
 julia> qrfact!(a)
 ERROR: InexactError: convert(Int64, -3.1622776601683795)
 Stacktrace:
- [1] convert at ./float.jl:703 [inlined]
- [2] setindex! at ./array.jl:806 [inlined]
- [3] setindex! at ./subarray.jl:245 [inlined]
- [4] reflector! at ./linalg/generic.jl:1196 [inlined]
- [5] qrfactUnblocked!(::Array{Int64,2}) at ./linalg/qr.jl:141
- [6] qrfact!(::Array{Int64,2}) at ./linalg/qr.jl:213
+[...]
 ```
 """
 qrfact!(A::StridedMatrix, ::Val{false}) = qrfactUnblocked!(A)

diff --git a/base/math.jl b/base/math.jl
@@ -489,9 +489,7 @@ julia> √(a^2 + a^2) # a^2 overflows
 ERROR: DomainError with -2.914184810805068e18:
 sqrt will only return a complex result if called with a complex argument. Try sqrt(Complex(x)).
 Stacktrace:
- [1] throw_complex_domainerror(::Symbol, ::Float64) at ./math.jl:31
- [2] sqrt at ./math.jl:462 [inlined]
- [3] sqrt(::Int64) at ./math.jl:472
+[...]
 ```
 """
 hypot(x::Number, y::Number) = hypot(promote(x, y)...)

diff --git a/base/nullable.jl b/base/nullable.jl
@@ -13,7 +13,7 @@ Nullable{Int64}()
 julia> get(a)
 ERROR: NullException()
 Stacktrace:
- [1] get(::Nullable{Int64}) at ./nullable.jl:118
+[...]
 ```
 """
 struct NullException <: Exception
@@ -104,7 +104,7 @@ julia> get(Nullable(5))
 julia> get(Nullable())
 ERROR: NullException()
 Stacktrace:
- [1] get(::Nullable{Union{}}) at ./nullable.jl:102
+[...]
 ```
 """
 @inline function get(x::Nullable{T}, y) where T
@@ -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:152
+[...]
 
 julia> x = 1
 1

diff --git a/base/number.jl b/base/number.jl
@@ -309,8 +309,7 @@ julia> factorial(6)
 julia> factorial(21)
 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

diff --git a/base/operators.jl b/base/operators.jl
@@ -334,6 +334,7 @@ julia> cmp(2, 1)
 
 julia> cmp(2+im, 3-im)
 ERROR: MethodError: no method matching isless(::Complex{Int64}, ::Complex{Int64})
+Stacktrace:
 [...]
 ```
 """

diff --git a/base/reflection.jl b/base/reflection.jl
@@ -444,7 +444,7 @@ julia> struct Foo
 julia> Base.fieldindex(Foo, :z)
 ERROR: type Foo has no field z
 Stacktrace:
- [1] fieldindex at ./reflection.jl:319 [inlined] (repeats 2 times)
+[...]
 
 julia> Base.fieldindex(Foo, :z, false)
 0

diff --git a/base/strings/basic.jl b/base/strings/basic.jl
@@ -220,6 +220,7 @@ false
 
 julia> str[2]
 ERROR: UnicodeError: invalid character index
+Stacktrace:
 [...]
 ```
 """

diff --git a/base/strings/util.jl b/base/strings/util.jl
@@ -551,7 +551,7 @@ throwing an `ArgumentError` indicating the position of the first non-ASCII byte.
 julia> ascii("abcdeγfgh")
 ERROR: ArgumentError: invalid ASCII at index 6 in "abcdeγfgh"
 Stacktrace:
- [1] ascii(::String) at ./strings/util.jl:479
+[...]
 
 julia> ascii("abcdefgh")
 "abcdefgh"

diff --git a/doc/src/manual/complex-and-rational-numbers.md b/doc/src/manual/complex-and-rational-numbers.md
@@ -143,9 +143,7 @@ julia> sqrt(-1)
 ERROR: DomainError with -1.0:
 sqrt will only return a complex result if called with a complex argument. Try sqrt(Complex(x)).
 Stacktrace:
- [1] throw_complex_domainerror(::Symbol, ::Float64) at ./math.jl:31
- [2] sqrt at ./math.jl:462 [inlined]
- [3] sqrt(::Int64) at ./math.jl:472
+[...]
 
 julia> sqrt(-1 + 0im)
 0.0 + 1.0im
@@ -285,8 +283,7 @@ Trying to construct a [`NaN`](@ref) rational value, however, is not:
 julia> 0//0
 ERROR: ArgumentError: invalid rational: zero(Int64)//zero(Int64)
 Stacktrace:
- [1] Rational{Int64}(::Int64, ::Int64) at ./rational.jl:13
- [2] //(::Int64, ::Int64) at ./rational.jl:40
+[...]
 ```
 
 As usual, the promotion system makes interactions with other numeric types effortless:

diff --git a/doc/src/manual/constructors.md b/doc/src/manual/constructors.md
@@ -93,7 +93,6 @@ julia> struct OrderedPair
            y::Real
            OrderedPair(x,y) = x > y ? error("out of order") : new(x,y)
        end
-
 ```
 
 Now `OrderedPair` objects can only be constructed such that `x <= y`:

diff --git a/doc/src/manual/control-flow.md b/doc/src/manual/control-flow.md
@@ -573,9 +573,7 @@ julia> sqrt(-1)
 ERROR: DomainError with -1.0:
 sqrt will only return a complex result if called with a complex argument. Try sqrt(Complex(x)).
 Stacktrace:
- [1] throw_complex_domainerror(::Symbol, ::Float64) at ./math.jl:31
- [2] sqrt at ./math.jl:462 [inlined]
- [3] sqrt(::Int64) at ./math.jl:472
+[...]
 ```
 
 You may define your own exceptions in the following way:
@@ -765,10 +763,7 @@ julia> sqrt_second(-9)
 ERROR: DomainError with -9.0:
 sqrt will only return a complex result if called with a complex argument. Try sqrt(Complex(x)).
 Stacktrace:
- [1] throw_complex_domainerror(::Symbol, ::Float64) at ./math.jl:31
- [2] sqrt at ./math.jl:462 [inlined]
- [3] sqrt at ./math.jl:472 [inlined]
- [4] sqrt_second(::Int64) at ./none:7
+[...]
 ```
 
 Note that the symbol following `catch` will always be interpreted as a name for the exception,

diff --git a/doc/src/manual/dates.md b/doc/src/manual/dates.md
@@ -334,8 +334,7 @@ function `dayabbr` will error.
 julia> Dates.dayabbr(t;locale="french")
 ERROR: BoundsError: attempt to access 1-element Array{String,1} at index [5]
 Stacktrace:
- [1] #dayabbr#6(::String, ::Function, ::Int64) at ./dates/query.jl:114
- [2] (::Base.Dates.#kw##dayabbr)(::Array{Any,1}, ::Base.Dates.#dayabbr, ::Int64) at ./<missing>:0 (repeats 2 times)
+[...]
 ```
 
 

diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md
@@ -128,6 +128,20 @@ As in the example above, we recommend following some simple conventions when wri
    You can then run `make -C doc doctest` to run all the doctests in the Julia Manual, which will
    ensure that your example works.
 
+   To indicate that the output result is truncated, you may write
+   `[...]` at the line where checking should stop. This is useful to
+   hide a stacktrace (which contains non-permanent references to lines
+   of julia code) when the doctest shows that an exception is thrown,
+   for example:
+
+   ````julia
+   ```jldoctest
+   julia> div(1, 0)
+   ERROR: DivideError: integer division error
+   [...]
+   ```
+   ````
+
    Examples that are untestable should be written within fenced code blocks starting with ````` ```julia`````
    so that they are highlighted correctly in the generated documentation.
 

diff --git a/doc/src/manual/faq.md b/doc/src/manual/faq.md
@@ -227,18 +227,14 @@ julia> sqrt(-2.0)
 ERROR: DomainError with -2.0:
 sqrt will only return a complex result if called with a complex argument. Try sqrt(Complex(x)).
 Stacktrace:
- [1] throw_complex_domainerror(::Symbol, ::Float64) at ./math.jl:31
- [2] sqrt(::Float64) at ./math.jl:462
+[...]
 
 julia> 2^-5
 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: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
@@ -496,6 +492,7 @@ julia> module Foo
 julia> Foo.foo()
 ERROR: On worker 2:
 UndefVarError: Foo not defined
+Stacktrace:
 [...]
 ```
 
@@ -516,6 +513,7 @@ julia> @everywhere module Foo
 julia> Foo.foo()
 ERROR: On worker 2:
 UndefVarError: gvar not defined
+Stacktrace:
 [...]
 ```
 

diff --git a/doc/src/manual/methods.md b/doc/src/manual/methods.md
@@ -243,6 +243,7 @@ julia> g(2, 3.0)
 
 julia> g(2.0, 3.0)
 ERROR: MethodError: g(::Float64, ::Float64) is ambiguous.
+Stacktrace:
 [...]
 ```
 

diff --git a/doc/src/manual/parallel-computing.md b/doc/src/manual/parallel-computing.md
@@ -125,6 +125,7 @@ julia> rand2(2,2)
 
 julia> fetch(@spawn rand2(2,2))
 ERROR: RemoteException(2, CapturedException(UndefVarError(Symbol("#rand2"))
+Stacktrace:
 [...]
 ```
 
@@ -567,6 +568,7 @@ julia> close(c);
 
 julia> put!(c, 2) # `put!` on a closed channel throws an exception.
 ERROR: InvalidStateException("Channel is closed.",:closed)
+Stacktrace:
 [...]
 ```
 
@@ -585,6 +587,7 @@ julia> take!(c) # The first `take!` removes the value.
 
 julia> take!(c) # No more data available on a closed channel.
 ERROR: InvalidStateException("Channel is closed.",:closed)
+Stacktrace:
 [...]
 ```
 

diff --git a/doc/src/manual/performance-tips.md b/doc/src/manual/performance-tips.md
@@ -453,6 +453,7 @@ MyBetterContainer{Float64,UnitRange{Float64}}
 
 julia> b = MyBetterContainer{Int64, UnitRange{Float64}}(UnitRange(1.3, 5.0));
 ERROR: MethodError: Cannot `convert` an object of type UnitRange{Float64} to an object of type MyBetterContainer{Int64,UnitRange{Float64}}
+Stacktrace:
 [...]
 ```
 

diff --git a/doc/src/manual/strings.md b/doc/src/manual/strings.md
@@ -205,6 +205,7 @@ ERROR: BoundsError: attempt to access "Hello, world.\n"
 julia> str[end+1]
 ERROR: BoundsError: attempt to access "Hello, world.\n"
   at index [15]
+Stacktrace:
 [...]
 ```
 

diff --git a/doc/src/manual/types.md b/doc/src/manual/types.md
@@ -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:118
+[...]
 
 julia> get(Nullable(1.0))
 1.0

diff --git a/doc/src/manual/variables-and-scoping.md b/doc/src/manual/variables-and-scoping.md
@@ -276,7 +276,7 @@ julia> f = y -> y + a
 julia> f(3)
 ERROR: UndefVarError: a not defined
 Stacktrace:
- [1] (::##1#2)(::Int64) at ./none:1
+[...]
 
 julia> a = 1
 1

diff --git a/stdlib/Test/docs/src/index.md b/stdlib/Test/docs/src/index.md
@@ -75,7 +75,7 @@ Error During Test
     length(::MethodTable) at reflection.jl:597
     ...
   Stacktrace:
-   [...]
+  [...]
 ERROR: There was an error during testing
 ```
 
@@ -154,8 +154,7 @@ julia> @testset "Foo Tests" begin
 Arrays: Test Failed
   Expression: foo(ones(4)) == 15
    Evaluated: 16 == 15
-Stacktrace:
-    [...]
+[...]
 Test Summary: | Pass  Fail  Total
 Foo Tests     |    3     1      4
   Animals     |    2            2

diff --git a/stdlib/Test/src/Test.jl b/stdlib/Test/src/Test.jl
@@ -1139,8 +1139,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:33
+[...]
 
 julia> @inferred max(1,2)
 2