Add TYPEDSIGNATURES (#72)

Author: kdheepak

src/DocStringExtensions.jl

@@ -77,7 +77,7 @@ module DocStringExtensions
 
 # Exports.
 
-export @template, FIELDS, EXPORTS, METHODLIST, IMPORTS, SIGNATURES, TYPEDEF, DOCSTRING, FUNCTIONNAME
+export @template, FIELDS, EXPORTS, METHODLIST, IMPORTS, SIGNATURES, TYPEDSIGNATURES, TYPEDEF, DOCSTRING, FUNCTIONNAME
 export README, LICENSE
 
 # Includes.

src/abbreviations.jl

@@ -303,6 +303,68 @@ function format(::MethodSignatures, buf, doc)
     end
 end
 
+
+#
+# `TypedMethodSignatures`
+#
+
+"""
+The singleton type for [`TYPEDSIGNATURES`](@ref) abbreviations.
+
+$(:FIELDS)
+"""
+struct TypedMethodSignatures <: Abbreviation end
+
+"""
+An [`Abbreviation`](@ref) for including a simplified representation of all the method
+signatures with types that match the given docstring. See [`printmethod`](@ref) for details on
+the simplifications that are applied.
+
+# Examples
+
+The generated markdown text will look similar to the following example where a function `f`
+defines method taking two positional arguments, `x` and `y`, and two keywords, `a` and the `b`.
+
+````markdown
+```julia
+f(x::Int, y::Int; a, b...)
+```
+````
+"""
+const TYPEDSIGNATURES = TypedMethodSignatures()
+
+function format(::TypedMethodSignatures, buf, doc)
+    local binding = doc.data[:binding]
+    local typesig = doc.data[:typesig]
+    local modname = doc.data[:module]
+    local func = Docs.resolve(binding)
+    local groups = methodgroups(func, typesig, modname)
+    if !isempty(groups)
+        println(buf)
+        println(buf, "```julia")
+        for group in groups
+            if length(group) == 1
+                for method in group
+                    printmethod(buf, binding, func, method, typesig)
+                    println(buf)
+                end
+            else
+                for (i, method) in enumerate(group)
+                    if i == length(group)
+                        t = typesig
+                    else
+                        t = typesig.a
+                        typesig = typesig.b
+                    end
+                    printmethod(buf, binding, func, method, t)
+                    println(buf)
+                end
+            end
+        end
+        println(buf, "\n```\n")
+    end
+end
+
 #
 # `FunctionName`
 #

src/utilities.jl

@@ -222,6 +222,58 @@ function printmethod(buffer::IOBuffer, binding::Docs.Binding, func, method::Meth
     return buffer
 end
 
+"""
+$(:TYPEDSIGNATURES)
+
+Print a simplified representation of a method signature to `buffer`. Some of these
+simplifications include:
+
+  * no `TypeVar`s;
+  * no types;
+  * no keyword default values;
+  * `?` printed where `#unused#` arguments are found.
+
+# Examples
+
+```julia
+f(x::Int; a = 1, b...) = x
+sig = printmethod(Docs.Binding(Main, :f), f, first(methods(f)))
+```
+"""
+function printmethod(buffer::IOBuffer, binding::Docs.Binding, func, method::Method, typesig)
+    # TODO: print qualified?
+    print(buffer, binding.var)
+    print(buffer, "(")
+    local args = arguments(method)
+    for (i, sym) in enumerate(args)
+        if typesig isa UnionAll
+            t = typesig.body.a.types[1]
+        else
+            t = typesig.types[i]
+        end
+        print(buffer, "$sym::$t")
+        if i != length(args)
+            print(buffer, ", ")
+        end
+    end
+    local kws = keywords(func, method)
+    if !isempty(kws)
+        print(buffer, "; ")
+        join(buffer, kws, ", ")
+    end
+    print(buffer, ")")
+    if typesig isa UnionAll
+        t = typesig.body.a
+    else
+        t = typesig
+    end
+    rt = Base.return_types(func, t)
+    if length(rt) >= 1 && rt[1] !== Nothing && rt[1] !== Union{}
+        print(buffer, " -> $(rt[1])")
+    end
+    return buffer
+end
+
 printmethod(b, f, m) = String(take!(printmethod(IOBuffer(), b, f, m)))
 
 get_method_source(m::Method) = Base.uncompressed_ast(m)

test/TestModule/M.jl

@@ -6,6 +6,8 @@ f(x) = x
 
 g(x = 1, y = 2, z = 3; kwargs...) = x
 
+h(x::Int, y::Int = 2, z::Int = 3; kwargs...) = x
+
 const A{T} = Union{Vector{T}, Matrix{T}}
 
 h_1(x::A) = x

test/tests.jl

@@ -155,6 +155,53 @@ end
             @test occursin("\n```\n", str)
         end
 
+        @testset "method signatures with types" begin
+            doc.data = Dict(
+                :binding => Docs.Binding(M, :h_1),
+                :typesig => Tuple{M.A},
+                :module => M,
+            )
+            DSE.format(DSE.TYPEDSIGNATURES, buf, doc)
+            str = String(take!(buf))
+            @test occursin("\n```julia\n", str)
+            if Sys.iswindows()
+                @test occursin("h_1(x::Union{Array{T,2}, Array{T,1}} where T) -> Union{Array{T,2}, Array{T,1}} where T", str)
+            else
+                @test occursin("h_1(x::Union{Array{T,1}, Array{T,2}} where T) -> Union{Array{T,1}, Array{T,2}} where T", str)
+            end
+            @test occursin("\n```\n", str)
+
+            doc.data = Dict(
+                :binding => Docs.Binding(M, :h),
+                :typesig => Tuple{Int, Int, Int},
+                :module => M,
+            )
+            DSE.format(DSE.TYPEDSIGNATURES, buf, doc)
+            str = String(take!(buf))
+            @test occursin("\n```julia\n", str)
+            if typeof(1) === Int64
+                @test occursin("\nh(x::Int64, y::Int64, z::Int64; kwargs...) -> Int64\n", str)
+            else
+                @test occursin("\nh(x::Int32, y::Int32, z::Int32; kwargs...) -> Int32\n", str)
+            end
+            @test occursin("\n```\n", str)
+
+            doc.data = Dict(
+                :binding => Docs.Binding(M, :h),
+                :typesig => Tuple{Int},
+                :module => M,
+            )
+            DSE.format(DSE.TYPEDSIGNATURES, buf, doc)
+            str = String(take!(buf))
+            @test occursin("\n```julia\n", str)
+            if typeof(1) === Int64
+                @test occursin("\nh(x::Int64) -> Int64\n", str)
+            else
+                @test occursin("\nh(x::Int32) -> Int32\n", str)
+            end
+            @test occursin("\n```\n", str)
+        end
+
         @testset "function names" begin
             doc.data = Dict(
                 :binding => Docs.Binding(M, :f),