(8 hours ago: Hmmm, I should probably do that…)

This has gotten interesting. First, I’ve reduced the warning-inducing code to this:

defmodule WhatTheSpec do
  @type key :: atom()
  @type transaction :: map()

  def put(_, _, _ \\ nil)

  @spec put(one, key(), any()) :: transaction() when one: transaction()
  def put(t, _, _) when is_map(t), do: t

  @spec put(one, any(), Keyword.t()) :: :ok when one: key()
  def put(_, _, _), do: :ok

  @spec put_foo(any()) :: :ok
  def put_foo(value) do
    put(:foo, value)
  end
end

Next, I realized that Keyword.t() does not include nil, yet the third parameter may be nil indeed. So the spec

@spec put(one, any(), Keyword.t()) :: :ok when one: key()

should actually be

@spec put(one, any(), Keyword.t() | nil) :: :ok when one: key()

And sure enough, Dialyxir goes green! So it was lack of understanding on my part after all! Also, this means there’s a similar problem in SystemRegistry @spec of update/3, which sent me on this trip! And furthermore, I point my finger at Dialyxir as well! *gasp!*

Dialyxir’s warning is misleading to say the least:

lib/spec.ex:13:invalid_contract
Invalid type specification for function.

Function:
WhatTheSpec.put_foo/1

Success typing:
@spec put_foo(_) :: map()

As I grok it, @spec put_foo(_) :: map() is not a success typing, as there is actually none. I reason this is a bug, as the complaint about map() being a return type goes away after the | nil fix. It should either stay there (no, it should not!), or never appear at all, right?

Also, changing update_foo from the original example (i. e., before the | nil fix) to

  @spec put_foo(any()) :: :ok
  def put_foo(value) do
    put(:foo, value, nil) # note the explicit nil here
  end

makes Dialyxir barf completely:

Please file a bug in Issues · jeremyjh/dialyxir · GitHub with this message.

Failed to format warning:
“@spec a(:one, any(), Keyword.t()) :: 'ok’whenone :: key()\ndef a() do\n :ok\nend\n”

Legacy warning:
lib/spec.ex:7: The contract ‘Elixir.WhatTheSpec’:put(one,key(),any()) → transaction() when one :: transaction();(one,any(),‘Elixir.Keyword’:t()) → ‘ok’ when one :: key() cannot be right because the inferred return for put(‘foo’,_value@1::any(),‘nil’) on line 15 is ‘ok’ | map()

---

lib/spec.ex:14:no_return
Function put_foo/1 has no local return.

---

@jeremyjh, It seems I’ve hit some murky parts of Dialyxir with this.