How do I get `@spec` of the external module

Questions / Help
,
1

I need to get specs for the function which may be located in the external module, like Process or :math.

Dialyzer source code does roughly this:

{:ok, core} = Process |> :code.which() |> :dialyzer_utils.get_core_from_beam([])
{:ok, rec_dict} = :dialyzer_utils.get_record_and_type_info(core)
:dialyzer_utils.get_spec_info(Process, core, rec_dict)

and it kinda works. Is there any better documented and/or less hacky way to get the spec? Is there any reason specs are not there in beam chunks? Should not Code.fetch_docs/2 (or maybe another not yet existing Code.fetch_specs/2) retrieve specs? What am I missing?

2

Should they be there? If you think about it, @spec is nothing more than a specialized module attribute.

3

Same as @doc is, btw.

Specs are there in generated documentation for a reason.

1 Like
4

Code.fetch_docs is about fetching the “Docs” chunk of a beam file (as proposed initially here: Eep 0048 - Erlang/OTP), which specifically includes only documentation text. There is no chunk for types though. E.g. ex_doc seems to parse them from the abstract code provided in the debug_info (“Dbgi”) chunk. Dialyzer also fetches the what seems like core erlang code from the debug_info chunk. I’m wondering if there’s also some history around where and how that data is fetched (seems like there is). So the answer might be that there’s multiple ways to skin the cat and nobody bothered normalizing one of them within the elixir core codebase.

3 Likes
5

For the record, I used this code to fetch the spec as a string.

  @spec fetch_spec(module(), atom(), arity()) :: {:ok, String.t()} | {:error, any()}
  def fetch_spec(mod, fun, arity) do
    with {:ok, core} <- mod |> :code.which() |> :dialyzer_utils.get_core_from_beam(),
         {:ok, rec_dict} <- :dialyzer_utils.get_record_and_type_info(core),
         {:ok, spec_info, %{}} <- :dialyzer_utils.get_spec_info(mod, core, rec_dict),
         {:ok, {{_file, _line}, {_tmp_contract, [_fun], type}, []}} <-
           fetch_spec_info(spec_info, {mod, fun, arity}),
         do: {:ok, type_to_string(fun, type)}
  end

  defp fetch_spec_info(spec_info, {mod, fun, arity}) do
    with :error <- Map.fetch(spec_info, {mod, fun, arity}), do: {:error, :no_mfa_info}
  end

  defp type_to_quoted(fun, type) do
    for {{:type, _, _, _} = type, _} <- type do
      Code.Typespec.spec_to_quoted(fun, type)
    end
  end

  defp type_to_string(fun, type) do
    fun
    |> type_to_quoted(type)
    |> Enum.map_join(" ", &Macro.to_string/1)
  end

The first naïve attempt was to use :erl_types.t_form_to_string/1 from :dialyzer and it worked to some extent, returning somewhat alongside

~c"fun((['Elixir.Task.Supervisor':option()]) -> 'Elixir.Task.Supervisor':on_start())"

I struggled to find an elixir helper to parse this into an elixir format and reached for Code.Typespec.spec_to_quoted/2 which kinda worked but not without glitches.

The type it returned for Process.send_after/4 did not recornize the when option: {:abs, boolean()} guard and gave me when option: var which resulted in compile error. I will probably file a bug to the core.

Another glitch I found is function spec syntax. While (binary() -> boolean()) is translated to the expected erlang ~c"fun((binary()) -> boolean())", the any-arity notation lacks parentheses around the fun as ~c"fun(...) -> integer()". That I am not sure whether it’s expected or not.

Anyway.

2 Likes
6

Seems like ex_doc also reaches into the private API of Code.Typespec. Sounds like there could be an effort made to lift functionality into proper public APIs.

1 Like
7

I am positive that specs should be optionally added to “Docs” chunks.

Now when Erlang uses ex_doc to generate docs, at least two different toolings reach for two different private APIs to retrieve what is de facto a part of docs.

Or, alternatively, the new “Spec” chunk should be added to unify the representation of specs in the chunks.

1 Like