Documenting Ecto schemas

Questions / Help
,
1

I’m working to document a large Elixir project and I’ve noticed that the Ecto schemas do not provide detailed types for their structs.

The best I’ve come up with is to include

@type t :: %__MODULE__{}

inside my Ecto schema modules. This at least causes the shape of the struct to show up in the docs, but it’s not what I would consider “polished”. In the generated ExDoc pages, the type includes the __meta__ attribute (which is confusing to any onlooker unfamiliar with Elixir) and all the values are represented with the term() catch-all:

@type t() :: %MyEctoSchema{
  __meta__: term(),
  foo: term(),
  bar: term(),
  # ...

The source-code says “Generating typespecs for schemas is out of the scope of Ecto.Schema" and that "t/0 has to be defined manually”… but when I tried manually adding my struct fields (in the way I would if this were a normal non-Ecto struct), my definitions all seem to be ignored regardless – it seems that no matter what I define, the output is the same default (with the __meta__ field and every field type as term()).

I did some noodling when I put together the inspecto package, but I don’t think it helps here since I don’t think you can dynamically assemble a type definition (or maybe you can in a macro?).

I think I’m probably missing something so I thought I’d do a sanity check here in the forum. Thanks for any insights!

2

A ecto schema has a __meta__ field if you want it or not. It’s used to store metadata (see Ecto.get_meta). Doing %MyEctoSchema{} will make sure all keys of the schema are part of the typespec no matter if you explicitly type them or not.

1 Like
3

What seems to be a bug is that the fields are listed explicitly, the documentation for the type do not update.

4

I just tried it out in a project of mine and the docs update just fine for explicitly listed keys.

5

Ah, I see it now – even if you force the fields in your own type definition, all the other fields are still filled in (with the default term() catch-alls)