Skip to content

Commit de0f36b

Browse files
JamesWrigleyJamesWrigley
committed
Combine TypedMethodSignatures and MethodSignatures
1 parent 594593e commit de0f36b

File tree

4 files changed

+59
-80
lines changed

4 files changed

+59
-80
lines changed

‎src/abbreviations.jl‎

Lines changed: 12 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -290,7 +290,12 @@ The singleton type for [`SIGNATURES`](@ref) abbreviations.
290290
291291
$(:FIELDS)
292292
"""
293-
struct MethodSignatures <: Abbreviation end
293+
struct MethodSignatures <: Abbreviation
294+
expr::Union{Nothing, Expr}
295+
print_types::Bool
296+
end
297+
298+
interpolation(ms::MethodSignatures, expr) = MethodSignatures(expr, ms.print_types)
294299

295300
"""
296301
An [`Abbreviation`](@ref) for including a simplified representation of all the method
@@ -308,43 +313,7 @@ f(x, y; a, b...)
308313
```
309314
````
310315
"""
311-
const SIGNATURES = MethodSignatures()
312-
313-
function format(::MethodSignatures, buf, doc)
314-
local binding = doc.data[:binding]
315-
local typesig = doc.data[:typesig]
316-
local modname = doc.data[:module]
317-
local func = Docs.resolve(binding)
318-
local groups = methodgroups(func, typesig, modname)
319-
320-
if !isempty(groups)
321-
println(buf)
322-
println(buf, "```julia")
323-
for group in groups
324-
for method in group
325-
printmethod(buf, binding, func, method)
326-
println(buf)
327-
end
328-
end
329-
println(buf, "\n```\n")
330-
end
331-
end
332-
333-
334-
#
335-
# `TypedMethodSignatures`
336-
#
337-
338-
"""
339-
The singleton type for [`TYPEDSIGNATURES`](@ref) abbreviations.
340-
341-
$(:FIELDS)
342-
"""
343-
struct TypedMethodSignatures <: Abbreviation
344-
expr::Union{Nothing, Expr}
345-
end
346-
347-
interpolation(::TypedMethodSignatures, expr) = TypedMethodSignatures(expr)
316+
const SIGNATURES = MethodSignatures(nothing, false)
348317

349318
"""
350319
An [`Abbreviation`](@ref) for including a simplified representation of all the method
@@ -362,9 +331,9 @@ f(x::Int, y::Int; a, b...)
362331
```
363332
````
364333
"""
365-
const TYPEDSIGNATURES = TypedMethodSignatures(nothing)
334+
const TYPEDSIGNATURES = MethodSignatures(nothing, true)
366335

367-
function format(x::TypedMethodSignatures, buf, doc)
336+
function format(ms::MethodSignatures, buf, doc)
368337
binding = doc.data[:binding]
369338
typesig = doc.data[:typesig]
370339
modname = doc.data[:module]
@@ -376,7 +345,8 @@ function format(x::TypedMethodSignatures, buf, doc)
376345
groups = methodgroups(func, typesig, modname)
377346
if !isempty(groups)
378347
group = groups[end]
379-
ast_info = parse_call(x.expr)
348+
ast_info = parse_call(ms.expr)
349+
380350
println(buf)
381351
println(buf, "```julia")
382352

@@ -403,7 +373,7 @@ function format(x::TypedMethodSignatures, buf, doc)
403373
t = tuples[findfirst(f, tuples)]
404374
end
405375

406-
printmethod(buf, binding, func, ast_info.args, ast_info.kwargs, t)
376+
printmethod(buf, binding, func, ast_info.args, ast_info.kwargs, t, ms.print_types)
407377
println(buf)
408378
end
409379

‎src/utilities.jl‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -321,7 +321,7 @@ function find_tuples(typesig)
321321
end
322322
end
323323

324-
function format_args(args::Vector{ASTArg}, typesig)
324+
function format_args(args::Vector{ASTArg}, typesig, print_types)
325325
# find inner tuple type
326326
function find_inner_tuple_type(t)
327327
# t is always either a UnionAll which represents a generic type or a Tuple where each parameter is the argument
@@ -369,6 +369,8 @@ function format_args(args::Vector{ASTArg}, typesig)
369369

