fireproofsocks
Should using @impl true cause docs to show the callback spec?
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!
Most Liked
Eiji
Added 2 issues:
al2o3cr
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:
Eiji
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.
Popular in Questions
Other popular topics
Categories:
Sub Categories:
Forums
Popular Tags
- #ecto
- #liveview
- #troubleshooting
- #learning-elixir
- #deployment
- #library
- #erlang
- #testing
- #genserver
- #mix
- #absinthe
- #remote-other
- #otp
- #plug
- #how-to-question
- #macros
- #postgres
- #channels
- #elixirconf
- #exunit
- #discussion
- #code-sync
- #javascript
- #podcasts
- #onsite
- #dialyzer
- #docker
- #authentication
- #umbrella
- #full-time-contract
- #podcasts-by-brainlid
- #ecto-query
- #elixir-ls
- #phoenix_html
- #iex
- #blog-post
- #graphql
- #genstage
- #ai
- #websockets
- #supervisor
- #advent-of-code
- #elixirconf-us
- #distillery
- #processes
- #forms
- #api
- #metaprogramming
- #security
- #performance









