Skip to content

Commit

Permalink
Fix doctest code-blocks in documentation
Browse files Browse the repository at this point in the history 
cb8aa0b - fix most doctests in the manual that changed due to backtraces.
cd3797e - fix stdlib doctests
1892f72 - fix doctests in devdocs
d9495c7 - resolve Warning mismatch by renaming functions
83ef854 - convert superflous doctest to code-block
78f6d70 - Fix example about typemax and typemin

          Due to the changes in 4706184 tuples are now printed compact. Thus to
          demonstrate the point in this example we have to execute the examples
          independently.
c03e6e0 - fixup linenumbers
35a31bb - start->first

Ref #15753
  • Loading branch information
@vchuravy @omus
vchuravy authored and omus committed Jun 25, 2016
1 parent c20199e commit ce62f34
Show file tree
Hide file tree
Showing 22 changed files with 270 additions and 180 deletions.
6 changes: 4 additions & 2 deletions base/docs/helpdb/Base.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5643,7 +5643,8 @@ julia> deleteat!([6, 5, 4, 3, 2, 1], 1:2:5)
julia> deleteat!([6, 5, 4, 3, 2, 1], (2, 2))
ERROR: ArgumentError: indices must be unique and sorted
in deleteat! at array.jl:543
in deleteat!(::Array{Int64,1}, ::Tuple{Int64,Int64}) at ./array.jl:565
in eval(::Module, ::Any) at ./boot.jl:237
```
"""
deleteat!(collection, itr)
Expand Down Expand Up @@ -8311,7 +8312,8 @@ julia> convert(Int, 3.0)
julia> convert(Int, 3.5)
ERROR: InexactError()
in convert at int.jl:209
in convert(::Type{Int64}, ::Float64) at ./int.jl:229
in eval(::Module, ::Any) at ./boot.jl:237
```
If `T` is a [`AbstractFloat`](:obj:`AbstractFloat`) or [`Rational`](:obj:`Rational`) type,
Expand Down
9 changes: 7 additions & 2 deletions doc/devdocs/reflection.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -104,9 +104,14 @@ variable assignments:
.. doctest::

julia> expand( :(f() = 1) )
:($(Expr(:method, :f, :((top(svec))((top(apply_type))(Tuple),(top(svec))())), AST(:($(Expr(:lambda, Any[], Any[Any[],Any[],0,Any[]], :(begin # none, line 1:
:(begin
$(Expr(:method, :f))
$(Expr(:method, :f, :((top(svec))((top(apply_type))(Tuple,((top(getfield))(Core,:Typeof))(f)),(top(svec))())), LambdaInfo for anonymous
:(begin # none, line 1:
return 1
end))))), false)))
end), false))
return f
end)

.. rubric:: Intermediate and compiled representations

Expand Down
74 changes: 37 additions & 37 deletions doc/devdocs/types.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -130,17 +130,17 @@ one can extract the underlying :obj:`TypeVar`:
.. testcode:: s

g{S<:Integer}(x::S) = 0
m = start(methods(g))
m = first(methods(g))
p = m.sig.parameters
tv = p[1]
tv = p[2]
dump(tv)

.. testoutput:: s

TypeVar
name: Symbol S
lb: Union{}
ub: Integer::DataType <: Real
ub: Integer <: Real
bound: Bool true

Here ``ub`` is ``Integer``, as specified in the function definition.
Expand All @@ -160,27 +160,27 @@ parameters. For example:
julia> h3{T<:Real}(A::Array{T}, b::T) = 1
h3 (generic function with 1 method)

