Module doc 

@doc and @moduledoc: documentation as a typed child of the tree.

@moduledoc """
retsu holds the list verbs.

    retsu::first([1, 2]) #=> 1
"""

@doc """
clamp keeps a number inside a range.

    clamp(99, 1, 10) #=> 10
"""
def clamp(x, lo, hi)
  …
end

@doc lowers to (blue-doc "text" (define …)): the definition is a child of its documentation, so the text travels with the tree it describes, into the formatter, def_hash, the doc rules and mondou’s views. @moduledoc is the first form of a file and lowers to (blue-moduledoc "text").

Two views of one parse. crate::parse_program_documented returns the tree with these nodes. Every other parse_program* door returns stripped forms: a documented definition becomes the definition itself, spanning its documentation too, and the module doc is gone. So the checker, the resolver and the evaluators see exactly the tree they saw before docs existed, and only the consumers that read docs ask for them.

The text is data, not code: no escapes and no interpolation. Its indentation (the closing """’s), trailing whitespace and leading and trailing blank lines are stripped at lex time, so the formatter writes one spelling of a text.

Examples are doctests. An indented paragraph of the text that holds a line expr #=> value is an example: its other lines run first, and each #=> line asserts expr == value. doctests lowers each example to a test block, so blue test runs it on the evaluator that runs every other test, and a red example is a red build.

Structs

Example

One example: an indented paragraph of a doc text with at least one #=> line.

Enums

Step

One line of an example.

Constants

DOCTEST_PREFIX

The name every doctest’s test block starts with.

DOC_HEAD

The head @doc lowers to.

MODULEDOC_HEAD

The head @moduledoc lowers to.

Functions

defined_name

The name a definition binds: def f, defmacro m, x = ….

doctests

Every example of src’s documentation as a test block, spanned at the example’s lines so a failure names where the example is written.

documented

The text and definition of a documented top-level form.

examples

Every example in a doc text.

intent

The intent: the text’s first paragraph, its lines joined by spaces.

is_definition

Can form carry a @doc? A function, macro or top-level value.

is_doc_node

Is form a doc node of either kind?

is_doctest

Is form a doctest doctests made?

module_doc

The module documentation of a documented parse, with its span.

moduledoc_text

The text of a @moduledoc form.

redocument

Put the documentation of src back on forms, a stripped parse of it (or a tree built from one whose top-level spans are the parse’s): a form whose span is a documented definition’s is wrapped again, its own span returned to the definition’s, and the module doc leads. Forms that are already documented are returned as they are.

strip

The forms every undocumented consumer sees: a documented definition is the definition, spanning its documentation; a module doc is dropped.