Does dyalizer need @spec when a function has @impl?

Questions / Help
,
1

Background

I have a module that is a GenStage. I am trying to make this module dyalizer compliant but I am not sure if I am going overboard with @spec.

Code

Imagine we have the following code:

@impl GenStage
def init(args) do
  {:producer_consumer, nil}
end

This code is the init callback of a GenStage (called after running start_link).

I wonder if I should let it be (because it is clear that it is already using the behaviour) or if I should add further information:

@spec init(any) :: {:producer_consumer, nil}
@impl GenStage
def init(args) do
  {:producer_consumer, nil}
end

Questions

  1. Which of the two version is correct?
  2. Which version would be better for dialyzer? (does it make a difference at all?)
2

From the documentation it seems as if that additionally to erroring when impls are missing or no callback that fits the impl, only @doc false is implied on @impl.

Though, in general, whether you have @impl or not, dialyzer will check you function against the @callback type when you implement a callback.

3

But which way would you recommend? Would the @spec clash?

4

If the spec is a subset of what is described per the callback, then it doesn’t clash. I’m not sure though how dialyzer looks at it, also, as the interface is defined from the outside world, I’d not try to re(de)fine the spec.

5

I see. Better play it safe!

6

You can provide a typespec for behaviour callback functions. If you do so, and some arg or the return type in your spec is not a subtype of the callback spec, dialyzer will emit a corresponding warning. The same will happen if the types inferred from the callback code do not match spec types.

So e.g. the following GenServer code:

@type state :: %{foo: integer}
@spec handle_call(:foo, GenServer.from(), state) :: {:reply, :ok, state}
def handle_call(:foo, _from, state) do
  {:reply, :ok, %{state | bar: 1}}
end

Will lead to a dialyzer warning:

Invalid type specification for function 'Elixir.TestServer':handle_call/3. 
The success typing is 
          ('foo', _, #{'bar' := _, _ => _}) ->
             {'reply', 'ok', #{'bar' := 1, _ => _}}

which means that either the spec or the impl is wrong.

So far, I didn’t got into a habit of writing specs for callbacks, but I’ve been toying with this idea for some time. I think it would help documenting expected callback args, and might help catching some errors.

4 Likes
7

I’ve been toying with this idea as well, but I left it because overall in my current environment people feel it’s duplicated documentation that adds more noise and makes the code harder to maintain (that’s why I created this post).

Overall I like the idea of specifying the sub-type of the callback I am about to return for clarity’s sake, but if there is also the chance of causing dialyzer conflicts (as @NobbZ pointed out) then I am ok with leaving it be until I or someone else better understands how dialyzer works inside.