How should I document an Ecto schema?

Questions / Help
1

My schemata are derived from an external standard, but I want to give the layperson a detailed overview of how the fields are used. I’d also like to point out any discrepancies between a schema and its underlying standard.

Right now I’m describing the schema using @moduledoc.

Does anyone have any pointers or hints for documenting an Ecto schema? Maybe some examples from other projects that you liked?

edit: changed topic title so as not to mislead others

2 Likes
2

I think documenting them with @moduledoc sounds like a great solution. I too would be keen to hear how others are handling this.

2 Likes
3

I found a “kind of” solution. I’m using information from __schema__/1 and __struct__/0 to create templates that I’ll manually edit. These docs can be included using extras: in the ex_doc config.

2 Likes
4

So, I was just thinking about this a little more and I just remembered that there is a SQL COMMENT command in PostgreSQL.

This way, documentation of columns can be done in migrations and then generated from a SQL query I found here:

SELECT 	cols.column_name,
	pg_catalog.col_description(c.oid, cols.ordinal_position::int)
FROM 	pg_catalog.pg_class c, information_schema.columns cols
WHERE	cols.table_catalog = 'db_name' AND
	cols.table_schema = 'schema_name' AND
	cols.table_name = 'table_name' AND
	cols.table_name = c.relname;
2 Likes
5

Do you have an example of that extras configuration? I’d be interested to see it.

3 Likes
6

Hi, this is an example of extras in the ecto mix config

4 Likes