julia> p1 = start(methods(h1)).sig.parameters
svec(Array{T,N},Real)
julia> p1 = first(methods(h1)).sig.parameters
svec(#h1,Array{T,N},Real)

julia> p2 = start(methods(h2)).sig.parameters
svec(Array{T,N},T<:Real)
julia> p2 = first(methods(h2)).sig.parameters
svec(#h2,Array{T,N},T<:Real)

julia> p3 = start(methods(h3)).sig.parameters
svec(Array{T<:Real,N},T<:Real)
julia> p3 = first(methods(h3)).sig.parameters
svec(#h3,Array{T<:Real,N},T<:Real)

julia> dump(p1[1].parameters[1])
julia> dump(p1[2].parameters[1])
TypeVar
name: Symbol T
lb: Union{}
ub: Any::DataType <: Any
ub: Any <: Any
bound: Bool false

julia> dump(p3[1].parameters[1])
julia> dump(p3[2].parameters[1])
TypeVar
name: Symbol T
lb: Union{}
ub: Real::DataType <: Number
ub: Real <: Number
bound: Bool true

Note that ``p2`` shows two objects called ``T``, but only one of them
Expand All @@ -194,7 +194,7 @@ One can construct :obj:`TypeVar`\s manually:
.. doctest::

julia> TypeVar(:V, Signed, Real, false)
Signed<:V<:Real
V<:Real

There are convenience versions that allow you to omit any of these
arguments except the ``name`` symbol.
Expand All @@ -215,20 +215,21 @@ a lot about how Julia does dispatch:

julia> methods(candid)
# 1 method for generic function "candid":
candid{T}(A::Array{T,N}, x::T) at none:1
candid{T}(A::Array{T,N<:Any}, x::T) at none:1

julia> methods(sneaky)
# 1 method for generic function "sneaky":
sneaky{T}(A::Array{T,N}, x::T) at none:1
sneaky{T}(A::Array{T,N<:Any}, x::T<:Any) at none:1

These therefore print identically, but they have very different behavior:

.. doctest::

julia> candid([1],3.2)
ERROR: MethodError: `candid` has no method matching candid(::Array{Int64,1}, ::Float64)
ERROR: MethodError: no method matching candid(::Array{Int64,1}, ::Float64)
Closest candidates are:
candid{T}(::Array{T,N}, !Matched::T)
in eval(::Module, ::Any) at ./boot.jl:237

julia> sneaky([1],3.2)
1
Expand All @@ -244,11 +245,11 @@ bound :obj:`TypeVar` objects with a hash (``#T`` instead of ``T``):

.. doctest::

julia> jl_(start(methods(candid)))
Method(sig=Tuple{Array{#T<:Any, N<:Any}, #T<:Any}, va=false, isstaged=false, tvars=#T<:Any, func=#<function>, invokes=nothing, next=nothing)
julia> jl_(first(methods(candid)))
Method(sig=Tuple{Main.#candid, Array{#T<:Any, N<:Any}, #T<:Any}, va=false, isstaged=false, tvars=#T<:Any, func=Main.candid(?), invokes=nothing, next=nothing)

julia> jl_(start(methods(sneaky)))
Method(sig=Tuple{Array{#T<:Any, N<:Any}, T<:Any}, va=false, isstaged=false, tvars=#T<:Any, func=#<function>, invokes=nothing, next=nothing)
julia> jl_(first(methods(sneaky)))
Method(sig=Tuple{Main.#sneaky, Array{#T<:Any, N<:Any}, T<:Any}, va=false, isstaged=false, tvars=#T<:Any, func=Main.sneaky(?), invokes=nothing, next=nothing)

Even though both print as ``T``, in ``sneaky`` the second ``T`` is
not bound, and hence it isn't constrained to be the same type as the
Expand Down Expand Up @@ -320,8 +321,17 @@ the type, which is an object of type :obj:`TypeName`:
cache: SimpleVector
length: Int64 135
linearcache: SimpleVector
length: Int64 18
uid: Int64 37
length: Int64 60
uid: Int64 43
mt: MethodTable
name: Symbol Array
defs: Void nothing
cache: Void nothing
cache_arg1: Void nothing
cache_targ: Void nothing
max_args: Int64 0
kwsorter: #undef
module: Module Core

In this case, the relevant field is ``primary``, which holds a
reference to the "primary" instance of the type::
Expand Down Expand Up @@ -357,20 +367,10 @@ type:
MyType{Float32,5}

julia> MyType.name.cache
svec(MyType{Float32,5},MyType{Int64,2},Evaluation succeeded, but an error occurred while showing value of type SimpleVector:
ERROR: UndefRefError: access to undefined reference
in getindex at ./essentials.jl:211
in show_delim_array at show.jl:229
in show at show.jl:257
in anonymous at show.jl:1278
in with_output_limit at ./show.jl:1255
in showlimited at show.jl:1277
in display at multimedia.jl:120
[inlined code] from multimedia.jl:151
in display at multimedia.jl:162

(The error is triggered because the cache is pre-allocated to have
length 8, but only the first two entries are populated.)
svec(MyType{Float32,5},MyType{Int64,2},#undef,#undef,#undef,#undef,#undef,#undef)

(The cache is pre-allocated to have length 8, but only the first two entries
are populated.)
Consequently, when you instantiate a parametric type, each concrete
type gets saved in a type-cache. However, instances with :obj:`TypeVar`
parameters are not cached.
Expand Down
8 changes: 4 additions & 4 deletions doc/manual/arrays.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -497,9 +497,9 @@ the name of the function to vectorize. Here is a simple example:

julia> methods(square)
# 4 methods for generic function "square":
square{T<:Number}(::AbstractArray{T<:Number,1}) at operators.jl:374
square{T<:Number}(::AbstractArray{T<:Number,2}) at operators.jl:375
square{T<:Number}(::AbstractArray{T<:Number,N}) at operators.jl:377
square{T<:Number}(x::AbstractArray{T,1}) at operators.jl:...
square{T<:Number}(x::AbstractArray{T,2}) at operators.jl:...
square{T<:Number}(x::AbstractArray{T,N<:Any}) at operators.jl:...
square(x) at none:1

julia> square([1 2 4; 5 6 7])
Expand Down Expand Up @@ -631,7 +631,7 @@ stride parameters.
0.507762 0.573567 0.220124 0.165816 0.211049 0.433277 0.539476

julia> b = sub(a, 2:2:8,2:2:4)
4×2 SubArray{Float64,2,Array{Float64,2},Tuple{StepRange{Int64,Int64},StepRange{Int64,Int64}},1}:
4×2 SubArray{Float64,2,Array{Float64,2},Tuple{StepRange{Int64,Int64},StepRange{Int64,Int64}},false}:
0.537192 0.996234
0.736979 0.228787
0.991511 0.74485
Expand Down
4 changes: 3 additions & 1 deletion doc/manual/complex-and-rational-numbers.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,8 @@ versus ``-1 + 0im`` even though ``-1 == -1 + 0im``:
julia> sqrt(-1)
ERROR: DomainError:
sqrt will only return a complex result if called with a complex argument. Try sqrt(complex(x)).
in sqrt at math.jl:146
in sqrt(::Int64) at ./math.jl:146
in eval(::Module, ::Any) at ./boot.jl:237

julia> sqrt(-1 + 0im)
0.0 + 1.0im
Expand Down Expand Up @@ -305,6 +306,7 @@ Trying to construct a :const:`NaN` rational value, however, is not:
ERROR: ArgumentError: invalid rational: zero(Int64)//zero(Int64)
in Rational{Int64}(::Int64, ::Int64) at ./rational.jl:8
in //(::Int64, ::Int64) at ./rational.jl:22
in eval(::Module, ::Any) at ./boot.jl:237

As usual, the promotion system makes interactions with other numeric
types effortless:
Expand Down
29 changes: 21 additions & 8 deletions doc/manual/constructors.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,8 @@ Now ``OrderedPair`` objects can only be constructed such that

julia> OrderedPair(2,1)
ERROR: out of order
in call at none:5
in OrderedPair(::Int64, ::Int64) at ./none:5
in eval(::Module, ::Any) at ./boot.jl:237

You can still reach in and directly change the field values to violate
this invariant, but messing around with an object's internals uninvited is
Expand Down Expand Up @@ -266,6 +267,7 @@ access to an uninitialized reference is an immediate error:

julia> z.xx
ERROR: UndefRefError: access to undefined reference
in eval(::Module, ::Any) at ./boot.jl:237

This avoids the need to continually check for ``null`` values.
However, not all object fields are references. Julia considers some
Expand Down Expand Up @@ -323,9 +325,14 @@ types of the arguments given to the constructor. Here are some examples:
Point{Float64}(1.0,2.5)

julia> Point(1,2.5)
ERROR: MethodError: `convert` has no method matching convert(::Type{Point{T<:Real}}, ::Int64, ::Float64)
This may have arisen from a call to the constructor Point{T<:Real}(...),
since type constructors fall back to convert methods.
ERROR: MethodError: no method matching Point{T<:Real}(::Int64, ::Float64)
Closest candidates are:
(!Matched::Type{BoundsError})(::ANY, ::ANY)
(!Matched::Type{TypeError})(::Any, ::Any, !Matched::Any, !Matched::Any)
(!Matched::Type{TypeConstructor})(::ANY, ::ANY)
...
in eval(::Module, ::Any) at ./boot.jl:237


## explicit T ##

Expand All @@ -334,7 +341,9 @@ types of the arguments given to the constructor. Here are some examples:

julia> Point{Int64}(1.0,2.5)
ERROR: InexactError()
in call at none:2
[inlined code] from ./int.jl:229
in Point{Int64}(::Float64, ::Float64) at ./none:2
in eval(::Module, ::Any) at ./boot.jl:237

julia> Point{Float64}(1.0,2.5)
Point{Float64}(1.0,2.5)
Expand Down Expand Up @@ -419,9 +428,13 @@ However, other similar calls still don't work:
.. doctest::

julia> Point(1.5,2)
ERROR: MethodError: `convert` has no method matching convert(::Type{Point{T<:Real}}, ::Float64, ::Int64)
This may have arisen from a call to the constructor Point{T<:Real}(...),
since type constructors fall back to convert methods.
ERROR: MethodError: no method matching Point{T<:Real}(::Float64, ::Int64)
Closest candidates are:
(!Matched::Type{BoundsError})(::ANY, ::ANY)
(!Matched::Type{TypeError})(::Any, ::Any, !Matched::Any, !Matched::Any)
(!Matched::Type{TypeConstructor})(::ANY, ::ANY)
...
in eval(::Module, ::Any) at ./boot.jl:237

For a much more general way of making all such calls work sensibly, see
:ref:`man-conversion-and-promotion`. At the risk
Expand Down
Loading

0 comments on commit ce62f34

Please sign in to comment.