Move error.jl docs inline; add example to catch_backtrace()

[xorJane]

I moved docstrings inline for a few functions declared in error.jl and augmented the docs slightly for catch_backtrace(). ref #7283

Thanks in advance and happy Saturday!

[tkelman]

code highlight Array{Ptr{Void}}

[xorJane]

Fixed. Thanks!

[tkelman]

if the output of calling say f(-1) is repeatable, is it worth doctesting?

[xorJane]

The output seems system dependent. I get

DomainError: in f(::Int64) at ./REPL[49]:2 in eval(::Module, ::Any) at ./boot.jl:238 in eval(::Module, ::Any) at /Users/jane/Applications/julia/usr/lib/julia/sys.dylib:? in eval_user_input(::Any, ::Base.REPL.REPLBackend) at ./REPL.jl:66 in macro expansion at ./REPL.jl:97 [inlined] in (::Base.REPL.##3#4{Base.REPL.REPLBackend})() at ./event.jl:65

Is there a work-around/way to exclude local paths so I can include a doctest?

[tkelman]

I think those eval backtrace lines always get filtered out of doctest outputs so don't need to be included (they also might be different if run from repl vs a script)

[xorJane]

Added the doctest without eval backtrace lines!

[kshyatt]

@tkelman is this good to go?

[tkelman]

does this doctest pass like this?

[xorJane]

No, I made a mistake. As you suggested earlier, the output from running doctests is different from what you get at the repl.

Additionally, it looks like I need to add a println() statement to get the doctest to pass. For example,

julia> f(x) = try
           sqrt(x)
       catch y
           bt = catch_backtrace()
           showerror(STDOUT, y, bt)
           println()
       end;

julia> f(-1)
DomainError:
 in f(::Int64) at ./none:2
 in eval(::Module, ::Any) at ./boot.jl:236
...

and

julia> f(x) = try
           sqrt(x)
       catch y
           bt = catch_backtrace()
           showerror(STDOUT, y, bt)
       end;

julia> f(-1); println()
DomainError:
 in f(::Int64) at ./none:2
 in eval(::Module, ::Any) at ./boot.jl:236
...

pass, but they fail when I remove println(). Do you think either of the above is an adequate solution?

[tkelman]

that's strange. what does running the doctests say for "got" without the println ?

[yuyichao]

Buffering issue?

[xorJane]

@tkelman Excluding the system dependent info from "got", I see

File "stdlib/base.rst", line 1234, in default
Failed example:
    f(-1)
Expected:
    DomainError:
     in f(::Int64) at ./none:2
     in eval(::Module, ::Any) at ./boot.jl:236
    ...
Got:
    DomainError:
     in f(::Int64) at ./none:2
     in eval(::Module, ::Any) at ./boot.jl:236

I haven't been able to identify additional or missing whitespace as the problem.

@yuyichao Sorry, what do you mean?

[yuyichao]

What's

Excluding the system dependent info from "got", I see

[xorJane]

I was referring to output that included local paths. The full output is:

Got:
    DomainError:
     in f(::Int64) at ./none:2
     in eval(::Module, ::Any) at ./boot.jl:236
     in eval(::Module, ::Any) at /Users/jane/Applications/julia/usr/lib/julia/sys.dylib:?
     in eval_user_input(::Any, ::Bool) at ./client.jl:123
     in eval_user_input(::Any, ::Bool) at /Users/jane/Applications/julia/usr/lib/julia/sys.dylib:?
     in eval(::Module, ::Any) at ./boot.jl:236
     in eval(::Module, ::Any) at /Users/jane/Applications/julia/usr/lib/julia/sys.dylib:?
     in eval_user_input(::Any, ::Bool) at ./client.jl:123
     in eval_user_input(::Any, ::Bool) at /Users/jane/Applications/julia/usr/lib/julia/sys.dylib:?
     in _start() at ./client.jl:372
     in _start() at /Users/jane/Applications/julia/usr/lib/julia/sys.dylib:?**

[yuyichao]

That should be included since it at least means what tony said won't work.

[tkelman]

I think the doctest system specifically removes those, but I'm not sure where that happens

[xorJane]

That should be included since it at least means what tony said won't work.

This doctest fails even when I include the full output listed for "got".

After formatting this doctest several different ways, the only solutions I found involved adding calls to println(). I suspect there may be a bug in the way the doctest system is parsing this code block, but I did not find anything suspicious after going through what I could find of the documentation code. If there aren't other suggestions for things I might try, then I think I will move on to other fronts. Please let me know if you'd like me to convert this doctest to a regular code block or make some other modification. Thanks! :)

[fredrikekre]

#23272

[tkelman]

Though the catch_backtrace docstring doesn't have a doctest example yet, but that may be tricky to get to pass. It could be added as julia-repl maybe.