From b4e5a259ab0a0afe7936a0bc9dbbe3bc0594e82d Mon Sep 17 00:00:00 2001
From: "Jane E. Herriman" <jane@caltech.edu>
Date: Sat, 1 Jul 2017 10:46:04 -0700
Subject: [PATCH] Move docs inline from helpdb and add a couple doctests

---
 base/abstractarray.jl    | 12 ++++++++++++
 base/docs/helpdb/Base.jl | 40 ----------------------------------------
 base/error.jl            |  7 +++++++
 base/floatfuncs.jl       | 19 +++++++++++++++++++
 base/initdefs.jl         |  6 ++++++
 base/strings/types.jl    | 20 ++++++++++++++++++++
 6 files changed, 64 insertions(+), 40 deletions(-)

diff --git a/base/abstractarray.jl b/base/abstractarray.jl
index 63ef9ab76b6ec..5861073984cc9 100644
--- a/base/abstractarray.jl
+++ b/base/abstractarray.jl
@@ -842,6 +842,12 @@ Represents the array `y` as an array having the same indices type as `x`.
 """
 of_indices(x, y) = similar(dims->y, oftype(indices(x), indices(y)))
 
+
+"""
+    full(F)
+
+Reconstruct the matrix `A` from the factorization `F=factorize(A)`.
+"""
 full(x::AbstractArray) = x
 
 ## range conversions ##
@@ -1265,6 +1271,7 @@ end
 
 Concatenate along dimension 1.
 
+# Examples
 ```jldoctest
 julia> a = [1 2 3 4 5]
 1×5 Array{Int64,2}:
@@ -1296,6 +1303,7 @@ vcat(X...) = cat(Val{1}, X...)
 
 Concatenate along dimension 2.
 
+# Examples
 ```jldoctest
 julia> a = [1; 2; 3; 4; 5]
 5-element Array{Int64,1}:
@@ -1372,6 +1380,7 @@ Horizontal and vertical concatenation in one call. This function is called for b
 syntax. The first argument specifies the number of arguments to concatenate in each block
 row.
 
+# Examples
 ```jldoctest
 julia> a, b, c, d, e, f = 1, 2, 3, 4, 5, 6
 (1, 2, 3, 4, 5, 6)
@@ -1577,6 +1586,7 @@ end
 
 Returns a tuple of subscripts into array `a` corresponding to the linear index `index`.
 
+# Examples
 ```jldoctest
 julia> A = ones(5,6,7);
 
@@ -1604,6 +1614,7 @@ sub2ind(::Tuple{}, I::Integer...) = (@_inline_meta; _sub2ind((), 1, 1, I...))
 
 The inverse of [`ind2sub`](@ref), returns the linear index corresponding to the provided subscripts.
 
+# Examples
 ```jldoctest
 julia> sub2ind((5,6,7),1,2,3)
 66
@@ -1653,6 +1664,7 @@ i, j, ... = ind2sub(size(A), indmax(A))
 
 provides the indices of the maximum element.
 
+# Examples
 ```jldoctest
 julia> ind2sub((3,4),2)
 (2, 1)
diff --git a/base/docs/helpdb/Base.jl b/base/docs/helpdb/Base.jl
index c26f686a4e73e..ab3e49a2e8050 100644
--- a/base/docs/helpdb/Base.jl
+++ b/base/docs/helpdb/Base.jl
@@ -2055,29 +2055,6 @@ x` is converted by the compiler to `(setindex!(a, x, i, j, ...); x)`.
 """
 setindex!(collection,value,key...)
 
-"""
-    signif(x, digits, [base])
-
-Rounds (in the sense of [`round`](@ref)) `x` so that there are `digits` significant digits, under a
-base `base` representation, default 10. E.g., `signif(123.456, 2)` is `120.0`, and
-`signif(357.913, 4, 2)` is `352.0`.
-"""
-signif
-
-"""
-    full(F)
-
-Reconstruct the matrix `A` from the factorization `F=factorize(A)`.
-"""
-full(F)
-
-"""
-    throw(e)
-
-Throw an object as an exception.
-"""
-throw
-
 """
     zeros([A::AbstractArray,] [T=eltype(A)::Type,] [dims=size(A)::Tuple])
 
@@ -2145,23 +2122,6 @@ Values for `String` can be of that type, or `Vector{UInt8}`.
 """
 isvalid(T,value)
 
