Documenting defstruct fields

I always add a typespec for @type t :: … if the struct is of importance and there you’ve got @typedoc.

By way of example:

defstruct [
  :name
]

@typedoc """
Yay docs
"""
@type t :: %__MODULE__{
  name: String.t | nil,
  age: age,
}

@typedoc """
You can create named types if you need to comment on the type of a field.
"""
@type age :: pos_integer | nil

Using @typedoc looks like a better way to document the fields, thanks for pointing me into that direction. I still find it a little bit off that I need to duplicate the declaration of what the strict is in two places, but that’s maybe something I have to get used to. (I miss defining the type of fields inline like with records in Erlang)

The typed_struct library can be used to alleviate some of the boilerplate.

Example below from the docs:

defmodule Person do
  @moduledoc """
  A struct representing a person.
  """

  use TypedStruct

  @typedoc "A person"
  typedstruct do
    field :name, String.t(), enforce: true
    field :age, non_neg_integer()
    field :happy?, boolean(), default: true
    field :phone, String.t()
  end
end