How to document fields on a struct?

You can create custom typespec and document with this

The convention is to create a type called t using the @type attribute.

defmodule MyApp.Foo do
  
  defstruct [:foo, :bar]

  @typedoc "My Foo data type."
  @type t :: %__MODULE__{foo: String.t(), bar: String.t()}

  @spec new_foo(keyword) :: t
  def new_foo(opts) do
    struct!(__MODULE__, opts)
  end
end

You can reference your new type from other modules with MyApp.Foo.t() just as you would String.t().

Typespecs

Defstruct#types

typedstruct will generate the t() under the hood. My question was more about individual fields on a struct. Those are :foo and :bar in my example:

  # the foo field is so foo
  field :foo, String.t()

  # the bar field is so bar
  field :bar, String.t()

What you are suggesting is something like this:

@typedoc "the foo field is so foo"
@type foo::String

@typedoc "the bar field is so bar"
@type bar::String

typedstruct do
  @typedoc "Foo struct is so foo"

  field :foo, foo
  field :bar, bar
end

Obviously I don’t want to create a type for every single field just to document it, because I have dozens of fields and hundreds of structs.

Sorry I guess I misunderstood your question! I’m not familiar with that library, I thought it was pseudocode

IMO, t() is self-documenting as far as what types you expect in the fields. If I wanted more documentation I would add it to the top-level @typedoc. e.g.

@typedoc """
The Foo type.

## Fields

  * `:foo` - A string that says "foo"
  * `:bar` - A string that says "bar"
"""

Maybe there’s a feature in the typedstruct library, but that’s what I would do in vanilla Elixir

Assuming that you’re creating documentation with ExDoc vs. trying to create simple code comments that describe the field I’ll document the individual fields directly in the struct’s @typedoc. So your:

becomes something like:

@typedoc """
Foo struct is so foo

## Fields
  * `:foo` - this is doc for foo.

  * `:bar` - this is doc for bar.
"""

To my knowledge, there’s no great way to document the fields individually that will render in something like ExDoc or iex h like you might expect/want.

I should note that this assumes this is for public functions/modules. When the code being documented is private, I’ll just use normal code comments to include any helpful documentation with the understanding that won’t render in ExDoc’s output.

btw, this was not what I was suggesting, my original suggestion is outlined in my second comment, but this is a reasonable approach if you want thorough documentation for your fields which may be themselves complex types. It is probably overkill if your fields are built-in types

yep, this is for public modules, and I’m using ExDoc.

@msimonborg Gotcha! It was probably mixed up in my head with another answer given by thelastinuit. It seems like @typedoc with the “Fields” section is the most common way to document struct fields.

No worries It’s also the same documentation approach for function options and the like

@doc """
Make a new Foo.

## Options

  * `:foo` - A string that is so foo.
  * `:bar` - A string that is so bar.
"""
@spec new_foo(options :: keyword) :: t
def new_foo(options), do: struct!(__MODULE__, options)