Should using @impl true cause docs to show the callback spec?

Questions / Help
,
1

I found an old post discussing @impl and @spec: @behaviour, @callback and @spec - #13 by Eiji

I couldn’t tell where this discussion left off.

When I define a @callback, it defines the spec that implementations should follow. So it feels redundant to add a @spec declaration to a function that already has @impl. I would think that saying @impl true is sufficient or even preferable (in a DRY sort of way).

What I’m noticing is in my generated docs, functions that implement a callback do not show a @spec unless it is added explicitly. (And this means more or less copying the @callback definition).

Is this by design? What is the thinking around this, and how does this square with the DRY ideal of not duplicating work?

Thanks for any input!

3 Likes
2

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:

1 Like
3

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.

1 Like
4

Added 2 issues:

4 Likes
5

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.

1 Like
6

I’m a bit confused as well. However look that you can still use @behaviour without @impl. For now that’s the only workaround I know about.

7

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.

1 Like
8

I fell like even with mox we should aim to keep behaviour implementations as internal modules that are not documented publicly.
Looking at the example provided in the mox docs. We want to document high level functions in display_temp/1 and display_humidity/1 in MyApp.HumanizedWeather, but not the implementation of MyApp.WeatherAPI (though, I see how it could be desirable as well :slightly_smiling_face:)

Also for the same reason, once function is marked with @impl true, iex shell doesn’t autocomplete it by pressing tab =)

1 Like
9

That’s not the only problem. The documentation would be inconsistent. In theory (in docs) if we would not do anything then we will have a behaviour without any (public) implementations (like it’s private API used only internally) or if we mention that X module is implementation of some behaviour then we will have only @moduledoc and all @doc not related to behaviour (if any).

Some may say that in such case we can list all implementations in behaviour documentation. Well … good luck with documenting behaviour in libraries. :smiling_imp: It would be terribly confusing to end user.

So we end up with a special group in sidebar for behaviour implementations. Those would look like an extra markdown pages in worst case (i.e. no other public functions) each having only one paragraph with a short description that this module implements said behaviour and it’s implemented for (…). This may look not bad if we would have few implementations (we would group them anyway). Now think how a single implementation would look with just one paragraph written in other library or app …

Honestly I would expect to see a list of all implemented callbacks each with@spec and a first paragraph of @doc + a link to full callback description and as you said it would be much easier in iex and code editors to have autocomplete working.

1 Like