Wheres the idiomatic place to add type specs?

I put specs between a function’s doc and its declaration. “Hover for spec” is editor/IDE-dependant. I imagine there is no objective best practice. I like to have the spec close to the function, espectially when reading new code. This is also how I see it in all codebases/libraries that I can remember.

@doc """
"""
@spec like_this() :: return_type()
def like_this do
 # ...
end

Yes, like @slouchpie I would keep the function spec (@spec, @callback, @macrocallback) close to the function and put the custom type specs (@type, @typep, @opaque) at the top of my module, e.g.

defmodule Foo.Bar do
  use Baz

  @type foo_result :: {atom, String.t()}
  @typep private_type :: {atom, atom, atom}

  ...

  @doc """
  Random function
  """
  @spec random_function(integer) :: foo_result
  def random_function(input) do
    ...
  end
end

Sounds like a good plan.

The practice that @moogle19 has suggested is also what’s practiced in the Elixir standard library, e.g. here: elixir/lib/elixir/lib/enum.ex at main · elixir-lang/elixir · GitHub