Merge branch 'master' into mk-fix-alltypesigs

Author: MichaelHatherly

.github/workflows/ci.yml

@@ -36,6 +36,7 @@ jobs:
             ${{ runner.os }}-test-
             ${{ runner.os }}-
       - uses: julia-actions/julia-runtest@latest
+        continue-on-error: ${{ matrix.version == 'nightly' }}
       - uses: julia-actions/julia-processcoverage@v1
       - uses: codecov/codecov-action@v1
         with:

.github/workflows/register.yml

@@ -0,0 +1,14 @@
+name: Register Package
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Version to register or component to bump
+        required: true
+jobs:
+  register:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: julia-actions/RegisterAction@latest
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}

Project.toml

@@ -1,6 +1,6 @@
 name = "DocStringExtensions"
 uuid = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
-version = "0.8.6"
+version = "0.9.2"
 
 [deps]
 LibGit2 = "76f85450-5226-5b5a-8eaa-529ad045b433"

README.md

@@ -32,20 +32,14 @@ Contributions are very welcome, as are feature requests and suggestions. Please
 [gitter-url]: https://gitter.im/juliadocs/users
 
 [docs-latest-img]: https://img.shields.io/badge/docs-latest-blue.svg
-[docs-latest-url]: https://juliadocs.github.io/DocStringExtensions.jl/latest
+[docs-latest-url]: https://DocStringExtensions.juliadocs.org/latest
 
 [docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg
-[docs-stable-url]: https://juliadocs.github.io/DocStringExtensions.jl/stable
+[docs-stable-url]: https://DocStringExtensions.juliadocs.org/stable
 
 [github-action-img]: https://github.com/JuliaDocs/DocStringExtensions.jl/actions/workflows/ci.yml/badge.svg
 [github-action-url]: https://github.com/JuliaDocs/DocStringExtensions.jl/actions/workflows/ci.yml
 
-[travis-img]: https://travis-ci.org/JuliaDocs/DocStringExtensions.jl.svg?branch=master
-[travis-url]: https://travis-ci.org/JuliaDocs/DocStringExtensions.jl
-
-[appveyor-img]: https://ci.appveyor.com/api/projects/status/7bixd69chxps91wx/branch/master?svg=true
-[appveyor-url]: https://ci.appveyor.com/project/JuliaDocs/docstringextensions-jl/branch/master
-
 [codecov-img]: https://codecov.io/gh/JuliaDocs/DocStringExtensions.jl/branch/master/graph/badge.svg
 [codecov-url]: https://codecov.io/gh/JuliaDocs/DocStringExtensions.jl
 

src/abbreviations.jl

@@ -81,13 +81,9 @@ type `Vector{Any}`.
 
   - `x::String`
 
-  - `y::Int`
+  - `y::Int`: Unlike the `x` field this field has been documented.
 
-    Unlike the `x` field this field has been documented.
-
-  - `z::Array{Any, 1}`
-
-    Another documented field.
+  - `z::Array{Any, 1}`: Another documented field.
 ```
 """
 const TYPEDFIELDS = TypeFields(true)
@@ -96,23 +92,23 @@ function format(abbrv::TypeFields, buf, doc)
     local docs = get(doc.data, :fields, Dict())
     local binding = doc.data[:binding]
     local object = Docs.resolve(binding)
-    # On 0.7 fieldnames() on an abstract type throws an error. We then explicitly return
-    # an empty vector to be consistent with the behaviour on v0.6.
     local fields = isabstracttype(object) ? Symbol[] : fieldnames(object)
     if !isempty(fields)
         println(buf)
         for field in fields
-            if abbrv.types
-                println(buf, "  - `", field, "::", fieldtype(object, field), "`")
-            else
-                println(buf, "  - `", field, "`")
-            end
+            print(buf, "  - `", field)
+            abbrv.types && print(buf, "::", fieldtype(object, field))
+            print(buf, "`")
             # Print the field docs if they exist and aren't a `doc"..."` docstring.
             if haskey(docs, field) && isa(docs[field], AbstractString)
-                println(buf)
+                print(buf, ": ")
+                indented = true
                 for line in split(docs[field], "\n")
-                    println(buf, isempty(line) ? "" : "    ", rstrip(line))
+                    println(buf, indented || isempty(line) ? "" : "    ", rstrip(line))
+                    indented = false
                 end
+            else
+                println(buf)
             end
             println(buf)
         end
@@ -394,7 +390,7 @@ function format(::TypedMethodSignatures, buf, doc)
                 end
             end
 
-            if Sys.iswindows()
+            @static if Sys.iswindows() && VERSION < v"1.8"
                 t = tuples[findlast(f, tuples)]
             else
                 t = tuples[findfirst(f, tuples)]
@@ -670,6 +666,7 @@ function template_key(doc::Docs.DocStr)
     _key(::Function, ::typeof(Union{}), binding) = ismacro(binding) ? :MACROS : :FUNCTIONS
     _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
 

src/utilities.jl

@@ -175,6 +175,45 @@ function parsedocs(mod::Module)
     end
 end
 
+"""
+$(:SIGNATURES)
+
+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 = "")
+
+    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))
+
+        sep_delim = "\n"
+        paren_delim = "\n"
+        indent = "    "
+    end
+
+    print(buffer, binding)
+    print(buffer, "($paren_delim")
+    join(buffer, Ref(indent).*args, ",$sep_delim")
+    if !isempty(kws)
+        print(buffer, ";$sep_delim")
+        join(buffer, Ref(indent).*kws, ",$sep_delim")
+    end
+    print(buffer, "$paren_delim)")
+    print(buffer, return_type)
+    return buffer
+end
 
 """
 $(:SIGNATURES)
@@ -194,19 +233,10 @@ f(x; a = 1, b...) = x
 sig = printmethod(Docs.Binding(Main, :f), f, first(methods(f)))
 ```
 """
-function printmethod(buffer::IOBuffer, binding::Docs.Binding, func, method::Method)
-    # TODO: print qualified?
-    print(buffer, binding.var)
-    print(buffer, "(")
-    join(buffer, arguments(method), ", ")
-    local kws = keywords(func, method)
-    if !isempty(kws)
-        print(buffer, "; ")
-        join(buffer, kws, ", ")
-    end
-    print(buffer, ")")
-    return buffer
-end
+printmethod(buffer::IOBuffer, binding::Docs.Binding, func, method::Method) =
+    printmethod_format(buffer, string(binding.var),
+        string.(arguments(method)),
+        string.(keywords(func, method)))
 
 """
 $(:SIGNATURES)
@@ -274,18 +304,16 @@ sig = printmethod(Docs.Binding(Main, :f), f, first(methods(f)))
 """
 function printmethod(buffer::IOBuffer, binding::Docs.Binding, func, method::Method, typesig)
     # TODO: print qualified?
-    print(buffer, binding.var)
-    print(buffer, "(")
-    local args = arguments(method)
-    local where_syntax = []
+    local args = string.(arguments(method))
+    local kws = string.(keywords(func, method))
 
     # find inner tuple type
-    function f(t)
+    function find_inner_tuple_type(t)
         # t is always either a UnionAll which represents a generic type or a Tuple where each parameter is the argument
         if t isa DataType && t <: Tuple
             t
         elseif t isa UnionAll
-            f(t.body)
+            find_inner_tuple_type(t.body)
         else
             error("Expected `typeof($t)` to be `Tuple` or `UnionAll` but found `$typeof(t)`")
         end
@@ -309,45 +337,35 @@ function printmethod(buffer::IOBuffer, binding::Docs.Binding, func, method::Meth
         typ
     end
 
-    for (i, sym) in enumerate(args)
-        if typesig isa UnionAll
-            # e.g. Tuple{Vector{T}} where T<:Number
-            # or   Tuple{String, T, T} where T<:Number
-            # or   Tuple{Type{T}, String, Union{Nothing, Function}} where T<:Number
-            t = [x for x in f(typesig).types]
-            t = [get_typesig(x, x) for x in t][i]
-        else
-            # e.g. Tuple{Vector{Int}}
-            t = typesig.types[i]
-        end
+    # if `typesig` is an UnionAll, it may be
+    # e.g. Tuple{Vector{T}} where T<:Number
+    # or   Tuple{String, T, T} where T<:Number
+    # 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)
+
+    args = map(args, argtypes) do arg,t
+        type = ""
+        suffix = ""
         if isvarargtype(t)
-            elt = vararg_eltype(t)
-            if elt === Any
-                print(buffer, "$sym...")
-            else
-                print(buffer, "$sym::$elt...")
-            end
-        elseif t === Any
-            print(buffer, sym)
-        else
-            print(buffer, "$sym::$t")
+            t = vararg_eltype(t)
+            suffix = "..."
         end
-
-        if i != length(args)
-            print(buffer, ", ")
+        if t!==Any
+            type = "::$t"
         end
+
+        "$arg$type$suffix"
     end
-    local kws = keywords(func, method)
-    if !isempty(kws)
-        print(buffer, "; ")
-        join(buffer, kws, ", ")
-    end
-    print(buffer, ")")
+
     rt = Base.return_types(func, typesig)
-    if length(rt) >= 1 && rt[1] !== Nothing && rt[1] !== Union{}
-        print(buffer, " -> $(rt[1])")
-    end
-    buffer
+
+    return printmethod_format(buffer, string(binding.var), args, string.(kws);
+        return_type =
+            length(rt) >= 1 && rt[1] !== Nothing && rt[1] !== Union{} ?
+            " -> $(rt[1])" : "")
 end
 
 printmethod(b, f, m) = String(take!(printmethod(IOBuffer(), b, f, m)))
@@ -402,7 +420,7 @@ function keywords(func, m::Method)
     # table is a MethodTable object. For some reason, the :kwsorter field is not always
     # defined. An undefined kwsorter seems to imply that there are no methods in the
     # MethodTable with keyword arguments.
-    if isdefined(table, :kwsorter)
+    if  !(Base.fieldindex(Core.MethodTable, :kwsorter, false) > 0) || isdefined(table, :kwsorter)
         # Fetching method keywords stolen from base/replutil.jl:572-576 (commit 3b45cdc9aab0):
         kwargs = VERSION < v"1.4.0-DEV.215" ? Base.kwarg_decl(m, typeof(table.kwsorter)) : Base.kwarg_decl(m)
         if isa(kwargs, Vector) && length(kwargs) > 0
@@ -432,12 +450,21 @@ args = arguments(first(methods(f)))
 ```
 """
 function arguments(m::Method)
-    local template = get_method_source(m)
-    if isdefined(template, :slotnames)
-        local args = map(template.slotnames[1:nargs(m)]) do arg
+    local argnames = nothing
+    if isdefined(m, :generator)
+        # Generated function.
+        argnames = m.generator.argnames
+    else
+        local template = get_method_source(m)
+        if isdefined(template, :slotnames)
+            argnames = template.slotnames
+        end
+    end
+    if argnames !== nothing
+        local args = map(argnames[1:nargs(m)]) do arg
             arg === Symbol("#unused#") ? "_" : arg
         end
-        return filter(arg -> arg !== Symbol("#self#"), args)
+        return filter(arg -> arg !== Symbol("#self#") && arg !== Symbol("#ctor-self#"), args)
     end
     return Symbol[]
 end

test/TestModule/M.jl

@@ -15,6 +15,9 @@ h_2(x::A{Int}) = x
 h_3(x::A{T}) where {T} = x
 h_4(x, ::Int, z) = x
 
+@generated g_1(x) = x
+@generated g_2(x::String) = x
+
 i_1(x; y = x) = x * y
 i_2(x::Int; y = x) = x * y
 i_3(x::T; y = x) where {T} = x * y

test/templates.jl

@@ -35,6 +35,9 @@ const K = 1
 "mutable struct `T`"
 mutable struct T end
 
+"mutable struct `ISSUE_115{S}`"
+mutable struct ISSUE_115{S} end
+
 "`@kwdef` struct `S`"
 Base.@kwdef struct S end
 
@@ -101,6 +104,9 @@ module OtherModule
     "mutable struct `T`"
     mutable struct T end
 
+    "mutable struct `ISSUE_115{S}`"
+    mutable struct ISSUE_115{S} end
+
     "macro `@m`"
     macro m(x) end