Added 2 issues:

FWIW, searching the core Elixir repo for @impl true shows a lot of implementations that are @moduledoc false or at least have no @doc annotation.

Calendar.ISO does the repeating-spec thing:

The result of mentioned post was an issue:

with José Valim solution:

Currently when you write this code:

defmodule Example do
  @doc "foo"
  @callback foo() :: :ok
end

defmodule Sample do
  @behaviour Example

  def foo, do: :ok
end

You have:

$ iex -S mix
Erlang/OTP 24 [erts-12.3.1] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [jit]

Interactive Elixir (1.13.3) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)> b Example.foo
@callback foo() :: :ok

foo

iex(2)> h Sample.foo

                                   def foo()                                    

Sample.foo/0 has no docs but is a callback for behaviour Example. Showing
callback docs instead.

@callback foo() :: :ok

foo

ex_doc shows:

Callback implementation for Example.foo/0

with a link to callback documentation.

Having in mind above you do not need to write a spec. However if you write any @doc to your implementation then you need to note c:Module.callback/arity, so for example in ex_doc you can quickly navigate to said callback to see it’s @spec. Also modern editors are able to show same docs in popup. Therefore you do not need to write @spec on yourself.

However there is something weird if you add @impl true or @imple Example to Sample.foo/0 implementation. There are no documentation both in iex and ex_doc, so maybe it at least was intended. It’s worth to open an issue for that.

Thanks for filing those – they both were immediately closed, so I guess this behavior is intentional, but I can’t follow the reasoning as far as the spec is concerned. I still expect to see the original callback spec for functions that are implementing a callback.

I feel like there’s a tension between two potential uses for @behaviour:

• the original meaning, where it defined callbacks for mostly-internal use. For instance, you likely don’t want to see handle_call heads in the documentation for a GenServer

• a new meaning, where it defines an interface for Mox et al that are used externally. I’ve seen this done with a single module that declared @callbacks and @impled them, where the only “alternative implementation” was in MIX_ENV=test.