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

Eiji · April 5, 2022, 3:02am

Added 2 issues:

@impl attribute removes documentation

opened 02:52AM - 05 Apr 22 UTC

closed 04:43AM - 05 Apr 22 UTC

### Environment ```elixir $ elixir --version Erlang/OTP 24 [erts-12.3.1] [s…ource] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [jit] Elixir 1.13.3 (compiled with Erlang/OTP 24) ``` ```elixir $ cat /etc/os-release NAME="KDE neon" VERSION="5.24" ID=neon ID_LIKE="ubuntu debian" PRETTY_NAME="KDE neon User - 5.24" VARIANT="User Edition" VARIANT_ID=user VERSION_ID="20.04" HOME_URL="https://neon.kde.org/" SUPPORT_URL="https://neon.kde.org/" BUG_REPORT_URL="https://bugs.kde.org/" LOGO=start-here-kde-neon PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy" VERSION_CODENAME=focal UBUNTU_CODENAME=focal ``` ### Current behavior Below code works as expected in both `ex_doc` and `iex`: ```elixir defmodule Example do @doc "foo" @callback foo() :: :ok end defmodule Sample do @behaviour Example def foo, do: :ok end ``` However if we add `@impl true` or `@impl Example` to `Sample.foo/0` implementation then there is no documentation in both `ex_doc` and `iex`: ``` iex(1)> h Sample.foo No documentation for Sample.foo was found ``` ### Expected behavior The documentation should be the same as without `@impl` attribute set. Possibly related: https://elixirforum.com/t/should-using-impl-true-cause-docs-to-show-the-callback-spec/47034?u=eiji https://elixirforum.com/t/behaviour-callback-and-spec/20463?u=eiji issue #11219 and commit 26ca0d47cc34ec5eb3e5e3c40c37cf154c27a679

github.com/elixir-lang/ex_doc

Incorrect documentation for callback implementation

opened 03:02AM - 05 Apr 22 UTC

closed 04:45AM - 05 Apr 22 UTC

Eiji7

### Environment ```elixir $ elixir --version Erlang/OTP 24 [erts-12.3.1] [s…ource] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [jit] Elixir 1.13.3 (compiled with Erlang/OTP 24) ``` ```elixir $ cat /etc/os-release NAME="KDE neon" VERSION="5.24" ID=neon ID_LIKE="ubuntu debian" PRETTY_NAME="KDE neon User - 5.24" VARIANT="User Edition" VARIANT_ID=user VERSION_ID="20.04" HOME_URL="https://neon.kde.org/" SUPPORT_URL="https://neon.kde.org/" BUG_REPORT_URL="https://bugs.kde.org/" LOGO=start-here-kde-neon PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy" VERSION_CODENAME=focal UBUNTU_CODENAME=focal ``` ### Keep documentation metadata in callback This was fixed only for `iex`, but not for `ex_doc` yet, see: elixir-lang/elixir#11219 ### Setting `@impl` attribute removes documentation See: elixir-lang/elixir#11741 ### Different default callback documentation in `ex_doc` and `iex` Not sure if `ex_doc` here is just not updated (see documentation metadata section) or it's intended. I think it's more consistent to keep same messages, so at this point it's up to maintainers …