How to properly document Structs for ExDoc

Questions / Help
1

I think the title is descriptive enough. I would like to know what is your approach (formatting) documenting structs for ExDoc

2

I would think using @type t and @typespec would be the way to go. Something like:

defstruct [
  foo: nil,
  count: 0,
  title: "",
  stuff: [],
  status: :not_started
]

@typedoc """
Does some stuff...

Est enim effectrix multarum et magnarum voluptatum. Gerendus est mos, modo
recte sentiat. Sit, inquam, tam facilis, quam vultis, comparatio voluptatis,
quid de dolore dicemus? Sed quae tandem ista ratio est? 
"""
@type t :: %__MODULE__{
  foo: nil | Foo.t
  title: nil | String.t,
  count: integer()
  stuff: list(),
  status: :not_started | :in_progress | :error | :finished
}

I’m not sure exactly how this shows up in the ExDoc output though, I would have to check. If it’s not clear enough then I would put a special section in the module doc with more details.

3 Likes
3

yeah definitely this add value to how to do it. Now I am worry how to document the keys (formatting I mean)

4

Usually I do this from inside the @typedoc, eg:

@typedoc """
This type does nothing but is there. It contains keys as folows:

* `:foo`: It holds something of type `Foo.t` but maybe `nil` of currently no `Foo.t` is available.
* `:title`: A human readable name for this instance. Maybe `nil` if it is not meant to be used to communicate to humans.
* ...
4 Likes
5

I second this. This is consistent with the way keyword list options are documented throughout the elixir source, I think it makes sense here too.

6

With the * instead of - ?

7

IIRC * and - are semantically equivalent in markdown. I prefer the * because it stands a bit more out in plain text view.