Implement TYPEDSIGNATURENORETURN abbreviation

Author: ReubenJ

src/abbreviations.jl

@@ -159,7 +159,7 @@ function format(::ModuleExports, buf, doc)
     if !isempty(exports)
         println(buf)
         # Sorting ignores the `@` in macro names and sorts them in with others.
-        for sym in sort(exports, by = s -> lstrip(string(s), '@'))
+        for sym in sort(exports, by=s -> lstrip(string(s), '@'))
             # Skip the module itself, since that's always exported.
             sym === nameof(object) && continue
             # We print linked names using Documenter.jl cross-reference syntax
@@ -206,7 +206,7 @@ function format(::ModuleImports, buf, doc)
     local imports = unique(ccall(:jl_module_usings, Any, (Any,), object))
     if !isempty(imports)
         println(buf)
-        for mod in sort(imports, by = string)
+        for mod in sort(imports, by=string)
             println(buf, "  - `", mod, "`")
         end
         println(buf)
@@ -255,7 +255,7 @@ function format(::MethodList, buf, doc)
     local typesig = doc.data[:typesig]
     local modname = doc.data[:module]
     local func = Docs.resolve(binding)
-    local groups = methodgroups(func, typesig, modname; exact = false)
+    local groups = methodgroups(func, typesig, modname; exact=false)
     if !isempty(groups)
         println(buf)
         for group in groups
@@ -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")
@@ -574,7 +585,7 @@ An [`Abbreviation`](@ref) for including the package LICENSE.md.
 """
 const LICENSE = License()
 
-function format(::T, buf, doc) where T <: Union{Readme,License}
+function format(::T, buf, doc) where T<:Union{Readme,License}
     m = get(doc.data, :module, nothing)
     m === nothing && return
     path = pathof(m)
@@ -647,8 +658,8 @@ end
 function included_range(abbr::Template, parts::Vector)
     # Select the correct indexing depending on what we find.
     build_range(::Template, ::Nothing) = 0:-1
-    build_range(::Template{:before}, index) = 1:(index - 1)
-    build_range(::Template{:after}, index) = (index + 1):lastindex(parts)
+    build_range(::Template{:before}, index) = 1:(index-1)
+    build_range(::Template{:after}, index) = (index+1):lastindex(parts)
     # Search for index from either the front or back.
     find_index(::Template{:before}) = findfirst(is_docstr_template, parts)
     find_index(::Template{:after}) = findlast(is_docstr_template, parts)
@@ -662,13 +673,13 @@ function template_key(doc::Docs.DocStr)
     objname(obj::Union{Function,Module,DataType,UnionAll,Core.IntrinsicFunction}, b::Docs.Binding) = nameof(obj)
     objname(obj, b::Docs.Binding) = Symbol("") # Empty to force resolving to `:CONSTANTS` below.
     # Select the key returned based on input argument types.
-    _key(::Module, sig, binding)                 = :MODULES
+    _key(::Module, sig, binding) = :MODULES
     _key(::Function, ::typeof(Union{}), binding) = ismacro(binding) ? :MACROS : :FUNCTIONS
-    _key(::Function, sig, binding)               = ismacro(binding) ? :MACROS : :METHODS
+    _key(::Function, sig, binding) = ismacro(binding) ? :MACROS : :METHODS
     _key(::DataType, ::typeof(Union{}), binding) = :TYPES
     _key(::UnionAll, ::typeof(Union{}), binding) = :TYPES
-    _key(::DataType, sig, binding)               = :METHODS
-    _key(other, sig, binding)                    = :DEFAULT
+    _key(::DataType, sig, binding) = :METHODS
+    _key(other, sig, binding) = :DEFAULT
 
     binding = doc.data[:binding]
     obj = Docs.resolve(binding)

src/utilities.jl

@@ -55,10 +55,10 @@ Keyword argument `exact = true` matches signatures "exactly" with `==` rather th
 groups = methodgroups(f, Union{Tuple{Any}, Tuple{Any, Integer}}, Main; exact = false)
 ```
 """
