callbacks implementations are not listed in the module if `@impl true`

[eksperimental]

Given the following example.

defmodule SomeCallback do
  @doc """
  My documentation here
  """
  @callback something() :: keyword()
end


defmodule ImplTrue do
  @behaviour SomeCallback

  @impl true
  def something() do
    [a: "apple"]
  end

  @doc "bar..."
  def bar(), do: :ok
end


defmodule NoImpl do
  @behaviour SomeCallback

  def something() do
    [a: "apple"]
  end

  @doc "bar..."
  def bar(), do: :ok
end

mix docs for ImplTrue will not list something/1, while for NoImpl it shows the function.
Originally reported by vrod in https://elixirforum.com/t/documentation-for-callback/38758

[eksperimental]

I see it is not an ExDoc issue, it is rather coming from Elixir itself.

iex(2)> Code.fetch_docs(NoImpl)      
{:docs_v1, 22, :elixir, "text/markdown", %{}, %{},
 [
   {{:function, :bar, 0}, 29, ["bar()"], %{"en" => "bar..."}, %{}},
   {{:function, :something, 0}, 25, ["something()"], %{}, %{}}
 ]}
iex(3)> Code.fetch_docs(ImplTrue)
{:docs_v1, 9, :elixir, "text/markdown", %{}, %{},
 [
   {{:function, :bar, 0}, 17, ["bar()"], %{"en" => "bar..."}, %{}},
   {{:function, :something, 0}, 13, ["something()"], :hidden, %{}}
 ]} 

I see where this is coming from.
https://github.com/elixir-lang/elixir/blob/09896a609fa552feeabc53506df846c4ff7bb05b/lib/elixir/lib/module.ex#L1489-L1522

@josevalim Any specific reason why doing doc = if is_nil(doc) && impl, do: false, else: doc?

[josevalim]

Yes, that’s by design and the docs for @impl mention so. After all, you don’t want to export GenServer callbacks and so on.

[eksperimental]

Yes, that’s by design and the docs for @impl mention so. After all, you don’t want to export GenServer callbacks and so on.

Yes, I missed that last sentence in the docs for @impl

It makes sense... now my question is, shouldn't we be consitent and set @doc false for callback implementation that do not set @impl for the very same reason? after all @impl is an optional attribute to aid the user read the code.

[josevalim]

The goal was to not make this decision implicitly for the user but I believe ExDoc could not show docs for @callback by default. WDYT?

[wojtekmach]

+1

[eksperimental]

The goal was to not make this decision implicitly for the user but I believe ExDoc could not show docs for @callback by default. WDYT?

@josevalim Sorry, I don't fully understand what you mean.
Which path should we take?

[josevalim]

I mean that if the goal is consistency, we should not show docs for callbacks in ExDoc, unless they are explicitly given.