add a few doctests to broadcast, parse, intfuncs, number and permuted…

…dimsarray (#22289)

base/broadcast.jl

@@ -591,6 +591,16 @@ If you want to *avoid* adding dots for selected function calls in
 (no dot for `sort`).
 
 (`@.` is equivalent to a call to `@__dot__`.)
+
+```jldoctest
+julia> x = 1.0:3.0; y = similar(x);
+
+julia> @. y = x + 3 * sin(x)
+3-element Array{Float64,1}:
+ 3.52441
+ 4.72789
+ 3.42336
+```
 """
 macro __dot__(x)
     esc(__dot__(x))

base/docs/helpdb/Base.jl

@@ -1010,6 +1010,14 @@ stop as soon as it has parsed a valid expression. Incomplete but otherwise synta
 valid expressions will return `Expr(:incomplete, "(error message)")`. If `raise` is `true`
 (default), syntax errors other than incomplete expressions will raise an error. If `raise`
 is `false`, `parse` will return an expression that will raise an error upon evaluation.
+
+```jldoctest
+julia> parse("x = 3, y = 5", 7)
+(:(y = 5), 13)
+
+julia> parse("x = 3, y = 5", 5)
+(:((3, y) = 5), 13)
+```
 """
 parse(str, start)
 
@@ -1020,6 +1028,22 @@ Parse the expression string greedily, returning a single expression. An error is
 there are additional characters after the first expression. If `raise` is `true` (default),
 syntax errors will raise an error; otherwise, `parse` will return an expression that will
 raise an error upon evaluation.
+
+```jldoctest
+julia> parse("x = 3")
+:(x = 3)
+
+julia> parse("x = ")
+:($(Expr(:incomplete, "incomplete: premature end of input")))
+
+julia> parse("1.0.2")
+ERROR: ParseError("invalid numeric constant \\\"1.0.\\\"")
+Stacktrace:
+  [...]
+
+julia> parse("1.0.2"; raise = false)
+:($(Expr(:error, "invalid numeric constant \"1.0.\"")))
+```
 """
 parse(str)
 
@@ -1029,6 +1053,20 @@ parse(str)
 Parse a string as a number. If the type is an integer type, then a base can be specified
 (the default is 10). If the type is a floating point type, the string is parsed as a decimal
 floating point number. If the string does not contain a valid number, an error is raised.
+
+```jldoctest
+julia> parse(Int, "1234")
+1234
+
+julia> parse(Int, "1234", 5)
+194
+
+julia> parse(Int, "afc", 16)
+2812
+
+julia> parse(Float64, "1.2e-3")
+0.0012
+```
 """
 parse(T::Type, str, base=Int)
 

base/intfuncs.jl

@@ -224,6 +224,14 @@ const HWNumber = Union{HWReal, Complex{<:HWReal}, Rational{<:HWReal}}
     powermod(x::Integer, p::Integer, m)
 
 Compute ``x^p \\pmod m``.
+
+```jldoctest
+julia> powermod(2, 6, 5)
+4
+
+julia> mod(2^6, 5)
+4
+```
 """
 function powermod(x::Integer, p::Integer, m::T) where T<:Integer
     p < 0 && return powermod(invmod(x, m), -p, m)
@@ -302,6 +310,16 @@ ispow2(x::Integer) = x > 0 && count_ones(x) == 1
 
 The smallest `a^n` not less than `x`, where `n` is a non-negative integer. `a` must be
 greater than 1, and `x` must be greater than 0.
+
+```jldoctest
+julia> nextpow(2, 7)
+8
+
+julia> nextpow(2, 9)
+16
+```
+
+See also [`prevpow`](@ref).
 """
 function nextpow(a::Real, x::Real)
     (a <= 1 || x <= 0) && throw(DomainError())
@@ -317,6 +335,16 @@ end
 
 The largest `a^n` not greater than `x`, where `n` is a non-negative integer.
 `a` must be greater than 1, and `x` must not be less than 1.
+
+```jldoctest
+julia> prevpow(2, 7)
+4
+
+julia> prevpow(2, 9)
+8
+```
+
+See also [`nextpow`](@ref).
 """
 function prevpow(a::Real, x::Real)
     (a <= 1 || x < 1) && throw(DomainError())
@@ -411,6 +439,16 @@ Return 0 if `n == 0`, otherwise compute the number of digits in
 integer `n` written in base `b` (i.e. equal to `ndigits(n, b)`
 in this case).
 The base `b` must not be in `[-1, 0, 1]`.
+
+```jldoctest
+julia> Base.ndigits0z(0, 16)
+0
+
+julia> Base.ndigits(0, 16)
+1
+```
+
+See also [`ndigits`](@ref).
 """
 function ndigits0z(x::Integer, b::Integer)
     if b < -1
@@ -427,6 +465,17 @@ end
 
 Compute the number of digits in integer `n` written in base `b`.
 The base `b` must not be in `[-1, 0, 1]`.
+
+```jldoctest
+julia> ndigits(12345)
+5
+
+julia> ndigits(1022, 16)
+3
+
+julia> base(16, 1022)
+"3fe"
+```
 """
 ndigits(x::Integer, b::Integer, pad::Int=1) = max(pad, ndigits0z(x, b))
 
@@ -650,6 +699,14 @@ end
     binomial(n,k)
 
 Number of ways to choose `k` out of `n` items.
+
+```jldoctest
+julia> binomial(5, 3)
+10
+
+julia> factorial(5) ÷ (factorial(5-3) * factorial(3))
+10
+```
 """
 function binomial(n::T, k::T) where T<:Integer
     k < 0 && return zero(T)

base/number.jl

@@ -85,13 +85,26 @@ abs(x::Real) = ifelse(signbit(x), -x, x)
     abs2(x)
 
 Squared absolute value of `x`.
+
+```jldoctest
+julia> abs2(-3)
+9
+```
 """
 abs2(x::Real) = x*x
 
 """
     flipsign(x, y)
 
 Return `x` with its sign flipped if `y` is negative. For example `abs(x) = flipsign(x,x)`.
+
+```jldoctest
+julia> flipsign(5, 3)
+5
+
+julia> flipsign(5, -3)
+-5
+```
 """
 flipsign(x::Real, y::Real) = ifelse(signbit(y), -x, +x) # the + is for type-stability on Bool
 copysign(x::Real, y::Real) = ifelse(signbit(x)!=signbit(y), -x, +x)
@@ -126,6 +139,19 @@ map(f, x::Number, ys::Number...) = f(x, ys...)
     zero(x)
 
 Get the additive identity element for the type of `x` (`x` can also specify the type itself).
+
+```jldoctest
+julia> zero(1)
+0
+
+julia> zero(big"2.0")
+0.000000000000000000000000000000000000000000000000000000000000000000000000000000
+
+julia> zero(rand(2,2))
+2×2 Array{Float64,2}:
+ 0.0  0.0
+ 0.0  0.0
+```
 """
 zero(x::Number) = oftype(x,0)
 zero(::Type{T}) where {T<:Number} = convert(T,0)

base/permuteddimsarray.jl

@@ -121,6 +121,8 @@ vector specifying a permutation of length `ndims(src)`. The preallocated array `
 have `size(dest) == size(src)[perm]` and is completely overwritten. No in-place permutation
 is supported and unexpected results will happen if `src` and `dest` have overlapping memory
 regions.
+
+See also [`permutedims`](@ref)
 """
 function Base.permutedims!(dest, src::AbstractArray, perm)
     Base.checkdims_perm(dest, src, perm)