-function methodgroups(func, typesig, modname; exact = true)
+function methodgroups(func, typesig, modname; exact=true)
     # Group methods by file and line number.
     local methods = getmethods(func, typesig)
-    local groups = groupby(Tuple{Symbol, Int}, Vector{Method}, methods) do m
+    local groups = groupby(Tuple{Symbol,Int}, Vector{Method}, methods) do m
         (m.file, m.line), m
     end
 
@@ -74,7 +74,7 @@ function methodgroups(func, typesig, modname; exact = true)
     end
 
     # Sort the groups by file and line.
-    sort!(results, lt = comparemethods, by = first)
+    sort!(results, lt=comparemethods, by=first)
 
     return results
 end
@@ -164,7 +164,7 @@ function groupby!(f, groups, data)
         key, value = f(each)
         push!(get!(groups, key, []), value)
     end
-    return sort!(collect(groups), by = first)
+    return sort!(collect(groups), by=first)
 end
 
 """
@@ -183,7 +183,7 @@ groupby(Int, Vector{Int}, collect(1:10)) do num
 end
 ```
 """
-groupby(f, K, V, data) = groupby!(f, Dict{K, V}(), data)
+groupby(f, K, V, data) = groupby!(f, Dict{K,V}(), data)
 
 """
 $(:SIGNATURES)
@@ -218,21 +218,21 @@ Decides whether a length of method is too big to be visually appealing.
 """
 method_length_over_limit(len::Int) = len > 60
 
-function printmethod_format(buffer::IOBuffer, binding::String, args::Vector{String}, kws::Vector{String}; return_type = "")
+function printmethod_format(buffer::IOBuffer, binding::String, args::Vector{String}, kws::Vector{String}; return_type="")
 
     sep_delim = " "
     paren_delim = ""
     indent = ""
 
     if method_length_over_limit(
-            length(binding) +
-            1 +
-            sum(length.(args)) +
-            sum(length.(kws)) +
-            2*max(0, length(args)-1) +
-            2*length(kws) +
-            1 +
-            length(return_type))
+        length(binding) +
+        1 +
+        sum(length.(args)) +
+        sum(length.(kws)) +
+        2 * max(0, length(args) - 1) +
+        2 * length(kws) +
+        1 +
+        length(return_type))
 
         sep_delim = "\n"
         paren_delim = "\n"
@@ -241,10 +241,10 @@ function printmethod_format(buffer::IOBuffer, binding::String, args::Vector{Stri
 
     print(buffer, binding)
     print(buffer, "($paren_delim")
-    join(buffer, Ref(indent).*args, ",$sep_delim")
+    join(buffer, Ref(indent) .* args, ",$sep_delim")
     if !isempty(kws)
         print(buffer, ";$sep_delim")
-        join(buffer, Ref(indent).*kws, ",$sep_delim")
+        join(buffer, Ref(indent) .* kws, ",$sep_delim")
     end
     print(buffer, "$paren_delim)")
     print(buffer, return_type)
@@ -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))
@@ -379,29 +379,42 @@ function printmethod(buffer::IOBuffer, binding::Docs.Binding, func, method::Meth
     # or   Tuple{Type{T}, String, Union{Nothing, Function}} where T<:Number
     # in the other case, it's usually something like Tuple{Vector{Int}}.
     argtypes = typesig isa UnionAll ?
-            [get_typesig(t, t) for t in find_inner_tuple_type(typesig).types] :
-            collect(typesig.types)
+               [get_typesig(t, t) for t in find_inner_tuple_type(typesig).types] :
+               collect(typesig.types)
 
-    args = map(args, argtypes) do arg,t
+    args = map(args, argtypes) do arg, t
         type = ""
         suffix = ""
         if isvarargtype(t)
             t = vararg_eltype(t)
             suffix = "..."
         end
-        if t!==Any
+        if t !== Any
             type = "::$t"
         end
 
         "$arg$type$suffix"
     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)))