No method signature in help system

[ScottPJones]

I believe this is related to #11943 sadly enough.
After building shortly after it was merged, method signatures are no longer displayed from the help system.
From my quick test:

help?> convert(UTF32String, Char['a','b','c'])

help?> convert(UTF8String, Char['a','b','c'])

help?> convert(UTF8String, UInt8[64,65,66])

help?> convert(Int, 3.0)

Old:

help?> convert(Int, 3.0)
convert(::Type{Int64}, x::Float64) at int.jl:205

help?> convert(UTF8String, UInt8[64, 65, 66])
convert(::Type{UTF8String}, dat::Array{UInt8,1}) at unicode/utf8.jl:231

[MichaelHatherly]

The docs for those are being captured, see the contents of Base.DocBootstrap.docs, but aren't being migrated over to their respective module's __META__ afterwards. @one-more-minute, has the necessary functionality not included in #11943? I can't seem to find anything in base/docs related to it.

[MikeInnes]

Currently docs created at the bootstrap phase are still ignored. @MichaelHatherly I think you have a PR which finds methods with which, right? That would go some way towards implementing the bootstrap stuff.

[MichaelHatherly]

I think you have a PR which finds methods with which, right?

#11932

[MichaelHatherly]

Closed by #11932. I believe all those converts are now being stored correctly:

julia> Base.__META__[convert].order
9-element Array{Method,1}:
 convert(::Type{UTF8String}, dat::Array{UInt8,1}) at unicode/utf8.jl:231  
 convert(::Type{UTF16String}, str::AbstractString) at unicode/utf16.jl:114
 convert(::Type{UTF16String}, str::UTF8String) at unicode/utf16.jl:141    
 convert(::Type{UTF8String}, str::UTF16String) at unicode/utf16.jl:187    
 convert(::Type{UTF32String}, str::AbstractString) at unicode/utf32.jl:28 
 convert(::Type{UTF8String}, str::UTF32String) at unicode/utf32.jl:46     
 convert(::Type{UTF32String}, str::UTF8String) at unicode/utf32.jl:66     
 convert(::Type{UTF32String}, str::UTF16String) at unicode/utf32.jl:120   
 convert(::Type{UTF16String}, str::UTF32String) at unicode/utf32.jl:151   

[tkelman]

They're not being displayed correctly at the REPL though? I just built b15733f and tried @ScottPJones' examples above and didn't see any REPL help output.

[MichaelHatherly]

Only one of the Methods in the first example actually have any docs attached to them.

The first two examples:

julia> @which convert(UTF32String, Char['a','b','c'])
convert(::Type{UTF32String}, dat::AbstractArray{Char,1}) at unicode/utf32.jl:168

julia/base/unicode/utf32.jl

Lines 167 to 169 in b15733f

	function convert(::Type{UTF32String}, dat::AbstractVector{Char})
	@inbounds return fast_utf_copy(UTF32String, Char, length(dat), dat, true)
	end

julia> @which convert(UTF8String, Char['a','b','c'])
convert{T<:Union{UTF8String,ASCIIString}}(::Type{T<:Union{UTF8String,ASCIIString}}, data::AbstractArray{Char,1}) at unicode/utf32.jl:178

julia/base/unicode/utf32.jl

Lines 177 to 184 in b15733f

	function convert{T<:ByteString}(::Type{T}, data::AbstractVector{Char})
	s = IOBuffer(Array(UInt8,length(data)), true, true)
	truncate(s,0)
	for x in data
	print(s, x)
	end
	convert(T, takebuf_string(s))
	end

No docs have been added inline for either of those. That's why nothing is showing up in the REPL for them.

---

The following one does have docs:

julia> @which convert(UTF8String, UInt8[64,65,66])
convert(::Type{UTF8String}, dat::Array{UInt8,1}) at unicode/utf8.jl:231

julia/base/unicode/utf8.jl

Lines 220 to 229 in b15733f

	"""
	Converts a UTF-8 encoded vector of `UInt8` to a `UTF8String`
	### Returns:
	* `UTF8String`
	### Throws:
	* `UnicodeError`
	"""
	function convert(::Type{UTF8String}, dat::Vector{UInt8})

and the help mode is finding it now:

