Fix doc system part of JuliaLang#21016 (JuliaLang#21036)

* Breakage.

* Teach doc system to handle 'where'.

* Add parameters to signature.

* Add test and continue to use Union.

* Fix missing docstrings.

* Address comments.

* use newest Documenter, DocStringExtensions

base/docs/Docs.jl

@@ -78,7 +78,7 @@ function initmeta(m::Module = current_module())
  nothing
 end
 
-function signature(expr::Expr)
+function signature!(tv, expr::Expr)
  if isexpr(expr, [:call, :macrocall])
  sig = :(Union{Tuple{}})
  for arg in expr.args[2:end]
@@ -88,16 +88,26 @@ function signature(expr::Expr)
  end
  push!(sig.args[end].args, argtype(arg))
  end
- tv = typevars(expr)
+ if isexpr(expr.args[1], :curly) && isempty(tv)
+ append!(tv, tvar.(expr.args[1].args[2:end]))
+ end
+ for i = length(tv):-1:1
+ push!(sig.args, :(Tuple{$(tv[i].args[1])}))
+ end
  for i = length(tv):-1:1
  sig = Expr(:where, sig, tv[i])
  end
  sig
+ elseif isexpr(expr, :where)
+ append!(tv, tvar.(expr.args[2:end]))
+ signature!(tv, expr.args[1])
  else
- signature(expr.args[1])
+ signature!(tv, expr.args[1])
  end
 end
-signature(other) = :(Union{})
+signature!(tv, other) = :(Union{})
+signature(expr::Expr) = signature!([], expr)
+signature(other) = signature!([], other)
 
 function argtype(expr::Expr)
  isexpr(expr, :(::)) && return expr.args[end]
@@ -106,11 +116,8 @@ function argtype(expr::Expr)
 end
 argtype(other) = :Any
 
-function typevars(expr::Expr)
- isexpr(expr, :curly) && return expr.args[2:end]
- typevars(expr.args[1])
-end
-typevars(::Symbol) = []
+tvar(x::Expr) = x
+tvar(s::Symbol) = :($s <: Any)
 
 # Docsystem types.
 # ================
@@ -195,7 +202,7 @@ is stored as `Tuple{Any, Any}` in the `MultiDoc` while
 
  f{T}(x::T, y = ?) = ...
 
-is stored as `Union{Tuple{T}, Tuple{T, Any}}`.
+is stored as `Union{Tuple{T, Any}, Tuple{T}} where T`.
 
 Note: The `Function`/`DataType` object's signature is always `Union{}`.
 """
@@ -627,7 +634,7 @@ isquotedmacrocall(x) =
  isexpr(x.args[1].value, :macrocall, 1)
 # Simple expressions / atoms the may be documented.
 isbasicdoc(x) = isexpr(x, :.) || isa(x, Union{QuoteNode, Symbol})
-is_signature(x) = isexpr(x, :call) || (isexpr(x, :(::), 2) && isexpr(x.args[1], :call))
+is_signature(x) = isexpr(x, :call) || (isexpr(x, :(::), 2) && isexpr(x.args[1], :call)) || isexpr(x, :where)
 
 function docm(meta, ex, define = true)
  # Some documented expressions may be decorated with macro calls which obscure the actual

doc/REQUIRE

@@ -1,3 +1,3 @@
-Compat 0.20.0 0.20.0+
-DocStringExtensions 0.3.1 0.3.1+
-Documenter 0.9.1 0.9.1+
+Compat 0.21.0 0.21.0+
+DocStringExtensions 0.3.2 0.3.2+
+Documenter 0.9.2 0.9.2+

doc/src/stdlib/arrays.md

@@ -147,7 +147,7 @@ Base.sum_kbn
 Base.Random.randperm
 Base.invperm
 Base.isperm
-Base.permute!{T}(::Any, ::AbstractArray{T, 1})
+Base.permute!(::Any, ::AbstractVector)
 Base.ipermute!
 Base.Random.randcycle
 Base.Random.shuffle

doc/src/stdlib/dates.md

@@ -117,7 +117,7 @@ Base.Dates.toprev(::Function, ::Base.Dates.TimeType)
 
 ```@docs
 Base.Dates.Period(::Any)
-Base.Dates.CompoundPeriod{P <: Base.Dates.Period}(::Array{P,1})
+Base.Dates.CompoundPeriod(::Vector{<:Base.Dates.Period})
 Base.Dates.default
 ```
 

test/docs.jl

@@ -602,7 +602,7 @@ Base.collect{T}(::Type{EmptyType{T}}) = "borked"
 end
 
 let fd = meta(I12515)[@var(Base.collect)]
- @test fd.order[1] == (Tuple{Type{I12515.EmptyType{T}}} where T)
+ @test fd.order[1] == (Union{Tuple{Type{I12515.EmptyType{T}}}, Tuple{T}} where T)
 end
 
 # PR #12593
@@ -959,3 +959,41 @@ dynamic_test.x = "test 2"
 @test Text("docstring1") ≠ Text("docstring2")
 @test hash(Text("docstring1")) ≠ hash(Text("docstring2"))
 @test hash(Text("docstring")) ≠ hash(HTML("docstring"))
+
+# issue 21016
+module I21016
+
+struct Struct{T}
+end
+
+"String 1"
+function Struct{T}(arg1) where T<:Float64
+end
+
+"String 2"
+function Struct{T}(arg1) where T
+end
+
+"String 3"
+function Struct{T}(arg1) where Integer <: T <: Real
+end
+
+"String 4"
+function Struct{T}(arg1) where T >: Int
+end
+
+end
+
+@test docstrings_equal(
+ @doc(I21016.Struct),
+ doc"""
+ String 1
+
+ String 2
+
+ String 3
+
+ String 4
+ """
+)
+