Check for Ecto models to be minimally documented

[mz2]

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.

[devonestes]

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

[mz2]

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?

[devonestes]

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.

[mz2]

This is nice!

[simon-wolf]

I like that. And the fact that we don't have to describe every field.