-"""
-    reverseind(v, i)
-
-Given an index `i` in `reverse(v)`, return the corresponding index in `v` so that
-`v[reverseind(v,i)] == reverse(v)[i]`. (This can be nontrivial in the case where `v` is a
-Unicode string.)
-"""
-reverseind
-
-"""
-    exit([code])
-
-Quit (or control-D at the prompt). The default exit code is zero, indicating that the
-processes completed successfully.
-"""
-exit
-
 """
     skipchars(stream, predicate; linecomment::Char)
 
diff --git a/base/error.jl b/base/error.jl
index f26df61ee91d8..df09f57c1e50f 100644
--- a/base/error.jl
+++ b/base/error.jl
@@ -16,6 +16,13 @@
 #     rethrow(val)
 # end
 
+"""
+    throw(e)
+
+Throw an object as an exception.
+"""
+throw
+
 ## native julia error handling ##
 
 error(s::AbstractString) = throw(ErrorException(s))
diff --git a/base/floatfuncs.jl b/base/floatfuncs.jl
index a5973c7d99986..ac88fc1b743de 100644
--- a/base/floatfuncs.jl
+++ b/base/floatfuncs.jl
@@ -48,6 +48,7 @@ specifying a rounding mode the global mode will be used
 ([`RoundNearest`](@ref) mode), with ties (fractional values of 0.5) being
 rounded to the nearest even integer.
 
+# Examples
 ```jldoctest
 julia> round(1.7)
 2.0
@@ -68,6 +69,7 @@ rounded.
 `round(x, digits)` rounds to the specified number of digits after the decimal place (or
 before if negative). `round(x, digits, base)` rounds using a base other than 10.
 
+# Examples
 ```jldoctest
 julia> round(pi, 2)
 3.14
@@ -82,6 +84,7 @@ julia> round(pi, 3, 2)
     value represented by `1.15` is actually *less* than 1.15, yet will be
     rounded to 1.2.
 
+    # Examples
     ```jldoctest
     julia> x = 1.15
     1.15
@@ -131,6 +134,21 @@ function _signif_og(x, digits, base)
     return og, e
 end
 
+"""
+    signif(x, digits, [base])
+
+Rounds (in the sense of [`round`](@ref)) `x` so that there are `digits` significant digits, under a
+base `base` representation, default 10.
+
+# Examples
+```jldoctest
+julia> signif(123.456, 2)
+120.0
+
+julia> signif(357.913, 4, 2)
+352.0
+```
+"""
 function signif(x::Real, digits::Integer, base::Integer=10)
     digits < 1 && throw(DomainError())
 
@@ -189,6 +207,7 @@ approximately equal component-wise.
 The binary operator `≈` is equivalent to `isapprox` with the default arguments, and `x ≉ y`
 is equivalent to `!isapprox(x,y)`.
 
+# Examples
 ```jldoctest
 julia> 0.1 ≈ (0.1 - 1e-10)
 true
diff --git a/base/initdefs.jl b/base/initdefs.jl
index 4535a718a5fd7..c453b2b78070d 100644
--- a/base/initdefs.jl
+++ b/base/initdefs.jl
@@ -18,6 +18,12 @@ An array of the command line arguments passed to Julia, as strings.
 """
 const ARGS = String[]
 
+"""
+    exit([code])
+
+Quit (or control-D at the prompt). The default exit code is zero, indicating that the
+processes completed successfully.
+"""
 exit(n) = ccall(:jl_exit, Void, (Int32,), n)
 exit() = exit(0)
 quit() = exit()
diff --git a/base/strings/types.jl b/base/strings/types.jl
index 587af56c4015d..8f821d3572623 100644
--- a/base/strings/types.jl
+++ b/base/strings/types.jl
@@ -117,6 +117,7 @@ end
     reverse(s::AbstractString) -> AbstractString
 
 Reverses a string.
+# Examples
 ```jldoctest
 julia> reverse("JuliaLang")
 "gnaLailuJ"
@@ -127,6 +128,24 @@ reverse(s::RevString) = s.string
 
 ## reverse an index i so that reverse(s)[i] == s[reverseind(s,i)]
 
+"""
+    reverseind(v, i)
+
+Given an index `i` in `reverse(v)`, return the corresponding index in `v` so that
+`v[reverseind(v,i)] == reverse(v)[i]`. (This can be nontrivial in the case where `v` is a
+Unicode string.)
+
+# Examples
+```jldoctest
+julia> r = reverse("Julia")
+"ailuJ"
+
+julia> for i in 1:length(r)
+           print(r[reverseind("Julia", i)])
+       end
+Julia
+```
+"""
 reverseind(s::AbstractString, i) = chr2ind(s, length(s) + 1 - ind2chr(reverse(s), i))
 reverseind(s::Union{DirectIndexString,SubString{DirectIndexString}}, i::Integer) = length(s) + 1 - i
 reverseind(s::RevString, i::Integer) = endof(s) - i + 1
@@ -146,6 +165,7 @@ end
 Repeat `n` times the string `s`.
 The [`repeat`](@ref) function is an alias to this operator.
 
+# Examples
 ```jldoctest
 julia> "Test "^3
 "Test Test Test "