nicene
nicene copied to clipboard
sketch-hq
Check for Ecto models to be minimally documented
It'd be excellent to be able to enforce that Ecto models are documented to a minimal standard. For starters, requiring a moduledoc and associations to have a non-empty @desc would be a great start.
@mz2 Requiring @moduledoc is already a check in Credo so I don't think we need to add anything additional there, but since @desc isn't a supported attribute in Ecto, how do you see that being used? Could you give a little example?
Oops, mixed up Absinthe and Ecto schemas there! And because the association creation things being macros, I suppose @doc entries above them don't do anything either. Hmm, do you have ideas of how we could indeed create meaningful ExDoc entries for them?
Since Ecto schemas are just structs, maybe the best place for the sort of documentation you're thinking of would be in a typedoc for that struct? We can parse the schema definition easily to get the names of the associations on that struct, and then ensure that some documentation for those associations exists in the typedoc for that struct, but we'd need to formalize a format for that documentation to check that. So, it might look something like this:
defmodule User do
use Ecto.Schema
@typedoc """
A user is a person in our system.
## Associations
posts - blog posts written by the given user
comments - comments on all blog posts written by the user
"""
@type t :: %__MODULE__{}
schema("users") do
field(:name, :string)
has_many(:posts, Post)
has_many(:comments, through: [:posts, :comments])
end
end
With that we can then ensure that the following regex matches the typedoc:
## Associations.* posts - .* comments - .*. It is conceivable that there could be false negatives, but would never have false positives.
We could also do the same sort of checking for a documentation format in the moduledoc if you think that's a better place for this kind of thing.
