Refactor fetching callbacks

[wojtekmach]

No description provided.

[herminiotorres]

I have a silly question about the best way to use and references when using Kernel functions... so my question is it's okay to call only the function and avoid doing a full call like Kernel.hd(specs)?

[wojtekmach]

yes, it's totally ok to skip Kernel. since it's automatically imported everywhere.

[herminiotorres]

so the only reason to use a full declaration is when using pipes

[wojtekmach]

This is unrelated to pipes, you'd use full declaration when you're calling function from another module. You can skip the module name if the function is local to the current module or was imported using import/2. Kernel and Kernel.SpecialForms are automatically imported to every module, that's why you can call e.g. hd(list) instead of Kernel.hd(list).

[josevalim]

Is this a bug on the chunk?

[wojtekmach]

This is complicated.

We have:

iex> :gen_statem.behaviour_info(:callbacks)
[
  state_name: 3,
  ...
]

And:

Code.fetch_docs(:gen_statem) |> elem(6) |> Enum.map(&elem(&1, 0)) |> Enum.filter(&elem(&1, 0) == :callback)
[
  {:callback, :StateName, 3},
  # ...
]

And:

iex> b :gen_statem
@callback state_name(:enter, oldStateName :: state_name(), data :: data()) ::
            state_enter_result(:state_name)
@callback state_name(event_type(), eventContent :: term(), data :: data()) ::
            event_handler_result(state_name())

# ...

And:

b :gen_statem.state_name
@callback state_name(:enter, oldStateName :: state_name(), data :: data()) ::
            state_enter_result(:state_name)
@callback state_name(event_type(), eventContent :: term(), data :: data()) ::
            event_handler_result(state_name())

Note: no docs, even though they're properly attached to the chunk entry, because we have this discrepancy of state_name vs StateName.

Maybe it should be state_name in the chunk, that'd definitely solve the discrepancy, however looking at https://erlang.org/doc/man/gen_statem.html I think referring to it as Module:StateName/3 was on purpose, both the module name and function name vary.

If it makes sense to keep as StateName in the chunk, also worth mentioning that we won't be able to document such callback with EDoc given

-callback StateName(Foo) -> ok.

won't compile. We'd probably need to add support for a @name tag to overwrite how it's stored in the chunk.

-callback state_name(enter, OldState, Data).
%% @name StateName      (we document callbacks _after_ the definition.)

If we keep it as state_name in the chunk, maybe we do the reverse, store how the name should be displayed in chunk entry metadata.

[wojtekmach]

@josevalim I noticed that we ignored signature from the chunk entry for both callbacks and types so I thought I'd default to it. Was there a particular reason we didn't do it before? If this is the way to go, I'm happy to make sure Elixir is emitting the signature in the chunk.

[josevalim]

It is on purpose to keep the chunks lean. If there is no signature, we fetch it from the AST. I would keep it as is for now.