Documenting Base methods with doc macro clobbers their help entries

[mbauman]

It'd be nice to show both the extended @doc documentation and the old helpdb.jl entry. This would allow package authors to document their extensions to base methods, and it'd start paving the way towards documenting base methods inline.

Trivial example:

help?> +
search: + .+

Base.+(x, y...)

   Addition operator. "x+y+z+..." calls this function with all
   arguments, i.e. "+(x, y, z, ...)".

julia> @doc "Foo!" -> +(::Foo) = Foo()
+ (generic function with 141 methods)

help?> +
search: + .+

  Foo!

julia>

[hayd]

This was also an issue when I tried to extract the docstrings as markdown from the rst docs (which I attempted in this commit) hayd@246314b see discussion in MichaelHatherly/Lexicon.jl#6.

This required a way to attach the help to a signature (e.g. Foo in your example) after definition-time, IIRC that was the thing holding that effort back (as well as nice syntax for it). I was hoping something like:

@doc """For ordered, indexable collections, the maximum index `i` for which `getindex(collection, i)` is valid. For unordered collections, the number of elements.
""" length(collection) -> Integer

@doc """Returns an array containing only the unique elements of the iterable `itr`, in the order that the first of each set of equivalent elements originally appears. If `dim` is specified, returns unique regions of the array `itr` along `dim`.
""" unique(itr[, dim])

cc @one-more-minute @MichaelHatherly.

[MikeInnes]

I can take a look at doing this but it depends on how much complexity it adds to the new doc code. Moving away from helpdb should be higher priority than being compatible with it IMO.

[mbauman]

Yeah, I took a quick glance myself before I posted the issue. The fallback behaviors make this trickier than I imagined it would be. I had initially thought that this would block a migration away from helpdb, but that's not really true since the only sensible way to do it would be by moving whole functions at a time. It's not really worth spending time on.

[MikeInnes]

This will be taken care of by #11828