How to typespec guards in a human friendly way?

Questions / Help
, ,
1

Background

I am a fan of dialyzer and friends (looking at Gradient) and I try to have sepcs in my code as much as I can. To this end, I am playing with guards and I want my guard definitions to also have a typespec:

defmodule AuctionHouse.Shared.ExtraGuards do
  @moduledoc """
  Contains additional guards to use in functions.
  """

  defguard is_pos_integer(value) when is_integer(value) and value > 0
end

Problem

So, now that I have this simple guard, I want a spec for it. However, dyalizer’s suggestion doesn’t strike me as exactly human readable.

@spec is_pos_integer(any) ::
          {:__block__ | {:., [], [:andalso | :erlang, ...]}, [],
           [{:= | {any, any, any}, list, [...]}, ...]}
defguard is_pos_integer(value) when is_integer(value) and value > 0

I believe this is likely defined as a function that takes any as an argument but the return type is very difficult for me to understand. I assume it means it creates erlang code, like a macro, but I can’t make sense of it.

Questions

  • What does the return type mean?
  • Is there a way to make this more human readable? If so, how?
1 Like
2

defguard ends up calling defmacro, so what you’re seeing is the type inference for the macro.

You could type it as Macro.t() or maybe Macro.output(), but I don’t think that’s what you want…

3

defgaurd is a macro and as such it expects to receive Elixir AST as its arguments and it will return Elixir AST as its result. So the type of defguard is really something similar to:

@spec is_pos_integer(Macro.t) :: Macro.t

Which, as you are probably already saying, isn’t very illuminating and partially why adding specs to a defguard isn’t particularly useful.

I typically just add a @doc block to defguarda to document the underlying semantics.