Hi
Wow, thanks for all comments! Did not know that this would stir up this many opinions. 
A see your point @asummers, but since this is not a public library (“only” used within our company), I prefer that the implementers spend the extra time to go into the definition of the behaviour rather than using multiple specs that will effect the maintenance in the long run.
I also found that the @spec may state less than the actual @callback without Dialyzer telling me, witch gives me another argument not to use the @specs…
Example given:
defmodule Register.DocEvents do
@callback initialize(soure :: binary() | atom()) :: :ok | {:error, String.t()}
end
defmodule Register do
@behaviour Register.DocEvents
@impl Register.DocEvents
@spec initialize(atom()) :: :ok
def initialize(source) do
...
end
end
Dialyzer signals this is ok, and I guess it is since the actual implementation fits within the original specification. In this case, the @spec makes sense since this implementation is not the same as the @callback stated, but if they are expected to be the same then adding an extra @spec just creates more maintenance burden.
