Allow documenting methods with return types

E.g.

    "..."
    f{T}(x::T)::T = x

Fixes problem mentioned in

    JuliaLang#16432 (comment)

base/docs/Docs.jl

@@ -597,6 +597,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))
 
 function docm(meta, ex, define = true)
  # Some documented expressions may be decorated with macro calls which obscure the actual
@@ -621,7 +622,7 @@ function docm(meta, ex, define = true)
  # function f end
  # f(...)
  #
- isexpr(x, FUNC_HEADS) &&  isexpr(x.args[1], :call) ? objectdoc(meta, def, x, signature(x)) :
+ isexpr(x, FUNC_HEADS) && is_signature(x.args[1])  ? objectdoc(meta, def, x, signature(x)) :
  isexpr(x, :function) && !isexpr(x.args[1], :call) ? objectdoc(meta, def, x) :
  isexpr(x, :call) ? calldoc(meta, x) :
 

test/docs.jl

@@ -159,6 +159,14 @@ const val = Foo(1.0)
 function multidoc end,
 function multidoc! end
 
+"returntype-1"
+returntype(x::Float64)::Float64 = x
+
+"returntype-2"
+function returntype(x::Int)::Int
+ x
+end
+
 end
 
 let md = meta(DocsTest)[@var(DocsTest)]
@@ -223,6 +231,11 @@ let IT = @var(DocsTest.IT)
  @test d.data[:fields][:y] == "IT.y"
 end
 
+let rt = @var(DocsTest.returntype)
+ md = meta(DocsTest)[rt]
+ @test md.order == [Tuple{Float64}, Tuple{Int}]
+end
+
 @test docstrings_equal(@doc(DocsTest.TA), doc"TA")
 
 @test docstrings_equal(@doc(DocsTest.@mac), doc"@mac()")