ddoronin
How to document fields on a struct?
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
Marked As Solved
sbuttgereit
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.
Also Liked
msimonborg
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)
msimonborg
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
ddoronin
@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.
ddoronin
nice! this is really helpful!
Popular in Questions
Other popular topics
Latest on Elixir Forum
Sponsor Spotlight
Catch errors, track performance, monitor hosts and more.
Categories:
Sub Categories:
Forums
Our Sponsors
Build Elixir applications with speed and confidence.
Supporting innovation across the BEAM ecosystem.
We build reliable cloud platforms for business-critical systems.
Catch errors, track performance, monitor hosts and more.
Practical resources that improve the lives of professional developers.
Enabling companies to succeed by building software people love.
The deployment platform built for Elixir: PaaS ease, VPS control.
Courses that'll move you from confusion to "Aha, now I get it!"