Add more docstrings and fix the doctests

Author: timholy

docs/Project.toml

@@ -1,5 +1,7 @@
 [deps]
+CodeTracking = "da1fd8a2-8d9e-5ec2-8556-3022fb5608a2"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 JuliaInterpreter = "aa1ae85d-cabe-5617-a682-6adf51b2e16a"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+UUIDs = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"

docs/src/dev_reference.md

@@ -28,6 +28,7 @@ JuliaInterpreter.Compiled
 JuliaInterpreter.step_expr!
 JuliaInterpreter.finish!
 JuliaInterpreter.finish_and_return!
+JuliaInterpreter.finish_stack!
 JuliaInterpreter.get_return
 JuliaInterpreter.next_until!
 JuliaInterpreter.through_methoddef_or_done!
@@ -36,12 +37,24 @@ JuliaInterpreter.evaluate_foreigncall!
 JuliaInterpreter.maybe_evaluate_builtin
 ```
 
+## Breakpoints
+
+```@docs
+@breakpoint
+breakpoint
+enable
+disable
+remove
+```
+
 ## Types
 
 ```@docs
 JuliaInterpreter.JuliaStackFrame
 JuliaInterpreter.JuliaFrameCode
 JuliaInterpreter.JuliaProgramCounter
+JuliaInterpreter.BreakpointState
+JuliaInterpreter.BreakpointRef
 ```
 
 ## Internal storage
@@ -57,4 +70,7 @@ JuliaInterpreter.compiled_methods
 ```@docs
 JuliaInterpreter.@lookup
 JuliaInterpreter.iswrappercall
+JuliaInterpreter.isdocexpr
+JuliaInterpreter.isglobalref
+JuliaInterpreter.statementnumber
 ```

src/JuliaInterpreter.jl

@@ -391,7 +391,7 @@ julia> framecode, frameargs, lenv, argtypes = JuliaInterpreter.prepare_call(myme
 julia> framecode
 JuliaInterpreter.JuliaFrameCode(mymethod(x::Array{T,1}) where T in Main at none:1, CodeInfo(
 1 ─     return 1
-), Core.TypeMapEntry[#undef], BitSet([]), false, false, true)
+), Union{Compiled, TypeMapEntry}[#undef], JuliaInterpreter.BreakpointState[#undef], BitSet([]), false, false, true)
 
 julia> frameargs
 2-element Array{Any,1}:
@@ -916,9 +916,9 @@ mymethod (generic function with 1 method)
 
 julia> JuliaInterpreter.enter_call_expr(:(\$mymethod(1)))
 JuliaStackFrame(JuliaInterpreter.JuliaFrameCode(mymethod(x) in Main at none:1, CodeInfo(
-1 ─ %1 = (\$(QuoteNode(+)))(x, 1)
+1 ─ %1 = ($(QuoteNode(+)))(x, 1)
 └──      return %1
-), Core.TypeMapEntry[#undef, #undef], BitSet([1]), false, false, true), Union{Nothing, Some{Any}}[Some(mymethod), Some(1)], Any[#undef, #undef], Any[], Int64[], Base.RefValue{Any}(nothing), Base.RefValue{JuliaInterpreter.JuliaProgramCounter}(JuliaProgramCounter(1)), Dict{Symbol,Int64}(), Any[])
+), Union{Compiled, TypeMapEntry}[#undef, #undef], JuliaInterpreter.BreakpointState[#undef, #undef], BitSet([1]), false, false, true), Union{Nothing, Some{Any}}[Some(mymethod), Some(1)], Any[#undef, #undef], Any[], Int64[], Base.RefValue{Any}(nothing), Base.RefValue{JuliaInterpreter.JuliaProgramCounter}(JuliaProgramCounter(1)), Dict(Symbol("#self#")=>1,:x=>2), Any[])
 
 julia> mymethod(x::Vector{T}) where T = 1
 mymethod (generic function with 2 methods)
@@ -931,7 +931,7 @@ julia> a = [1.0, 2.0]
 julia> JuliaInterpreter.enter_call_expr(:(\$mymethod(\$a)))
 JuliaStackFrame(JuliaInterpreter.JuliaFrameCode(mymethod(x::Array{T,1}) where T in Main at none:1, CodeInfo(
 1 ─     return 1
-), Core.TypeMapEntry[#undef], BitSet([]), false, false, true), Union{Nothing, Some{Any}}[Some(mymethod), Some([1.0, 2.0])], Any[#undef], Any[Float64], Int64[], Base.RefValue{Any}(nothing), Base.RefValue{JuliaInterpreter.JuliaProgramCounter}(JuliaProgramCounter(1)), Dict{Symbol,Int64}(), Any[])
+), Union{Compiled, TypeMapEntry}[#undef], JuliaInterpreter.BreakpointState[#undef], BitSet([]), false, false, true), Union{Nothing, Some{Any}}[Some(mymethod), Some([1.0, 2.0])], Any[#undef], Any[Float64], Int64[], Base.RefValue{Any}(nothing), Base.RefValue{JuliaInterpreter.JuliaProgramCounter}(JuliaProgramCounter(1)), Dict(Symbol("#self#")=>1,:x=>2), Any[])
 ```
 
 See [`enter_call`](@ref) for a similar approach not based on expressions.
