# The `src/doc.rs` module

The module provides the `Document` type. At the time of writing, the type
has too many responsibilities: it handles parsing, validation, linting, HTML
generation, and more. This makes it harder to use correctly, and harder to
understand.

We should redesign the whole module by splitting the one type into several:

* `DirtyDocument` is a parsed document. It's what you get after parsing the
  subplot, bindings, and Markdown files. Basic metadata can be queried, and
  the AST for Markdown exists.

* `DocLinter` takes a `DirtyDocument` and verifies everything is OK. This
  includes checking that all embedded files exist and are used, that all steps
  in all scenarios can be matched to implementation functions, etc. In some
  cases it's useful to be able to operate on an invalid document.

* `Document` is valid. All aspects of a full subplot document are OK, and
  code that, for example, generates an HTML document, does not need to check
  that an embedded file exists. A this stage, if that is not true, it's a
  programming error in Subplot and should be treated as such.

* `DocumentGenerator` typesets a `Document` as HTML, or whatever output
  formats we may choose to support later.

* `CodeGenerator` output test code in the languages we support.

This split separates concerns so that each type has a clear purpose.
