Documenting defstruct fields

Questions / Help
,
1

I am wondering how to document fields in defstruct properly. The convention seems to be to list fields in @moduledoc, but I find that cumbersome. With that approach, I have to jump between @moduledoc and defstruct while reading code. On the other hand, when documenting a field inline with a comment, the field is not documented in the HTML documentation without doubling the comment.

Is there a way to document a field inline, while adding that documentation to @moduledoc as well? I thought that something along the following would be nice, but this fails to parse:

defstruct [
field: :default @fielddoc "my field"
]
1 Like
2

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

2 Likes
3

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
3 Likes
4

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)

5

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
4 Likes