370370
if !isnothing(arg.name)
371371
name = arg.name
372+
elseif isnothing(arg.name) && (t === Any || !print_types)
373+
name = "_"
372374
end
373375
if isvarargtype(t)
374376
t = vararg_eltype(t)
@@ -378,7 +380,7 @@ function format_args(args::Vector{ASTArg}, typesig)
378380
# information.
379381
suffix = "..."
380382
end
381-
if t !== Any
383+
if print_types && t !== Any
382384
type = "::$t"
383385
end
384386
if !isnothing(arg.default)
@@ -409,21 +411,22 @@ sig = printmethod(Docs.Binding(Main, :f), f, first(methods(f)))
409411
```
410412
"""
411413
function printmethod(buffer::IOBuffer, binding::Docs.Binding, func,
412-
args::Vector{ASTArg}, kws::Vector{ASTArg}, typesig)
413-
formatted_args = format_args(args, typesig)
414+
args::Vector{ASTArg}, kws::Vector{ASTArg},
415+
typesig, print_types::Bool)
416+
formatted_args = format_args(args, typesig, print_types)
417+
414418
# We don't have proper type information for keyword arguments like we do
415419
# with `typesig` for positional arguments, so we assume they're all Any. An
416420
# alternative would be to use the types extracted from the AST, but that
417421
# might not exactly match the types of positional arguments (e.g. an alias
418422
# type would be printed as the underlying type for positional arguments but
419423
# under the alias for keyword arguments).
420-
formatted_kws = format_args(kws, NTuple{length(kws), Any})
424+
formatted_kws = format_args(kws, NTuple{length(kws), Any}, print_types)
421425
rt = Base.return_types(func, typesig)
426+
can_print_rt = print_types && length(rt) >= 1 && rt[1] !== Nothing && rt[1] !== Union{}
422427

423428
return printmethod_format(buffer, string(binding.var), formatted_args, formatted_kws;
424-
return_type =
425-
length(rt) >= 1 && rt[1] !== Nothing && rt[1] !== Union{} ?
426-
" -> $(rt[1])" : "")
429+
return_type = can_print_rt ? " -> $(rt[1])" : "")
427430
end
428431

429432
printmethod(b, f, m) = String(take!(printmethod(IOBuffer(), b, f, m)))

‎test/runtests.jl‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
using DocStringExtensions
2-
import DocStringExtensions: TypedMethodSignatures
32

43
using Test
54
import Markdown

‎test/tests.jl‎

Lines changed: 36 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
using REPL # Hack to get around: https://github.com/JuliaLang/julia/issues/52986
22
import CodeTracking: code_string
3+
import DocStringExtensions: MethodSignatures
34
const DSE = DocStringExtensions
45

56
include("templates.jl")
@@ -144,30 +145,34 @@ end
144145
end
145146

146147
@testset "method signatures" begin
148+
UntypedSignatures(x) = MethodSignatures(x, false)
149+
147150
doc.data = Dict(
148151
:binding => Docs.Binding(M, :f),
149152
:typesig => Tuple{Any},
150153
:module => M,
151154
)
152-
DSE.format(SIGNATURES, buf, doc)
155+
156+
DSE.format(UntypedSignatures(get_expr(M.f)), buf, doc)
153157
str = String(take!(buf))
154158
@test occursin("\n```julia\n", str)
155159
@test occursin("\nf(x)\n", str)
156160
@test occursin("\n```\n", str)
157161

162+
g_expr = get_expr(M.g, Int, Int, Int)
158163
doc.data = Dict(
159164
:binding => Docs.Binding(M, :g),
160165
:typesig => Union{Tuple{}, Tuple{Any}},
161166
:module => M,
162167
)
163-
DSE.format(SIGNATURES, buf, doc)
168+
DSE.format(UntypedSignatures(g_expr), buf, doc)
164169
str = String(take!(buf))
165170
@test occursin("\n```julia\n", str)
166171
# On 1.10+, automatically generated methods have keywords in the metadata,
167172
# hence the display difference between Julia versions.
168173
if VERSION >= v"1.10"
169-
@test occursin("\ng(; ...)\n", str)
170-
@test occursin("\ng(x; ...)\n", str)
174+
@test occursin("\ng(; kwargs...)\n", str)
175+
@test occursin("\ng(x=1; kwargs...)\n", str)
171176
else
172177
@test occursin("\ng()\n", str)
173178
@test occursin("\ng()\n", str)
@@ -179,29 +184,29 @@ end
179184
:typesig => Union{Tuple{}, Tuple{Any}, Tuple{Any, Any}, Tuple{Any, Any, Any}},
180185
:module => M,
181186
)
182-
DSE.format(SIGNATURES, buf, doc)
187+
DSE.format(UntypedSignatures(g_expr), buf, doc)
183188
str = String(take!(buf))
184189
@test occursin("\n```julia\n", str)
185190
# On 1.10+, automatically generated methods have keywords in the metadata,
186191
# hence the display difference between Julia versions.
187192
if VERSION >= v"1.10"
188-
@test occursin("\ng(; ...)\n", str)
189-
@test occursin("\ng(x; ...)\n", str)
190-
@test occursin("\ng(x, y; ...)\n", str)
193+
@test occursin("\ng(; kwargs...)\n", str)
194+
@test occursin("\ng(x=1; kwargs...)\n", str)
195+
@test occursin("\ng(x=1, y=2; kwargs...)\n", str)
191196
else
192197
@test occursin("\ng()\n", str)
193-
@test occursin("\ng(x)\n", str)
194-
@test occursin("\ng(x, y)\n", str)
198+
@test occursin("\ng(x=1)\n", str)
199+
@test occursin("\ng(x=1, y=2)\n", str)
195200
end
196-
@test occursin("\ng(x, y, z; kwargs...)\n", str)
201+
@test occursin("\ng(x=1, y=2, z=3; kwargs...)\n", str)
197202
@test occursin("\n```\n", str)
198203

