Documentation fixes (#19)

Author: timholy

Project.toml

@@ -1,7 +1,7 @@
 name = "MethodAnalysis"
 uuid = "85b6ec6f-f7df-4429-9514-a64bcd9ee824"
 authors = ["Tim Holy <[email protected]>"]
-version = "0.4.2"
+version = "0.4.3"
 
 [deps]
 AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"

docs/src/index.md

@@ -52,7 +52,7 @@ julia> foo(::AbstractVector) = 1
 foo (generic function with 1 method)
 
 julia> methodinstance(foo, (Vector{Int},))   # we haven't called it yet, so it's not compiled
-MethodInstance for foo(::Vector{Int64})
+
 
 julia> foo([1,2])
 1
@@ -82,7 +82,7 @@ We checked that the length was 2, rather than 1, because the first parameter is
 
 ```jldoctest findfirst
 julia> mis[1].specTypes
-Tuple{typeof(findfirst),BitVector}
+Tuple{typeof(findfirst), BitVector}
 ```
 
 There's also a convenience shortcut:
@@ -97,10 +97,13 @@ Let's see all the compiled instances of `Base.setdiff` and their immediate calle
 
 ```jldoctest; setup=(using MethodAnalysis)
 julia> direct_backedges(setdiff)
-3-element Vector{Any}:
- MethodInstance for setdiff(::Base.KeySet{Any,Dict{Any,Any}}, ::Base.KeySet{Any,Dict{Any,Any}}) => MethodInstance for keymap_merge(::Dict{Char,Any}, ::Dict{Any,Any})
- MethodInstance for setdiff(::Base.KeySet{Any,Dict{Any,Any}}, ::Base.KeySet{Any,Dict{Any,Any}}) => MethodInstance for keymap_merge(::Any, ::Dict{Any,Any})
-                           MethodInstance for setdiff(::Vector{Base.UUID}, ::Vector{Base.UUID}) => MethodInstance for deps_graph(::Pkg.Types.Context, ::Dict{Base.UUID,String}, ::Dict{Base.UUID,Pkg.Types.VersionSpec}, ::Dict{Base.UUID,Pkg.Resolve.Fixed})
+6-element Vector{Any}:
+     MethodInstance for setdiff(::Base.KeySet{Any, Dict{Any, Any}}, ::Base.KeySet{Any, Dict{Any, Any}}) => MethodInstance for keymap_merge(::Dict{Char, Any}, ::Dict{Any, Any})
+     MethodInstance for setdiff(::Base.KeySet{Any, Dict{Any, Any}}, ::Base.KeySet{Any, Dict{Any, Any}}) => MethodInstance for keymap_merge(::Dict{Char, Any}, ::Union{Dict{Any, Any}, Dict{Char, Any}})
+   MethodInstance for setdiff(::Base.KeySet{Char, Dict{Char, Any}}, ::Base.KeySet{Any, Dict{Any, Any}}) => MethodInstance for keymap_merge(::Dict{Char, Any}, ::Union{Dict{Any, Any}, Dict{Char, Any}})
+   MethodInstance for setdiff(::Base.KeySet{Any, Dict{Any, Any}}, ::Base.KeySet{Char, Dict{Char, Any}}) => MethodInstance for keymap_merge(::Dict{Char, Any}, ::Union{Dict{Any, Any}, Dict{Char, Any}})
+ MethodInstance for setdiff(::Base.KeySet{Char, Dict{Char, Any}}, ::Base.KeySet{Char, Dict{Char, Any}}) => MethodInstance for keymap_merge(::Dict{Char, Any}, ::Union{Dict{Any, Any}, Dict{Char, Any}})
+                                   MethodInstance for setdiff(::Vector{Base.UUID}, ::Vector{Base.UUID}) => MethodInstance for deps_graph(::Pkg.Types.Context, ::Dict{Base.UUID, String}, ::Dict{Base.UUID, Pkg.Types.VersionSpec}, ::Dict{Base.UUID, Pkg.Resolve.Fixed})
 ```
 
 ### Printing backedges as a tree
@@ -114,9 +117,12 @@ MethodInstance for findfirst(::BitVector)
 julia> MethodAnalysis.print_tree(mi)
 MethodInstance for findfirst(::BitVector)
 ├─ MethodInstance for prune_graph!(::Graph)
-│  └─ MethodInstance for #simplify_graph!#111(::Bool, ::typeof(simplify_graph!), ::Graph, ::Set{Int64})
+│  └─ MethodInstance for var"#simplify_graph!#111"(::Bool, ::typeof(simplify_graph!), ::Graph, ::Set{Int64})
 │     └─ MethodInstance for simplify_graph!(::Graph, ::Set{Int64})
 │        └─ MethodInstance for simplify_graph!(::Graph)
+│           ├─ MethodInstance for trigger_failure!(::Graph, ::Vector{Int64}, ::Tuple{Int64, Int64})
+│           │  ⋮
+│           │
 │           └─ MethodInstance for resolve_versions!(::Context, ::Vector{PackageSpec})
 │              ⋮
 │
@@ -136,7 +142,7 @@ MethodInstance for findfirst(::BitVector)
       │
       └─ MethodInstance for maxsum(::Graph)
          └─ MethodInstance for resolve(::Graph)
-            ├─ MethodInstance for trigger_failure!(::Graph, ::Vector{Int64}, ::Tuple{Int64,Int64})
+            ├─ MethodInstance for trigger_failure!(::Graph, ::Vector{Int64}, ::Tuple{Int64, Int64})
             │  ⋮
             │
             └─ MethodInstance for resolve_versions!(::Context, ::Vector{PackageSpec})
@@ -185,3 +191,9 @@ call_type
 findcallers
 worlds
 ```
+
+### types
+
+```@docs
+MethodAnalysis.CallMatch
+```

src/findcallers.jl

@@ -29,6 +29,17 @@ function get_typed_instances(@nospecialize(tt), method::Method; world=typemax(UI
     return get_typed_instances!(Tuple{CodeInfo,Core.SimpleVector}[], tt, method, world, interp)
 end
 
+"""
+    CallMatch
+
+A structure to summarize a "matching" caller/callee pair. The fields are:
+
+- `mi`: the `MethodInstance` for the caller
+- `src`: its corresponding `CodeInfo`
+- `sparams`: the type parameters for the caller, given `mi`'s signature (alternatively use `mi.sparam_vals`)
+- `line`: the statement number (in SSAValue sense) on which the call occurs
+- `argtypes`: the caller's inferred types passed as arguments to the callee
+"""
 struct CallMatch
     mi::MethodInstance
     src::CodeInfo
@@ -50,8 +61,7 @@ Optionally pass `nothing` for `argmatch` to allow any calls to `f`.
 
 `callhead` controls whether you're looking for an ordinary (`:call`) or a splatted (varargs) call (`:iterate`).
 
-`callers` is a vector of tuples `t`, where `t[1]` is the `MethodInstance`, `t[2]` is the corresponding `CodeInfo`,
-`t[3]` is the statement number on which the call occurs, and `t[4]` holds the inferred argument types.
+`callers` is a vector of [`CallMatch`](@ref) objects.
 
 # Examples
 
@@ -76,6 +86,7 @@ callers2 = findcallers(f, argtyps->length(argtyps) == 1 && argtyps[1] === Intege
 
 # Get the splat call
 callers3 = findcallers(f, argtyps->length(argtyps) == 1 && argtyps[1] === Vector{Any}, mis; callhead=:iterate)
+```
 
 !!! compat
     `findcallers` is available on Julia 1.6 and higher