Extracts documentation from compiled modules through the BEAM docs chunk.

This reads the same Docs chunk used by IEx and ExDoc, then extracts English documentation and normalizes its metadata for JSON. Modules must be compiled and loadable; mix doc_shell.build arranges this inside the host application. Source files are not required once their BEAM documentation is available.

Each module becomes one entry:

%{
  "id" => "MyApp.Accounts",
  "title" => "MyApp.Accounts",
  "kind" => "module",
  "ast" => [...],
  "meta" => %{
    "module" => "MyApp.Accounts",
    "language" => "elixir",
    "moduledoc" => "present",
    "members" => [...]
  }
}

ast is the module documentation parsed by DocShell.Ast. members lists every function, macro, callback, and type in the docs chunk with its kind, name, arity, signatures, raw documentation, doc_state, and metadata such as since or deprecated. Member documentation is left as Markdown text rather than parsed, because a page usually renders a member list lazily and parsing every member of every module up front is work most renderers throw away.

doc_state uses the same vocabulary as the module's moduledoc: "present", "hidden" for @doc false, or "none". Hidden members stay in the extraction for coverage reporting; renderers and the navigation leave them out, as ExDoc does.

Member metadata

The docs chunk carries whatever metadata the compiler and macros attached, and some libraries attach a lot of it. Spark, which generates Ash code interfaces, stores each function's full option schema under spark_opts — tens of kilobytes per function that no reader sees. By default only the keys in default_member_metadata/0 are kept, which are the ones ExDoc itself renders. Pass member_metadata: :all to keep every key, or a list of key names to choose your own. Filtering happens before normalization, so dropped values are never converted.

Modules without documentation

A module compiled with --no-docs, or from Erlang without a chunk, is skipped rather than treated as an error — extract/1 simply omits it. A module that has a chunk but fails to read is an error, tagged with the module name.

Modules that have a chunk but no prose are a different case, and they are deliberately still returned, with an empty ast. meta["moduledoc"] says which situation each one is in:

• "present" — the module has documentation
• "hidden" — the author wrote @moduledoc false
• "none" — no @moduledoc at all

Extraction stays complete because callers use it for more than rendering: a documentation-coverage report needs the undocumented modules precisely because they are undocumented, and dropping them here would make every codebase look fully documented.

Filtering for display happens later, in DocShell.Presentation.StaticGenerator, which skips empty entries by default so mix doc_shell.build does not fill a navigation tree with internal modules that opted out.

Modules are sorted by name so the artifact is stable across builds. Each module is read independently, so extraction runs on every scheduler; results are still returned in sorted order and the first failure in that order is the one reported.