@behaviour, @callback and @spec

Thank you for the discussion everyone!
it helped me really to read the different perspectives and make decisions.

Honestly I do not remember … However what you wrote is no longer an Elixir core part, but ex_doc library.

I have created bug report:

If it works like this, we can just put an empty @doc "" to fix the bug concerned, but this feature even is not linked on document after generating just we can see the link on iex

Screen Shot 1400-06-08 at 21.50.44884×176 2.87 KB

Am I right?

As far as I know we do not have any copy-paste documentation mechanism in Elixir which is good as you may want to have it’s own custom documentation here and for further details you should see delegated documentation …

When I deleted @callback it just shows this not full document, it doesn’t show full doc?

Screen Shot 1400-06-08 at 21.43.35829×130 9.71 KB

Looks like a bug. When @callback is used delegate_to option seems to be ignored …

Hi, I want to use @doc delegate_to: of a macro, but it doesn’t show me the doc I need

my macro and its doc

defmodule MishkaDatabase.CRUD
  @doc """
  ### Creating a record macro
  """
  defmacro crud_add(attrs)
  ...
  end
end

and my function that needs to use delegate doc:

defmodule MishkaDatabase.Public.Setting do
  @behaviour MishkaDatabase.CRUD

  @doc delegate_to: {MishkaDatabase.CRUD, :crud_add, 1}
  def create(attrs) do
    crud_add(attrs)
  end
end

when I run h, it just shows me @callback like this, not the doc I need

iex(25)> h MishkaDatabase.Public.Setting.create
@callback create(record_input()) ::
            {:error, :add, error_tag(), repo_error()}
            | {:ok, :add, error_tag(), repo_data()}

For sure if you have different @spec for specific implementation than @callback then you should use @spec. It’s important to let other knows that you will not meet exactly all cases expected by @behaviour. Otherwise I suggest delegating to callback documentation as I have mentioned previously. For dialyzer it’s ok probably because both arguments and return value match @callback specification - only small part, but matches.

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.

GenServer is not good example here is it’s most probably intended to not add @doc and @spec to those functions. Anyway I can see what you are talking about. For sure adding @doc false when you really expect documentation is really bad, but @doc delegate_to is still ok here

More … for this use case when most of projects don’t even document those functions it could be nice to properly link them to GenServer documentation page. I believe that core team does not wanted to add extra documentation for every module which uses GenServer as reading documentation could be a bit harder due to more documentation.

I have similar feeling to HTTPoison. Omitting that you are linking to deprecated function we can still use @doc delegate_to in such case without any problem.

ok, so for me it’s even not an option to consider

Personally I don’t like be forced to something. I’m like Erlang/Elixir - I can fail as much as I need. No matter how much times - sooner or later I would be better. If I would be limited in order to protect myself then I’m not going to make fails and learn on them. Look that Elixir is written to be as much extensible as possible.

The goal here is to introduce well known standards (just like adding optional @spec support), but not force them. Imagine what would happen if suddenly all hex libraries would fail, because @spec would be required for all functions. Look that @spec everywhere would be like a dream for readers, but also huge pain for maintainers.

Sooner or later you would get an edge-case. There is no rule in world to cover all cases, so forcing anything is never a good idea. It’s why phoenix is not called a framework, but library.

You have lots of cases when you need to take a look at other modules to understand code properly especially in cases like GenServer. You just need to remind from time to time handle_call, handle_cast and handle_info.

Personally I think that delegating documentation is much better, because same documentation and spec does not need to be written multiple times. Of course we do not see it in such simple examples.

Simply compare:

@doc delegate_to: {MyBehaviour, :foo, 0}

which is never going to change with copy-paste long specifications especially with map (optional and required keys).

There is no even need to imagine long map specification. Just look at really simple init/1 specification:
https://github.com/elixir-lang/elixir/blob/0a81b278619324e088641abe9d486dca8a6510b5/lib/elixir/lib/gen_server.ex#L447
You would have few extra lines for each implementation’s function just to not make one click on HTML page and it’s not even middle size of typical real world specification..