[Proposal] Linking behaviour doc in implementing function

[Sylvain Gournay]

Hello there,

TLDR: Having an easy way to find behaviour do for implementing function.

I was playing around with behaviours and found something that bugs me.
Here is the kind of code I wrote :

defmodule MyBehaviour do
@moduledoc "general purpose doc"

@doc "fun/0 contract description"
@callback fun() :: any()
end

defmodule MyImplementation do
@behaviour MyBehaviour

@impl MyBehaviour
def fun, do: nil
end

Then some other place (or even some other project if it’s bundled in a library) would call MyImplementation.fun()
My proposal is about documentation, currently we have no doc inheritance and this results in IEx returning:

> h MyImplementation.fun
No documentation for MyImplementation.fun was found

Intuitively, I would expect to get:
- MyImplementation.fun doc if defined (and a link to MyBehaviour.fun , maybe?)
- MyBehaviour.fun doc as a fallback (or only an link to it)

For example, in many projects, GenServer is used and I’d expect h MyService.init to point me to GenServer.init doc since most likely dev won’t override the doc.

Is there something I don’t see that would make this a bad idea?

[Rudolf Manusadzhian]

Hello, 

@impl implicitly sets @doc false to the function. (And you could notice, that it won't get autocompleted in `iex` shell).

In general those functions that implement behavior callbacks are not meant to be called directly and should be treated as private/internal details. And there should be some other documented public function that makes use of the implementation of the callback.

For example if MyServer implements GenServer, we don't call MyServer.handle_call/3 directly, but rather, we use a documented public function GenServer.call/3