From 08791b4a708ca53bf330a519946f682b5d2c51dd Mon Sep 17 00:00:00 2001 From: Reuben Gardos Reid <5456207+ReubenJ@users.noreply.github.com> Date: Thu, 30 Oct 2025 17:41:30 +0100 Subject: [PATCH 1/2] Add test for `TypedMethodSignatures(false)` The behavior should be the same as `TypedMethodSignatures(true)` but omitting return types. --- test/tests.jl | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/test/tests.jl b/test/tests.jl index c399e79..33adebb 100644 --- a/test/tests.jl +++ b/test/tests.jl @@ -455,6 +455,81 @@ end end + @testset "method signatures with types (no return type)" begin + doc.data = Dict( + :binding => Docs.Binding(M, :h_1), + :typesig => Tuple{M.A}, + :module => M, + ) + DSE.format(DSE.TypedMethodSignatures(false), buf, doc) + str = String(take!(buf)) + @test occursin("\n```julia\n", str) + f = str -> replace(str, " " => "") + str = f(str) + if Sys.iswindows() && VERSION < v"1.8" + @test occursin(f("h_1(x::Union{Array{T,4}, Array{T,3}} where T)"), str) + else + @test occursin(f("h_1(x::Union{Array{T,3}, Array{T,4}} where T)"), str) + end + @test !occursin("->", str) + @test occursin("\n```\n", str) + + + doc.data = Dict( + :binding => Docs.Binding(M, :g_2), + :typesig => Tuple{String}, + :module => M, + ) + DSE.format(DSE.TypedMethodSignatures(false), buf, doc) + str = String(take!(buf)) + @test occursin("\n```julia\n", str) + @test occursin("\ng_2(x::String)", str) + @test occursin("\n```\n", str) + + doc.data = Dict( + :binding => Docs.Binding(M, :h), + :typesig => Tuple{Int,Int,Int}, + :module => M, + ) + DSE.format(DSE.TypedMethodSignatures(false), 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...)\n", str) + else + @test occursin("\nh(x::Int32, y::Int32, z::Int32; kwargs...)\n", str) + end + @test occursin("\n```\n", str) + + doc.data = Dict( + :binding => Docs.Binding(M, :h), + :typesig => Tuple{Int}, + :module => M, + ) + DSE.format(DSE.TypedMethodSignatures(false), buf, doc) + str = String(take!(buf)) + @test occursin("\n```julia\n", str) + if typeof(1) === Int64 + # On 1.10+, automatically generated methods have keywords in the metadata, + # hence the display difference between Julia versions. + if VERSION >= v"1.10" + @test occursin("\nh(x::Int64; ...)\n", str) + else + @test occursin("\nh(x::Int64)\n", str) + end + else + # On 1.10+, automatically generated methods have keywords in the metadata, + # hence the display difference between Julia versions. + if VERSION >= v"1.10" + @test occursin("\nh(x::Int32; ...)\n", str) + else + @test occursin("\nh(x::Int32)\n", str) + end + end + @test occursin("\n```\n", str) + + end + @testset "function names" begin doc.data = Dict( :binding => Docs.Binding(M, :f), From 649f56dc7c424bab80e7a6e6e9c1e880ba9e4f55 Mon Sep 17 00:00:00 2001 From: Reuben Gardos Reid <5456207+ReubenJ@users.noreply.github.com> Date: Thu, 30 Oct 2025 17:45:08 +0100 Subject: [PATCH 2/2] Implement `TypedMethodSignatures(::Bool)` Adds a field to `TypedMethodSignatures` to configure whether to display return types or not. --- src/abbreviations.jl | 19 ++++++++++++++----- src/utilities.jl | 23 ++++++++++++++++++----- 2 files changed, 32 insertions(+), 10 deletions(-) diff --git a/src/abbreviations.jl b/src/abbreviations.jl index a40a9de..00365a8 100644 --- a/src/abbreviations.jl +++ b/src/abbreviations.jl @@ -336,17 +336,25 @@ end # """ -The singleton type for [`TYPEDSIGNATURES`](@ref) abbreviations. +The type for [`TYPEDSIGNATURES`](@ref) abbreviations. $(:FIELDS) """ -struct TypedMethodSignatures <: Abbreviation end +struct TypedMethodSignatures <: Abbreviation + return_types::Bool +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. +!!! tip "Disabling the Return Type" + In many codebases the return types are not annotated meaning the return + type is printed as `Any`. To reduce clutter, the return type may be omitted by + calling [`TypedMethodSignatures`](@ref) and passing `false` to its constructor: + `\$(DocStringExtensions.TypedMethodSignatures(false))`. + # Examples The generated markdown text will look similar to the following example where a function `f` @@ -358,9 +366,9 @@ f(x::Int, y::Int; a, b...) ``` ```` """ -const TYPEDSIGNATURES = TypedMethodSignatures() +const TYPEDSIGNATURES = TypedMethodSignatures(true) -function format(::TypedMethodSignatures, buf, doc) +function format(tms::TypedMethodSignatures, buf, doc) local binding = doc.data[:binding] local typesig = doc.data[:typesig] local modname = doc.data[:module] @@ -395,7 +403,8 @@ function format(::TypedMethodSignatures, buf, doc) else t = tuples[findfirst(f, tuples)] end - printmethod(buf, binding, func, method, t) + printmethod(buf, binding, func, method, t; + print_return_types=tms.return_types) println(buf) end println(buf, "\n```\n") diff --git a/src/utilities.jl b/src/utilities.jl index baff0a5..9f1ae71 100644 --- a/src/utilities.jl +++ b/src/utilities.jl @@ -338,7 +338,7 @@ 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) +function printmethod(buffer::IOBuffer, binding::Docs.Binding, func, method::Method, typesig; print_return_types=true) # TODO: print qualified? local args = string.(arguments(method)) local kws = string.(keywords(func, method)) @@ -397,11 +397,24 @@ function printmethod(buffer::IOBuffer, binding::Docs.Binding, func, method::Meth end rt = Base.return_types(func, typesig) + return_type_string = if ( + print_return_types && + length(rt) >= 1 && + rt[1] !== Nothing && + rt[1] !== Union{} + ) + " -> $(rt[1])" + else + "" + end - return printmethod_format(buffer, string(binding.var), args, string.(kws); - return_type = - length(rt) >= 1 && rt[1] !== Nothing && rt[1] !== Union{} ? - " -> $(rt[1])" : "") + return printmethod_format( + buffer, + string(binding.var), + args, + string.(kws); + return_type=return_type_string + ) end printmethod(b, f, m) = String(take!(printmethod(IOBuffer(), b, f, m)))