From 0d89bb82e85c3de52b69e9fe9f4d97aa9d682508 Mon Sep 17 00:00:00 2001 From: unnamedunknownusername <109242984+unnamedunknownusername@users.noreply.github.com> Date: Wed, 17 May 2023 12:27:51 +0200 Subject: [PATCH 1/6] add WIP TypedMethodList --- src/abbreviations.jl | 110 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) diff --git a/src/abbreviations.jl b/src/abbreviations.jl index a40a9de..673c6b3 100644 --- a/src/abbreviations.jl +++ b/src/abbreviations.jl @@ -281,6 +281,116 @@ function format(::MethodList, buf, doc) end + + + + + + +# +# `TypedMethodList` +# + +""" +The singleton type for [`TYPEDMETHODLIST`](@ref) abbreviations. + +$(:FIELDS) +""" +struct TypedMethodList <: Abbreviation end + +""" +An [`Abbreviation`](@ref) for including a list of all the methods that match a documented +`Method`, `Function`, or `DataType` within the current module. + +# Examples + +The generated markdown text will look similar to the following example where a function +`f` defines two different methods (one that takes a number, and the other a string): + +````markdown +```julia +f(x::Int, y::Int; a, b...) +``` + +defined at [`:`](). + +```julia +f(x::Int, y::String; a, b...) +``` + +defined at [`:`](). +```` +""" +const TYPEDMETHODLIST = TypedMethodList() + +function format(::MethodList, 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; exact = false) + if !isempty(groups) + + #START OF COPIED CODE FROM TYPEDMETHODSIGNATURES + group = groups[end] + println(buf) + println(buf, "```julia") + for (i, method) in enumerate(group) + N = length(arguments(method)) + # return a list of tuples that represent type signatures + tuples = find_tuples(typesig) + # The following will find the tuple that matches the number of arguments in the function + # ideally we would check that the method signature matches the Tuple{...} signature + # but that is not straightforward because of how expressive Julia can be + function f(t) + if t isa DataType + return t <: Tuple && length(t.types) == N + elseif t isa UnionAll + return f(t.body) + else + return false + end + end + + @static if Sys.iswindows() && VERSION < v"1.8" + t = tuples[findlast(f, tuples)] + else + t = tuples[findfirst(f, tuples)] + end + printmethod(buf, binding, func, method, t) + + println(buf) + end + #END OF COPIED CODE FROM TYPEDMETHODSIGNATURES + + println(buf, "```\n") + if !isempty(group) + local method = group[1] + local file = string(method.file) + local line = method.line + local path = cleanpath(file) + local URL = url(method) + isempty(URL) || println(buf, "defined at [`$path:$line`]($URL).") + end + println(buf) + end + return nothing +end + + + + + + + + + + + + + + + # # `MethodSignatures` # From 8bfea79a65cff07ecd3ae16b6a766a01ef20af57 Mon Sep 17 00:00:00 2001 From: unnamedunknownusername <109242984+unnamedunknownusername@users.noreply.github.com> Date: Wed, 17 May 2023 12:29:45 +0200 Subject: [PATCH 2/6] fix docstring --- src/abbreviations.jl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/abbreviations.jl b/src/abbreviations.jl index 673c6b3..b7b8105 100644 --- a/src/abbreviations.jl +++ b/src/abbreviations.jl @@ -309,13 +309,13 @@ The generated markdown text will look similar to the following example where a f ````markdown ```julia -f(x::Int, y::Int; a, b...) +f(x::Int) ``` defined at [`:`](). ```julia -f(x::Int, y::String; a, b...) +f(y::String) ``` defined at [`:`](). From f0108b11c9db681670ecce1cb34e9bbf13f7aabe Mon Sep 17 00:00:00 2001 From: unnamedunknownusername <109242984+unnamedunknownusername@users.noreply.github.com> Date: Sun, 21 May 2023 12:54:09 +0200 Subject: [PATCH 3/6] pull out common code into a function --- src/abbreviations.jl | 125 ++++++++++++++++++++++--------------------- 1 file changed, 65 insertions(+), 60 deletions(-) diff --git a/src/abbreviations.jl b/src/abbreviations.jl index b7b8105..a853aaf 100644 --- a/src/abbreviations.jl +++ b/src/abbreviations.jl @@ -330,39 +330,39 @@ function format(::MethodList, buf, doc) local func = Docs.resolve(binding) local groups = methodgroups(func, typesig, modname; exact = false) if !isempty(groups) - - #START OF COPIED CODE FROM TYPEDMETHODSIGNATURES - group = groups[end] - println(buf) - println(buf, "```julia") - for (i, method) in enumerate(group) - N = length(arguments(method)) - # return a list of tuples that represent type signatures - tuples = find_tuples(typesig) - # The following will find the tuple that matches the number of arguments in the function - # ideally we would check that the method signature matches the Tuple{...} signature - # but that is not straightforward because of how expressive Julia can be - function f(t) - if t isa DataType - return t <: Tuple && length(t.types) == N - elseif t isa UnionAll - return f(t.body) - else - return false - end - end + printTypedSignaturesForMethod(groups,buf,typesig) + # #START OF COPIED CODE FROM TYPEDMETHODSIGNATURES + # group = groups[end] + # println(buf) + # println(buf, "```julia") + # for (i, method) in enumerate(group) + # N = length(arguments(method)) + # # return a list of tuples that represent type signatures + # tuples = find_tuples(typesig) + # # The following will find the tuple that matches the number of arguments in the function + # # ideally we would check that the method signature matches the Tuple{...} signature + # # but that is not straightforward because of how expressive Julia can be + # function f(t) + # if t isa DataType + # return t <: Tuple && length(t.types) == N + # elseif t isa UnionAll + # return f(t.body) + # else + # return false + # end + # end + + # @static if Sys.iswindows() && VERSION < v"1.8" + # t = tuples[findlast(f, tuples)] + # else + # t = tuples[findfirst(f, tuples)] + # end + # printmethod(buf, binding, func, method, t) + + # println(buf) + # end + # #END OF COPIED CODE FROM TYPEDMETHODSIGNATURES - @static if Sys.iswindows() && VERSION < v"1.8" - t = tuples[findlast(f, tuples)] - else - t = tuples[findfirst(f, tuples)] - end - printmethod(buf, binding, func, method, t) - - println(buf) - end - #END OF COPIED CODE FROM TYPEDMETHODSIGNATURES - println(buf, "```\n") if !isempty(group) local method = group[1] @@ -379,7 +379,39 @@ end +function printTypedSignaturesForMethod(groups,buf,typesig) + #START OF COPIED CODE FROM TYPEDMETHODSIGNATURES ---> CAN RMEOVE THIS COMMENT BEFORE MERGING + group = groups[end] + println(buf) + println(buf, "```julia") + for (i, method) in enumerate(group) + N = length(arguments(method)) + # return a list of tuples that represent type signatures + tuples = find_tuples(typesig) + # The following will find the tuple that matches the number of arguments in the function + # ideally we would check that the method signature matches the Tuple{...} signature + # but that is not straightforward because of how expressive Julia can be + function f(t) + if t isa DataType + return t <: Tuple && length(t.types) == N + elseif t isa UnionAll + return f(t.body) + else + return false + end + end + @static if Sys.iswindows() && VERSION < v"1.8" + t = tuples[findlast(f, tuples)] + else + t = tuples[findfirst(f, tuples)] + end + printmethod(buf, binding, func, method, t) + println(buf) + end + + #END OF COPIED CODE FROM TYPEDMETHODSIGNATURES ---> CAN RMEOVE THIS COMMENT BEFORE MERGING +end @@ -480,34 +512,7 @@ function format(::TypedMethodSignatures, buf, doc) # and whether default arguments are used local groups = methodgroups(func, typesig, modname) if !isempty(groups) - group = groups[end] - println(buf) - println(buf, "```julia") - for (i, method) in enumerate(group) - N = length(arguments(method)) - # return a list of tuples that represent type signatures - tuples = find_tuples(typesig) - # The following will find the tuple that matches the number of arguments in the function - # ideally we would check that the method signature matches the Tuple{...} signature - # but that is not straightforward because of how expressive Julia can be - function f(t) - if t isa DataType - return t <: Tuple && length(t.types) == N - elseif t isa UnionAll - return f(t.body) - else - return false - end - end - - @static if Sys.iswindows() && VERSION < v"1.8" - t = tuples[findlast(f, tuples)] - else - t = tuples[findfirst(f, tuples)] - end - printmethod(buf, binding, func, method, t) - println(buf) - end + printTypedSignaturesForMethod(groups,buf,typesig) println(buf, "\n```\n") end end From 674d1eab3c61e56d0b06b431d3eb685f6877b22f Mon Sep 17 00:00:00 2001 From: unnamedunknownusername <109242984+unnamedunknownusername@users.noreply.github.com> Date: Sat, 27 May 2023 16:58:23 +0200 Subject: [PATCH 4/6] fix indentation --- src/abbreviations.jl | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/abbreviations.jl b/src/abbreviations.jl index a853aaf..a54d042 100644 --- a/src/abbreviations.jl +++ b/src/abbreviations.jl @@ -361,9 +361,11 @@ function format(::MethodList, buf, doc) # println(buf) # end + # println(buf, "```\n") # #END OF COPIED CODE FROM TYPEDMETHODSIGNATURES - println(buf, "```\n") + + if !isempty(group) local method = group[1] local file = string(method.file) @@ -409,7 +411,8 @@ function printTypedSignaturesForMethod(groups,buf,typesig) printmethod(buf, binding, func, method, t) println(buf) end - + println(buf, "```\n") + #END OF COPIED CODE FROM TYPEDMETHODSIGNATURES ---> CAN RMEOVE THIS COMMENT BEFORE MERGING end @@ -513,7 +516,7 @@ function format(::TypedMethodSignatures, buf, doc) local groups = methodgroups(func, typesig, modname) if !isempty(groups) printTypedSignaturesForMethod(groups,buf,typesig) - println(buf, "\n```\n") + end end From 2bc0fc1a7adc089401b1913fc813bff42997ae95 Mon Sep 17 00:00:00 2001 From: unnamedunknownusername <109242984+unnamedunknownusername@users.noreply.github.com> Date: Sat, 27 May 2023 16:58:37 +0200 Subject: [PATCH 5/6] Update tests.jl add testset for typed method list --- test/tests.jl | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/test/tests.jl b/test/tests.jl index 19ef1ed..3558256 100644 --- a/test/tests.jl +++ b/test/tests.jl @@ -131,6 +131,24 @@ end @test occursin(joinpath("test", "TestModule", "M.jl"), str) end + + # START OF NEW TESTS FOR TYPED METHOD LIST + @testset "method lists wih types" begin + doc.data = Dict( + :binding => Docs.Binding(M, :f), + :typesig => Tuple{Any}, + :module => M, + ) + with_test_repo() do + DSE.format(METHODLIST, buf, doc) + end + str = String(take!(buf)) + @test occursin("```julia", str) + @test occursin("f(x)", str) + @test occursin(joinpath("test", "TestModule", "M.jl"), str) + end + # END OF NEW TESTS FOR TYPED METHOD LIST + @testset "method signatures" begin doc.data = Dict( :binding => Docs.Binding(M, :f), From 79fa5aa93d371038b923ea228ed1cc650c913d66 Mon Sep 17 00:00:00 2001 From: unnamedunknownusername <109242984+unnamedunknownusername@users.noreply.github.com> Date: Sat, 27 May 2023 17:03:18 +0200 Subject: [PATCH 6/6] add test for exported function --- src/abbreviations.jl | 25 +++++++++++++++---------- test/tests.jl | 2 +- 2 files changed, 16 insertions(+), 11 deletions(-) diff --git a/src/abbreviations.jl b/src/abbreviations.jl index a54d042..9ee49a1 100644 --- a/src/abbreviations.jl +++ b/src/abbreviations.jl @@ -386,7 +386,9 @@ function printTypedSignaturesForMethod(groups,buf,typesig) group = groups[end] println(buf) - println(buf, "```julia") + println(buf, "```julia") #start the markdown juia code block + + for (i, method) in enumerate(group) N = length(arguments(method)) # return a list of tuples that represent type signatures @@ -403,16 +405,19 @@ function printTypedSignaturesForMethod(groups,buf,typesig) return false end end - @static if Sys.iswindows() && VERSION < v"1.8" - t = tuples[findlast(f, tuples)] - else - t = tuples[findfirst(f, tuples)] - end - printmethod(buf, binding, func, method, t) - println(buf) + + + @static if Sys.iswindows() && VERSION < v"1.8" + t = tuples[findlast(f, tuples)] + else + t = tuples[findfirst(f, tuples)] + end + printmethod(buf, binding, func, method, t) + println(buf) end - println(buf, "```\n") - + + println(buf, "```\n") #end the markdown juia code block + #END OF COPIED CODE FROM TYPEDMETHODSIGNATURES ---> CAN RMEOVE THIS COMMENT BEFORE MERGING end diff --git a/test/tests.jl b/test/tests.jl index 3558256..a1ee1b9 100644 --- a/test/tests.jl +++ b/test/tests.jl @@ -127,7 +127,7 @@ end end str = String(take!(buf)) @test occursin("```julia", str) - @test occursin("f(x)", str) + @test occursin("f(x::Any)", str) @test occursin(joinpath("test", "TestModule", "M.jl"), str) end