help?> convert(UTF8String, UInt8[64,65,66])
  Converts a UTF-8 encoded vector of UInt8 to a UTF8String

     Returns:
    ––––––––––

    •    UTF8String

     Throws:
    –––––––––

    •    UnicodeError

---

julia> @which convert(Int, 3.0)
convert(::Type{Int64}, x::Float64) at int.jl:205

julia/base/int.jl

Line 205 in b15733f

convert(::Type{$to}, x::Float64) = box($to,checked_fptosi($to,unbox(Float64,x)))

The closest match would be the docs for the convert Function. There are none for that particular method:

julia/base/docs/helpdb.jl

Lines 13225 to 13263 in b15733f

	doc"""
	```rst
	::
	convert(T, x)
	Convert ``x`` to a value of type ``T``.
	If ``T`` is an ``Integer`` type, an :exc:`InexactError` will be raised if
	``x`` is not representable by ``T``, for example if ``x`` is not
	integer-valued, or is outside the range supported by ``T``.
	.. doctest::
	julia> convert(Int, 3.0)
	3
	julia> convert(Int, 3.5)
	ERROR: InexactError()
	in convert at int.jl:205
	If ``T`` is a :obj:`AbstractFloat` or :obj:`Rational` type, then it will return
	the closest value to ``x`` representable by ``T``.
	.. doctest::
	julia> x = 1/3
	0.3333333333333333
	julia> convert(Float32, x)
	0.33333334f0
	julia> convert(Rational{Int32}, x)
	1//3
	julia> convert(Rational{Int64}, x)
	6004799503160661//18014398509481984
	```
	"""
	convert

Related to that: help for convert is really verbose now. Try:

help?> convert
search: convert code_native @code_native
...
lots of output
...

@one-more-minute either we need a more intelligent way of displaying the that many docstrings, or we shouldn't be displaying docs for every Method when searching with a Function.

[tkelman]

Ah, thanks, I didn't try enough of them then. How hard would it be to bring back the fallback behavior of printing the @which result when no docs are found?

Another related regression that may be worth a separate issue is showing fields and supertype for help on types that don't have specific constructor docs.

[MichaelHatherly]

How hard would it be to bring back the fallback behavior of printing the @which result when no docs are found?

Something along the lines of

diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl
index ad89c72..dfb2867 100644
--- a/base/docs/Docs.jl
+++ b/base/docs/Docs.jl
@@ -528,7 +528,8 @@ macro repl(ex)
             if $(isfield(ex) ? :(isa($(esc(ex.args[1])), DataType)) : false)
                 $(isfield(ex) ? :(fielddoc($(esc(ex.args[1])), $(ex.args[2]))) : nothing)
             else
-                @doc $(esc(ex))
+                result = @doc $(esc(ex))
+                result == nothing ? (@which($(esc(ex)))) : result
             end
         end
     end

would work with in most (?) cases I think.

Another related regression that may be worth a separate issue is showing fields and supertype for help on types that don't have specific constructor docs.

Yeah, that should definitely be fixed.

[ScottPJones]

I think it would be good to print the which info always for a method.

[jakebolewski]

Works now due to #12835

help?> convert(UTF32String, Char['a','b','c'])
  ..  convert(T, x)

  Convert ``x`` to a value of type ``T``.

  If ``T`` is an ``Integer`` type, an :exc:`InexactError` will be raised if
  ``x`` is not representable by ``T``, for example if ``x`` is not
  integer-valued, or is outside the range supported by ``T``.

  .. doctest::

     julia> convert(Int, 3.0)
     3

     julia> convert(Int, 3.5)
     ERROR: InexactError()
      in convert at int.jl:205

  If ``T`` is a :obj:`AbstractFloat` or :obj:`Rational` type, then it will return
  the closest value to ``x`` representable by ``T``.

  .. doctest::

     julia> x = 1/3
     0.3333333333333333

     julia> convert(Float32, x)
     0.33333334f0

     julia> convert(Rational{Int32}, x)
     1//3

     julia> convert(Rational{Int64}, x)
     6004799503160661//18014398509481984

there are definitely remaining bugs in the current implementation and some regressions in behavior, best to file those separately with clear test cases.