Replace callback docs copy with a link

[wojtekmach]

In #641 we made it so that callbacks docs are copied to a function (unless it has @doc false).

There was a similar proposal #815 about copying typespecs which ultimately has not been accepted given the copy can be wrong, if it referred to private types. The same problem exists for copying docs although it's less severe given it's, well, docs.

I'd like to propose to replace docs copy with docs that just give a link to appropriate callback, e.g.: @doc "Implementation for callback c:GenServer.handle_call/3.". One particular advantage of this solution is we can now hover over the link and we'll see the typespec in the popover.

If this is accepted, we should probably make similar change to IEx which I'll be happy to do.

Thoughts?

[josevalim]

The problem is that @impl true automatically disables docs, so by adding this we would be basically punishing those who use the @impl true feature and the behavior would certainly be surprising. I am not sure there is an answer for this. -- *José Valim* www.plataformatec.com.br Skype: jv.ptec Founder and Director of R&D

[wojtekmach]

Punished how? Perhaps it wasn't obvious, but just to be clear that if function has @doc false (or @impl true that sets it), we will not copy the docs. The only difference would be for users that were already relying on copying docs, instead of the whole docs they'd just have a link.

[josevalim]

That’s the point though. Setting @impl true is the best practice. We want to encourage folks to do it.

[wojtekmach]

grr, what I meant to write was:

just to be clear that if function has @doc false (or @impl true that sets it), we will neither copy nor link to the callback docs.

If your point is that @impl true is best practice (which I wholeheartedly agree with) and so we shouldn't spend time on features for people not using @impl true where they should - if that's your point, I can get behind that. 👍

[josevalim]

Yes exactly. The option is to explicitly add docs redirecting, that’s it.

[wojtekmach]

just to be clear, the proposal was about changing existing behaviour of copying callback docs into creating docs that point to a callback under the same circumstances. But I guess it does fall under "feature for people not using @impl true" so let's leave it at that ;)

[josevalim]

Oh, I see. Yes, let's create docs that point to the callback instead of copying.