199204
doc.data = Dict(
200205
:binding => Docs.Binding(M, :g_1),
201206
:typesig => Tuple{Any},
202207
:module => M,
203208
)
204-
DSE.format(SIGNATURES, buf, doc)
209+
DSE.format(UntypedSignatures(get_expr(M.g_1)), buf, doc)
205210
str = String(take!(buf))
206211
@test occursin("\n```julia\n", str)
207212
@test occursin("\ng_1(x)\n", str)
@@ -212,7 +217,7 @@ end
212217
:typesig => Union{Tuple{Any, Int, Any}},
213218
:module => M,
214219
)
215-
DSE.format(SIGNATURES, buf, doc)
220+
DSE.format(UntypedSignatures(get_expr(M.h_4)), buf, doc)
216221
str = String(take!(buf))
217222
@test occursin("\n```julia\n", str)
218223
@test occursin("\nh_4(x, _, z)\n", str)
@@ -226,7 +231,9 @@ end
226231
:module => M,
227232
)
228233

229-
DSE.format(TypedMethodSignatures(get_expr(M.h_1)), buf, doc)
234+
TypedSignatures(x) = MethodSignatures(x, true)
235+
236+
DSE.format(TypedSignatures(get_expr(M.h_1)), buf, doc)
230237
str = String(take!(buf))
231238
@test occursin("\n```julia\n", str)
232239
f = str -> replace(str, " " => "")
@@ -243,7 +250,7 @@ end
243250
:typesig => Tuple{String},
244251
:module => M,
245252
)
246-
DSE.format(TypedMethodSignatures(get_expr(M.g_2)), buf, doc)
253+
DSE.format(TypedSignatures(get_expr(M.g_2)), buf, doc)
247254
str = String(take!(buf))
248255
@test occursin("\n```julia\n", str)
249256
@test occursin("\ng_2(x::String)", str)
@@ -255,7 +262,7 @@ end
255262
:typesig => Tuple{Int, Int, Int},
256263
:module => M,
257264
)
258-
DSE.format(TypedMethodSignatures(h_expr), buf, doc)
265+
DSE.format(TypedSignatures(h_expr), buf, doc)
259266
str = String(take!(buf))
260267
@test occursin("\n```julia\n", str)
261268
if typeof(1) === Int64
@@ -270,7 +277,7 @@ end
270277
:typesig => Tuple{Int},
271278
:module => M,
272279
)
273-
DSE.format(TypedMethodSignatures(h_expr), buf, doc)
280+
DSE.format(TypedSignatures(h_expr), buf, doc)
274281
str = String(take!(buf))
275282
@test occursin("\n```julia\n", str)
276283
if typeof(1) === Int64
@@ -297,7 +304,7 @@ end
297304
:typesig => Tuple{T} where T,
298305
:module => M,
299306
)
300-
DSE.format(TypedMethodSignatures(get_expr(M.k_0)), buf, doc)
307+
DSE.format(TypedSignatures(get_expr(M.k_0)), buf, doc)
301308
str = String(take!(buf))
302309
@test occursin("\n```julia\n", str)
303310
@test occursin("\nk_0(x) -> Any\n", str)
@@ -309,7 +316,7 @@ end
309316
:module => M,
310317
)
311318
k_1_expr = get_expr(M.k_1, String, Int, Int)
312-
DSE.format(TypedMethodSignatures(k_1_expr), buf, doc)
319+
DSE.format(TypedSignatures(k_1_expr), buf, doc)
313320
str = String(take!(buf))
314321
@test occursin("\n```julia\n", str)
315322
@test occursin("\nk_1(x::String) -> String\n", str)
@@ -322,7 +329,7 @@ end
322329
:typesig => (Union{Tuple{String, U, T}, Tuple{T}, Tuple{U}} where T <: Number) where U <: Complex,
323330
:module => M,
324331
)
325-
DSE.format(TypedMethodSignatures(get_expr(M.k_2)), buf, doc)
332+
DSE.format(TypedSignatures(get_expr(M.k_2)), buf, doc)
326333
str = String(take!(buf))
327334
@test occursin("\n```julia\n", str)
328335
@test occursin("k_2(x::String, y::Complex, z::Number) -> String", str)
@@ -333,7 +340,7 @@ end
333340
:typesig => (Union{Tuple{Any, T, U}, Tuple{U}, Tuple{T}} where U <: Any) where T <: Any,
334341
:module => M,
335342
)
336-
DSE.format(TypedMethodSignatures(get_expr(M.k_3)), buf, doc)
343+
DSE.format(TypedSignatures(get_expr(M.k_3)), buf, doc)
337344
str = String(take!(buf))
338345
@test occursin("\n```julia\n", str)
339346
@test occursin("\nk_3(x, y, z) -> Any\n", str)
@@ -344,7 +351,7 @@ end
344351
:typesig => Union{Tuple{String}, Tuple{String, Int}},
345352
:module => M,
346353
)
347-
DSE.format(TypedMethodSignatures(get_expr(M.k_4, String, Int)), buf, doc)
354+
DSE.format(TypedSignatures(get_expr(M.k_4, String, Int)), buf, doc)
348355
str = String(take!(buf))
349356
@test occursin("\n```julia\n", str)
350357
if VERSION > v"1.3.0"
@@ -367,7 +374,7 @@ end
367374
:typesig => Union{Tuple{Type{T}, String}, Tuple{Type{T}, String, Union{Nothing, Function}}, Tuple{T}} where T <: Number,
368375
:module => M,
369376
)
370-
DSE.format(TypedMethodSignatures(get_expr(M.k_5, Type{Int}, String, Nothing)), buf, doc)
377+
DSE.format(TypedSignatures(get_expr(M.k_5, Type{Int}, String, Nothing)), buf, doc)
371378
str = String(take!(buf))
372379
@test occursin("\n```julia\n", str)
373380
if VERSION > v"1.3.0"
@@ -386,7 +393,7 @@ end
386393
:typesig => Union{Tuple{Vector{T}}, Tuple{T}} where T <: Number,
387394
:module => M,
388395
)
389-
DSE.format(TypedMethodSignatures(get_expr(M.k_6)), buf, doc)
396+
DSE.format(TypedSignatures(get_expr(M.k_6)), buf, doc)
390397
f = str -> replace(str, " " => "")
391398
str = String(take!(buf))
392399
str = f(str)
@@ -404,7 +411,7 @@ end
404411
:typesig => Union{Tuple{Union{Nothing, T}}, Tuple{T}, Tuple{Union{Nothing, T}, T}} where T<:Integer,
405412
:module => M,
406413
)
407-
DSE.format(TypedMethodSignatures(get_expr(M.k_7, Nothing, Int)), buf, doc)
414+
DSE.format(TypedSignatures(get_expr(M.k_7, Nothing, Int)), buf, doc)
408415
str = String(take!(buf))
409416
@test occursin("\n```julia\n", str)
410417
if VERSION >= v"1.6" && VERSION < v"1.7"
@@ -421,7 +428,7 @@ end
421428
:typesig => Union{Tuple{Any}},
422429
:module => M,
423430
)
424-
DSE.format(TypedMethodSignatures(get_expr(M.k_8)), buf, doc)
431+
DSE.format(TypedSignatures(get_expr(M.k_8)), buf, doc)
425432
str = String(take!(buf))
426433
@test occursin("\n```julia\n", str)
427434
@test occursin("\nk_8(x) -> Any\n", str)
@@ -432,7 +439,7 @@ end
432439
:typesig => Union{Tuple{T where T}},
433440
:module => M,
434441
)
435-
DSE.format(TypedMethodSignatures(get_expr(M.k_9)), buf, doc)
442+
DSE.format(TypedSignatures(get_expr(M.k_9)), buf, doc)
436443
str = String(take!(buf))
437444
@test occursin("\n```julia\n", str)
438445
@test occursin("\nk_9(x) -> Any\n", str)
@@ -445,7 +452,7 @@ end
445452
:typesig => Union{Tuple{Int, Vararg{Any}}},
446453
:module => M,
447454
)
448-
DSE.format(TypedMethodSignatures(get_expr(M.k_11)), buf, doc)
455+
DSE.format(TypedSignatures(get_expr(M.k_11)), buf, doc)
449456
str = String(take!(buf))
450457
@test occursin("\n```julia\n", str)
451458
@test occursin("\nk_11(x::Int64, xs...) -> Int64\n", str)
@@ -456,7 +463,7 @@ end
456463
:typesig => Union{Tuple{Int, Vararg{Real}}},
457464
:module => M,
458465
)
459-
DSE.format(TypedMethodSignatures(get_expr(M.k_12)), buf, doc)
466+
DSE.format(TypedSignatures(get_expr(M.k_12)), buf, doc)
460467
str = String(take!(buf))
461468
@test occursin("\n```julia\n", str)
462469
@test occursin("\nk_12(x::Int64, xs::Real...) -> Int64\n", str)

0 commit comments

Comments
 (0)