doc improvements

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

@@ -1000,38 +1000,6 @@ implementation of a more specific method of the same function).
 """
 invoke
 
-"""
- parse(str, start; greedy=true, raise=true)
-
-Parse the expression string and return an expression (which could later be passed to eval
-for execution). `start` is the index of the first character to start parsing. If `greedy` is
-`true` (default), `parse` will try to consume as much input as it can; otherwise, it will
-stop as soon as it has parsed a valid expression. Incomplete but otherwise syntactically
-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.
-"""
-parse(str, start)
-
-"""
- parse(str; raise=true)
-
-Parse the expression string greedily, returning a single expression. An error is thrown if
-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.
-"""
-parse(str)
-
-"""
- parse(type, str, [base])
-
-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.
-"""
-parse(T::Type, str, base=Int)
-
 """
  position(s)
 
@@ -2209,14 +2177,6 @@ Compute the cosecant of `x`, where `x` is in degrees.
 """
 cscd
 
-"""
- tryparse(type, str, [base])
-
-Like [`parse`](@ref), but returns a [`Nullable`](@ref) of the requested type. The result will be null if the
-string does not contain a valid number.
-"""
-tryparse
-
 """
  exit([code])
 

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/parse.jl

@@ -171,11 +171,45 @@ end
  throw(ArgumentError("invalid base: base must be 2 ≤ base ≤ 62, got $base"))
 end
 
+
+"""
+ tryparse(type, str, [base])
+
+Like [`parse`](@ref), but returns a [`Nullable`](@ref) of the requested type. The result will be null if the
+string does not contain a valid number.
+"""
+function tryparse end
+
 tryparse(::Type{T}, s::AbstractString, base::Integer) where {T<:Integer} =
  tryparse_internal(T, s, start(s), endof(s), check_valid_base(base), false)
 tryparse(::Type{T}, s::AbstractString) where {T<:Integer} =
  tryparse_internal(T, s, start(s), endof(s), 0, false)
 
+
+"""
+ parse(type, str, [base])
+
+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
+```
+"""
+function parse(T::Type, str, base=Int) end
+
+
 function parse(::Type{T}, s::AbstractString, base::Integer) where T<:Integer
  get(tryparse_internal(T, s, start(s), endof(s), check_valid_base(base), true))
 end
@@ -211,6 +245,28 @@ float(a::AbstractArray{<:AbstractString}) = map!(float, similar(a,typeof(float(0
 
 ## interface to parser ##
 
+"""
+ parse(str, start; greedy=true, raise=true) -> (Expr, Int)
+
+Parse the expression string and return an expression (which could later be passed to eval
+for execution). `start` is the index of the first character to start parsing. If `greedy` is
+`true` (default), `parse` will try to consume as much input as it can; otherwise, it will
+stop as soon as it has parsed a valid expression. Incomplete but otherwise syntactically
+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)
+
+
 function parse(str::AbstractString, pos::Int; greedy::Bool=true, raise::Bool=true)
  # pos is one based byte offset.
  # returns (expr, end_pos). expr is () in case of parse error.
@@ -228,6 +284,33 @@ function parse(str::AbstractString, pos::Int; greedy::Bool=true, raise::Bool=tru
  return ex, pos+1 # C is zero-based, Julia is 1-based
 end
 
+
+"""
+ parse(str; raise=true) -> Expr
+
+Parse the expression string greedily, returning a single expression. An error is thrown if
+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)
+
 function parse(str::AbstractString; raise::Bool=true)
  ex, pos = parse(str, 1, greedy=true, raise=raise)
  if isa(ex,Expr) && ex.head === :error

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)