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

base/docs/helpdb/Base.jl

@@ -2,13 +2,6 @@
 
 # Base
 
-"""
-    systemerror(sysfunc, iftrue)
-
-Raises a `SystemError` for `errno` with the descriptive string `sysfunc` if `iftrue` is `true`
-"""
-systemerror
-
 """
     fill!(A, x)
 
@@ -176,13 +169,6 @@ julia> [1 2 3] .* [1 2 3]
 """
 Base.:(.*)
 
-"""
-    backtrace()
-
-Get a backtrace object for the current program point.
-"""
-backtrace
-
 """
     -(x)
 
@@ -290,14 +276,6 @@ Neither `convert` nor `cconvert` should take a Julia object and turn it into a `
 """
 cconvert
 
-"""
-    assert(cond)
-
-Throw an [`AssertionError`](:obj:`AssertionError`) if `cond` is `false`.
-Also available as the macro `@assert expr`.
-"""
-assert
-
 """
     sech(x)
 
@@ -2155,13 +2133,6 @@ Show a descriptive representation of an exception object.
 """
 showerror
 
-"""
-    error(message::AbstractString)
-
-Raise an `ErrorException` with the given message.
-"""
-error
-
 """
     sqrtm(A)
 
@@ -2538,14 +2509,6 @@ This is intended to be called using `do` block syntax:
 """
 get!(f::Function,collection,key)
 
-"""
-    @assert cond [text]
-
-Throw an `AssertionError` if `cond` is `false`. Preferred syntax for writing assertions.
-Message `text` is optionally displayed upon assertion failure.
-"""
-:@assert
-
 """
     deserialize(stream)
 
@@ -2587,14 +2550,6 @@ Cumulative product of `A` along a dimension, storing the result in `B`. The dime
 """
 cumprod!
 
-"""
-    rethrow([e])
-
-Throw an object without changing the current exception backtrace. The default argument is
-the current exception (if called within a `catch` block).
-"""
-rethrow
-
 """
     !(x)
 
@@ -2799,13 +2754,6 @@ garbage answers, in the same manner as C.
 """
 unsafe_load
 
-"""
-    catch_backtrace()
-
-Get the backtrace of the current exception, for use within `catch` blocks.
-"""
-catch_backtrace
-
 """
     cos(x)
 

base/error.jl

@@ -18,24 +18,83 @@
 
 ## native julia error handling ##
 
+"""
+    error(message::AbstractString)
+
+Raise an `ErrorException` with the given message.
+"""
 error(s::AbstractString) = throw(ErrorException(s))
 error(s...) = throw(ErrorException(Main.Base.string(s...)))
 
+"""
+    rethrow([e])
+
+Throw an object without changing the current exception backtrace. The default argument is
+the current exception (if called within a `catch` block).
+"""
 rethrow() = ccall(:jl_rethrow, Bottom, ())
 rethrow(e) = ccall(:jl_rethrow_other, Bottom, (Any,), e)
+
+"""
+    backtrace()
+
+Get a backtrace object for the current program point.
+"""
 backtrace() = ccall(:jl_backtrace_from_here, Array{Ptr{Void},1}, (Int32,), false)
+
+"""
+    catch_backtrace()
+
+Get the backtrace of the current exception, for use within `catch` blocks.
+The backtrace is represented as an `Array{Ptr{Void}}` of addresses, so [`showerror`](:func:`showerror`)
+may be helpful for displaying the backtrace in a human-readable format.
+
+# Example
+
+```jldoctest
+julia> f(x) = try
+           sqrt(x)
+       catch y
+           bt = catch_backtrace()
+           showerror(STDOUT, y, bt)
+       end;
+
+julia> f(-1)
+DomainError:
+ in f(::Int64) at ./REPL[24]:2
+ in eval(::Module, ::Any) at ./boot.jl:236
+ ...
+```
+"""
 catch_backtrace() = ccall(:jl_get_backtrace, Array{Ptr{Void},1}, ())
 
 ## keyword arg lowering generates calls to this ##
 kwerr(kw, args...) = throw(MethodError(typeof(args[1]).name.mt.kwsorter, (kw,args...)))
 
 ## system error handling ##
+"""
+    systemerror(sysfunc, iftrue)
 
+Raises a `SystemError` for `errno` with the descriptive string `sysfunc` if `iftrue` is `true`.
+"""
 systemerror(p, b::Bool; extrainfo=nothing) = b ? throw(Main.Base.SystemError(string(p), Libc.errno(), extrainfo)) : nothing
 
 ## assertion functions and macros ##
 
+"""
+    assert(cond)
+
+Throw an [`AssertionError`](:obj:`AssertionError`) if `cond` is `false`.
+Also available as the macro `@assert expr`.
+"""
 assert(x) = x ? nothing : throw(Main.Base.AssertionError())
+
+"""
+    @assert cond [text]
+
+Throw an `AssertionError` if `cond` is `false`. Preferred syntax for writing assertions.
+Message `text` is optionally displayed upon assertion failure.
+"""
 macro assert(ex, msgs...)
     msg = isempty(msgs) ? ex : msgs[1]
     if !isempty(msgs) && (isa(msg, Expr) || isa(msg, Symbol))

base/test.jl

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

doc/manual/control-flow.rst

@@ -807,7 +807,7 @@ execution:
 
     julia> error("Hi"); 1+1
     ERROR: Hi
-     in error(::String) at ./error.jl:21
+     in error(::String) at ./error.jl:26
      ...
 
 

doc/stdlib/base.rst

@@ -1197,7 +1197,24 @@ Errors
 
    .. Docstring generated from Julia source
 
-   Get the backtrace of the current exception, for use within ``catch`` blocks.
+   Get the backtrace of the current exception, for use within ``catch`` blocks. The backtrace is represented as an ``Array{Ptr{Void}}`` of addresses, so :func:`showerror` may be helpful for displaying the backtrace in a human-readable format.
+
+   **Example**
+
+   .. doctest::
+
+       julia> f(x) = try
+                  sqrt(x)
+              catch y
+                  bt = catch_backtrace()
+                  showerror(STDOUT, y, bt)
+              end;
+
+       julia> f(-1)
+       DomainError:
+        in f(::Int64) at ./REPL[24]:2
+        in eval(::Module, ::Any) at ./boot.jl:236
+        ...
 
 .. function:: assert(cond)
 

doc/stdlib/c.rst

@@ -157,7 +157,7 @@
 
    .. Docstring generated from Julia source
 
-   Raises a ``SystemError`` for ``errno`` with the descriptive string ``sysfunc`` if ``iftrue`` is ``true``
+   Raises a ``SystemError`` for ``errno`` with the descriptive string ``sysfunc`` if ``iftrue`` is ``true``\ .
 
 .. data:: Ptr{T}
 

doc/stdlib/math.rst

@@ -461,7 +461,7 @@ Mathematical Operators
 
    .. Docstring generated from Julia source
 
-   Equivalent to ``!is(x, y)``\ .
+   Equivalent to ``!(x === y)``\ .
 
 .. _<:
 .. function:: <(x, y)

doc/stdlib/test.rst

@@ -274,7 +274,7 @@ writing new tests.
 
        julia> @inferred f(1,2,3)
        ERROR: return type Int64 does not match inferred return type Union{Float64,Int64}
-        in error(::String) at ./error.jl:21
+        in error(::String) at ./error.jl:26
         ...
 
        julia> @inferred max(1,2)