Print general function documentation before that of its methods

[nalimilan]

When printing the docs for a function, even though the methods are printed from the more general to more specific, the documentation for the function itself is printed last. It should probably be printed first.

julia> """
           test(x)

       Test something.
       """
       function test end


julia> """
           test(x::Integer)

       For integers, does something very cool.
       """
       function test(x::Integer)
           x + 1
       end
test (generic function with 1 method)

julia> """
           test(x::Int)

       For `Int`, does something super silly.
       """
       function test(x::Int)
           x + 2
       end
test (generic function with 2 methods)

help?> test
search: test Test bytestring ByteString @text_str intersect intersect!

  test(x::Integer)

  For integers, does something very cool.

  test(x::Int)

  For Int, does something super silly.

  test(x)

  Test something.

[hayd]

Edit: removed noise, as I was incorrect.

That said, there's a lot of confusion about this at the moment. For example:

• Are docstrings still attached to specific methods in a meaningful way?
• Is this ordering well defined, specifically if you extend something in base or another module...

Aside/unhelpful: if you're doing something completely different use a different method name.

[MichaelHatherly]

Using

"..."
function test end

is the same as

"..."
test

apart from the first defining the function with 0 methods. Being able to write the general function docs above the more specific methods is nicer in some cases than having it only able to appear afterwards. Is there a problem with defining "dummy method definitions"?

Are docstrings still attached to specific methods in a meaningful way?

Yes, they're attached to specific signatures. See Base.__META__[*].order for an example of how method signatures are stored.

Is this ordering well defined

They're sorted using Docs.type_morespecific. I agree with @nalimilan, would be better to have the docs for Functions sorted first.

specifically if you extend something in base or another module

It'll depend on the order in which modules are registered with Docs.modules, but we could sort results across modules as well to make the module load order irrelevant.

[darwindarak]

Is there any way we can manually specify the order? Sometimes the order given by type_morespecific can be a little counterintuitive. For example, I would have thought that type_morespecific(Float64, AbstractArray) would be true.

[timholy]

Mildly OT, but there isn't (and can't be) a strict order on types; note that

type_morespecific(Float64, AbstractArray) == type_morespecific(AbstractArray, Float64) == false

[MichaelHatherly]

Prior to ac1ac74#diff-5a9ad42cbc2e070b47b9d63118501e2fR154 where type_moresprecific was first introduced we just used the order in which docstrings were added as the order they were displayed in I think. That approach may be less surprising than the current ordering. (Note: if someone does try out changing the behaviour then this method needs to first reverse the docs list before evaling each docstring.)

[darwindarak]

@timholy @MichaelHatherly Thank you both, that's exactly what I was looking for.

Is there anyone currently working on this, or are there any specific things I can help with to move this issue forward?

[MichaelHatherly]

Is there anyone currently working on this

I don't think so. I'll probably get around to it during next month when I've got some spare time.

are there any specific things I can help with to move this issue forward?

We either need to sort the signatures of Function docs above those of Methods in type_morespecific, or (as Tim has mentioned since there isn't actually a strict ordering) remove the explicit sorting calls (

julia/base/docs/Docs.jl

Line 270 in f228b83

sort!(m.order, lt = type_morespecific)

,

julia/base/docs/Docs.jl

Line 337 in f228b83

sort!(results, lt = (a, b) -> type_morespecific(first(a), first(b)))

) and just rely on the order in which docs are added instead.

[MichaelHatherly]

Closed by #15266 where the following ordering is now followed in, hopefully, all cases:

• docstrings are always displayed in the same order in which they were defined within each module.
• when multiple modules contain docs matching an @doc query then each module's docs are displayed in the order that the modules were loaded, i.e. docs for bindings from Base will always be displayed before those of packages.

This should be the least surprising behaviour I think. @nalimilan, if you think this is worth mentioning in #15136 feel free to add it.

[nalimilan]

Thanks, that should improve on the current status. I still wonder whether sorting by specificity might be a good idea too, but maybe that's not needed after all (since modules typically depends on another when extending a more general method).