@@ -959,15 +959,15 @@ julia> JuliaInterpreter.enter_call(mymethod, 1)
 JuliaStackFrame(JuliaInterpreter.JuliaFrameCode(mymethod(x) in Main at none:1, CodeInfo(
 1 ─ %1 = ($(QuoteNode(+)))(x, 1)
 └──      return %1
-), Core.TypeMapEntry[#undef, #undef], BitSet([1]), false, false, true), Union{Nothing, Some{Any}}[Some(mymethod), Some(1)], Any[#undef, #undef], Any[], Int64[], Base.RefValue{Any}(nothing), Base.RefValue{JuliaInterpreter.JuliaProgramCounter}(JuliaProgramCounter(1)), Dict{Symbol,Int64}(), Any[])
+), Union{Compiled, TypeMapEntry}[#undef, #undef], JuliaInterpreter.BreakpointState[#undef, #undef], BitSet([1]), false, false, true), Union{Nothing, Some{Any}}[Some(mymethod), Some(1)], Any[#undef, #undef], Any[], Int64[], Base.RefValue{Any}(nothing), Base.RefValue{JuliaInterpreter.JuliaProgramCounter}(JuliaProgramCounter(1)), Dict(Symbol("#self#")=>1,:x=>2), Any[])
 
 julia> mymethod(x::Vector{T}) where T = 1
 mymethod (generic function with 2 methods)
 
 julia> JuliaInterpreter.enter_call(mymethod, [1.0, 2.0])
 JuliaStackFrame(JuliaInterpreter.JuliaFrameCode(mymethod(x::Array{T,1}) where T in Main at none:1, CodeInfo(
 1 ─     return 1
-), Core.TypeMapEntry[#undef], BitSet([]), false, false, true), Union{Nothing, Some{Any}}[Some(mymethod), Some([1.0, 2.0])], Any[#undef], Any[Float64], Int64[], Base.RefValue{Any}(nothing), Base.RefValue{JuliaInterpreter.JuliaProgramCounter}(JuliaProgramCounter(1)), Dict{Symbol,Int64}(), Any[])
+), Union{Compiled, TypeMapEntry}[#undef], JuliaInterpreter.BreakpointState[#undef], BitSet([]), false, false, true), Union{Nothing, Some{Any}}[Some(mymethod), Some([1.0, 2.0])], Any[#undef], Any[Float64], Int64[], Base.RefValue{Any}(nothing), Base.RefValue{JuliaInterpreter.JuliaProgramCounter}(JuliaProgramCounter(1)), Dict(Symbol("#self#")=>1,:x=>2), Any[])
 ```
 
 For a `@generated` function you can use `enter_call((f, true), args...; kwargs...)`

src/breakpoints.jl

@@ -109,17 +109,51 @@ end
 breakpoint!(frame::JuliaStackFrame, pc=frame.pc[], condition::Condition=nothing) =
     breakpoint!(frame.code, pc, condition)
 
+"""
+    enable(bp::BreakpointRef)
+
+Enable breakpoint `bp`.
+"""
 enable(bp::BreakpointRef)  = bp[] = true
+
+"""
+    disable(bp::BreakpointRef)
+
+Disable breakpoint `bp`. Disabled breakpoints can be re-enabled with [`enable`](@ref).
+"""
 disable(bp::BreakpointRef) = bp[] = false
+
+"""
+    remove(bp::BreakpointRef)
+
+Remove (delete) breakpoint `bp`. Removed breakpoints cannot be re-enabled.
+"""
 function remove(bp::BreakpointRef)
     idx = findfirst(isequal(bp), _breakpoints)
     deleteat!(_breakpoints, idx)
     bp.framecode.breakpoints[bp.stmtidx] = BreakpointState(false, falsecondition)
     return nothing
 end
 
+"""
+    enable()
+
+Enable all breakpoints.
+"""
 enable() = for bp in _breakpoints enable(bp) end
+
+"""
+    disable()
+
+Disable all breakpoints.
+"""
 disable() = for bp in _breakpoints disable(bp) end
+
+"""
+    remove()
+
+Remove all breakpoints.
+"""
 function remove()
     for bp in _breakpoints
         bp.framecode.breakpoints[bp.stmtidx] = BreakpointState(false, falsecondition)