Module Atd.DocSource

Support for <doc text="..."> annotations:

type foo = Bar of int <doc text="This type represents foo values.">

This allows code generators to inject the documentation into the generated code.

<doc> nodes that appear in the following positions should be taken into account by code generators that care about documentation:

Formats:

Currently only one format called "text" is supported:

Character encoding: UTF-8 is strongly recommended, if not plain ASCII.

Sourcetype inline =
  1. | Text of string
  2. | Code of string
    (*

    Text is regular text. Code is text that was enclosed within \{\{ \}\} and should be rendered using the same fixed-width font used in all verbatim text.

    *)
Sourcetype block =
  1. | Paragraph of inline list
  2. | Pre of string list
    (*

    Paragraph is a regular paragraph. Pre is preformatted text that was enclosed within \{\{\{ \}\}\}, and then broken up into lines. Leading space is removed evenly from each line. It should be rendered using a fixed-width font preserving spaces and line breaks.

    *)
Sourcetype doc = block list

A document is a list of paragraph-like blocks.

Sourceval parse_text : Ast.loc -> string -> doc

Parse the contents of a doc.text annotation.

Sourceval print_text : doc -> string

Print documentation in ATD's "text" format. This performs whitespace normalization, i.e. some non-significant whitespace is removed and newlines are inserted if needed to ensure that {{{ and }}} are on their own line.

Sourceval annot_schema : Annot.schema

This is for checking the placement of <doc ...> annotations.

Sourceval get_doc : Ast.loc -> Ast.annot -> doc option

Get and parse doc data from annotations.

Sourceval html_of_doc : doc -> string

Convert parsed doc into HTML.

Sourceval rewrap_paragraph : max_length:int -> string -> string list

Rewrap a paragraph of text.

This generic utility splits a string into lines where the "words" defined by any sequence of non-whitespace characters are separated by a single space character. Each line will not exceed max_length bytes unless a word is longer than this maximum length.

The result is a list of lines that are not newline-terminated.