Documentation for functions with same arity

Question

I have two functions, with the same arity. Currently if I call h foo/1 I only get the documentation (or function signature) of the first function. Is there a way to specify which foo/1 I am interested in? Is there a way to add @doc comments to the function that will help with this? Really silly sample code below, minus any @doc comments.

def foo(bar) when is_binary(bar) do
  .
  .
  .
end

def foo(bar) when is_number(bar) do
  .
  .
  .
end

Answer 1

You actually have one function with multiple clauses. A function is identified by a name and an arity, multiple functions cannot have the same name+arity in a module. That's why your documentation only shows for the first function clause.

There's an open issue on Elixir for warning in cases such as this: https://github.com/elixir-lang/elixir/issues/3707.

Answer 2

You can define docs alongside a default signature, like so:

@doc """
foo takes either a binary or an integer value and foo's it
"""
@spec foo(String.t | integer) :: result_type_here
def foo(val)

def foo(str) when is_binary(str), do: ...
def foo(num) when is_integer(num), do: ...

But there is no way to document each variant individually.