Implement TYPEDSIGNATURESNORETURN abbreviation

Author: ReubenJ

src/DocStringExtensions.jl

@@ -76,7 +76,7 @@ module DocStringExtensions
 # Exports.
 
 export @template, FIELDS, TYPEDFIELDS, EXPORTS, METHODLIST, IMPORTS
-export SIGNATURES, TYPEDSIGNATURES, TYPEDEF, DOCSTRING, FUNCTIONNAME
+export SIGNATURES, TYPEDSIGNATURES, TYPEDSIGNATURESNORETURN, TYPEDEF, DOCSTRING, FUNCTIONNAME
 export README, LICENSE
 # export interpolation
 
@@ -99,11 +99,11 @@ include("templates.jl")
 # end of the module definition and so has all the definitions already defined.
 #
 let λ = s -> isa(s, Symbol) ? getfield(DocStringExtensions, s) : s
-    for (binding, multidoc) in Docs.meta(DocStringExtensions)
-        for (typesig, docstr) in multidoc.docs
-            docstr.text = Core.svec(map(λ, docstr.text)...)
+        for (binding, multidoc) in Docs.meta(DocStringExtensions)
+                for (typesig, docstr) in multidoc.docs
+                        docstr.text = Core.svec(map(λ, docstr.text)...)
+                end
         end
-    end
 end
 
 __init__() = (hook!(template_hook); nothing)

src/abbreviations.jl

@@ -336,11 +336,13 @@ 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
@@ -358,9 +360,17 @@ f(x::Int, y::Int; a, b...)
 ```
 ````
 """
-const TYPEDSIGNATURES = TypedMethodSignatures()
+const TYPEDSIGNATURES = TypedMethodSignatures(true)
+
+"""
+An alternative to [`TYPEDSIGNATURES`](@ref) that omits the return type.
+
+The return type shown by [`TYPEDSIGNATURES`](@ref) is often `-> Any`, which is usually not
+correct. It is nicer to then just omit the type completely.
+"""
+const TYPEDSIGNATURESNORETURN = TypedMethodSignatures(false)
 
-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 +405,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")

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)))