Dextrin.Schema.Docs (Dextrin v0.3.2)

Copy Markdown View Source

HTML documentation for a directory of .dxns schema documents: a small static site -- an index of the namespaces, and a page for each, every schema, shape and named type on it anchored, every reference a link, every version of a schema shown (Jan, 2026-10-20).

It reads the documents' source, not their compiled schemas, so it documents what a person wrote -- comments, the order of fields, a type as it was spelled -- and needs no schema to compile.

Names

A definition's name comes from where its file lies under the root, by the conventions of DXNS.md §6:

  • acme/shop/Customer-v2.dxns, acme/shop/Order/v1.dxns and acme.shop.Product.dxns each hold one definition, the entry named like the file: acme.shop/Customer, acme.shop/Order, acme.shop/Product. Every other entry in such a file is internal to that definition: it uses them, and no file name leads to them.
  • acme.common.dxns, whose entries are not named like it, is a namespace file: each entry is acme.common/<entry>.
  • HealthCheck.dxns holding HealthCheck is a name with no namespace.

Comments

A definition's documentation is its comments (see Dextrin.Schema.Docs.Comments), written in the Markdown subset of Dextrin.Schema.Docs.Markdown; a code span naming a definition links to it. A namespace file's leading comments describe its namespace; any other file's describe the version of the definition it holds.

Summary

Types

page()

A page of the site: its path under the output directory, and its content.

Functions

references(node, scope)

The names the type node refers to, as scope resolves them.

resolve(name, scope)

The name a bare or namespaced name stands for, in a file whose entries are scope.

site(root, opts \\ [])

The documentation of every .dxns file under root, as pages.

text(arg1)

The tokens under node, written together without trivia.

undoc(value)

A value node without the {:doc T %{...}} around it, and what the doc says (DXNS.md §1b): its annotations by name, each value decoded -- %{} for a value without one.

write(root, out, opts \\ [])

The documentation of every .dxns file under root, written to out: the paths it wrote, or why it could not.

Types

page()

@type page() :: {Path.t(), iodata()}

A page of the site: its path under the output directory, and its content.

Functions

references(node, scope)

@spec references(Ichor.Syntax.Node.t() | Ichor.Syntax.Token.t() | nil, %{
  required(String.t()) => String.t()
}) :: [String.t()]

The names the type node refers to, as scope resolves them.

resolve(name, scope)

@spec resolve(String.t(), %{required(String.t()) => String.t()}) :: String.t()

The name a bare or namespaced name stands for, in a file whose entries are scope.

site(root, opts \\ [])

@spec site(Path.t(), keyword()) :: {:ok, [page()]} | {:error, String.t()}

The documentation of every .dxns file under root, as pages.

opts: :title, the site's name (the root directory's name when not given).

text(arg1)

@spec text(Ichor.Syntax.Node.t() | Ichor.Syntax.Token.t()) :: String.t()

The tokens under node, written together without trivia.

undoc(value)

@spec undoc(Ichor.Syntax.Node.t() | nil) ::
  {Ichor.Syntax.Node.t() | nil, %{optional(String.t()) => term()}}

A value node without the {:doc T %{...}} around it, and what the doc says (DXNS.md §1b): its annotations by name, each value decoded -- %{} for a value without one.

write(root, out, opts \\ [])

@spec write(Path.t(), Path.t(), keyword()) :: {:ok, [Path.t()]} | {:error, String.t()}

The documentation of every .dxns file under root, written to out: the paths it wrote, or why it could not.