How to document fields on a struct?

Questions / Help
, ,
1

Hey folks! I want to add documentation for individual fields on a struct/typedstruct, and I’m wondering about available options? I’m new in elixir.

typedstruct do
  @typedoc "Foo struct is so foo"

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

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

You can create custom typespec and document with this

3

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

4

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.

5

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

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

1 Like
6

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.

2 Likes
7

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.

8

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

9

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

10

@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.

1 Like
11

No worries :slight_smile: 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)
2 Likes
12

nice! this is really helpful!

1 Like