feat: field docs via a moduledoc marker (#41)

[bamorim]

Implements field docs with a marker-replacement design: fields accept a doc: option, and the module's @moduledoc is scanned for a specific marker that gets replaced at compile time with a markdown list of the fields. The marker is specific enough to be the opt-in itself — no schema option, no application config, no experimental flag, and no fallback behavior of any kind.

Usage

defmodule Person do
  @moduledoc """
  A person.

  ## Fields

  <!-- typed_ecto_schema: fields -->
  """

  use TypedEctoSchema

  typed_schema "people" do
    field(:name, :string, null: false, doc: "The person's full name")
    field(:age, :integer)
  end
end

generates documentation equivalent to:

@moduledoc """
A person.

## Fields

- `id` (`integer() | nil`)
- `name`: The person's full name (`String.t()`)
- `age` (`integer() | nil`)
"""

How it works

• The :doc option is stripped in SyntaxSugar before the Ecto macro runs (same mechanism as :null/:enforce), and accepted everywhere those are: field/3, associations, embeds, polymorphic embeds and @primary_key. Docs accumulate in a new @__typed_ecto_schema_docs__ attribute.
• In the postlude — after all fields are tracked but while the module is still compiling — TypeBuilder.__set_moduledoc__/1 reads @moduledoc via Module.get_attribute; if it is a string containing <!-- typed_ecto_schema: fields -->, the marker is replaced (String.replace/3) and the attribute put back. Anything else (no moduledoc, @moduledoc false, no marker) is left completely untouched.
• The marker is replaced by the list alone, no heading — placement and heading hierarchy stay entirely under the author's control, and since it is an HTML comment it renders as nothing even when left unreplaced (older versions, marker typo'd into a non-schema module, etc.).
• Typespecs are rendered from the already-tracked type ASTs with Macro.to_string/1, so :: overrides, null: false, enum unions etc. all show up as they appear in t/0.
• The list includes all fields (primary key, belongs_to foreign keys, timestamps included; __meta__ skipped), with the :doc text appended where present. A belongs_to :doc attaches to the association entry only, not the generated foreign key.
• The @moduledoc must appear before typed_schema (its conventional position). Documented.

Generated @typedoc

Independently of the moduledoc marker, the generated t/0 gets a @typedoc with a ## Fields heading and the same list, so field docs also show up in t Person.t() in IEx and on the type in hexdocs — meaning doc: text is never silently lost even without the marker. This only happens when the module defines no @typedoc of its own:

• an open @typedoc (defined before the schema block) is kept untouched, with the marker interpolated in it the same way as in the @moduledoc;
• @typedoc false is respected;
• the pending typedoc is set immediately before @type t() is defined, so it attaches to t/0 and never to an additional_types named type (covered by a test).

Known gaps (pre-existing, left out of scope)

• embeds_one/many with an inline do block already rejects :enforce/:null today (the opts aren't stripped on that code path), and :doc behaves the same there.
• timestamps(doc: ...) is not supported (Ecto silently accepts it; we ignore it) — a single doc for both generated fields seemed of little value.

No CHANGELOG entry, per the open release PR.

Closes #41

🤖 Generated with Claude Code