jon.recoil.org

Module Odoc_parser.AstSource

Abstract syntax tree representing ocamldoc comments

This is a syntactic representation of ocamldoc comments. See The manual for a detailed description of the syntax understood. Note that there is no attempt at semantic analysis, and hence these types are capable of representing values that will be rejected by further stages, for example, invalid references or headings that are out of range.

Sourcetype 'a with_location = 'a Odoc_parser.Loc.with_location
Sourcetype style = [
  1. | `Bold
  2. | `Italic
  3. | `Emphasis
  4. | `Superscript
  5. | `Subscript
]
Sourcetype alignment = [
  1. | `Left
  2. | `Center
  3. | `Right
]
Sourcetype reference_kind = [
  1. | `Simple
  2. | `With_text
]

References in doc comments can be of two kinds: {!simple} or {{!ref}With text}.

Sourcetype inline_element = [
  1. | `Space of string
  2. | `Word of string
  3. | `Code_span of string
  4. | `Raw_markup of string option * string
  5. | `Styled of Odoc_parser.Ast.style * Odoc_parser.Ast.inline_element Odoc_parser.Ast.with_location list
  6. | `Reference of Odoc_parser.Ast.reference_kind * string Odoc_parser.Ast.with_location * Odoc_parser.Ast.inline_element Odoc_parser.Ast.with_location list
  7. | `Math_span of string
    (*
    • since 2.0.0
    *)
]

Inline elements are equivalent to what would be found in a span in HTML. Mostly these are straightforward. The `Reference constructor takes a triple whose second element is the reference itself, and the third the replacement text. Similarly the `Link constructor has the link itself as first parameter and the second is the replacement text.

Sourcetype 'a cell = 'a Odoc_parser.Ast.with_location list * [ `Header | `Data ]
Sourcetype 'a row = 'a Odoc_parser.Ast.cell list
Sourcetype 'a grid = 'a Odoc_parser.Ast.row list
Sourcetype 'a abstract_table = 'a Odoc_parser.Ast.grid * Odoc_parser.Ast.alignment option list option
Sourcetype code_block_tag = [
  1. | `Tag of string Odoc_parser.Ast.with_location
  2. | `Binding of string Odoc_parser.Ast.with_location * string Odoc_parser.Ast.with_location
]
Sourcetype code_block_tags = Odoc_parser.Ast.code_block_tag list
Sourcetype code_block_meta = {
  1. language : string Odoc_parser.Ast.with_location;
  2. tags : Odoc_parser.Ast.code_block_tags;
}
Sourcetype media = [
  1. | `Audio
  2. | `Video
  3. | `Image
]
Sourcetype media_href = [
  1. | `Reference of string
]
Sourcetype code_block = {
  1. meta : Odoc_parser.Ast.code_block_meta option;
  2. delimiter : string option;
  3. content : string Odoc_parser.Ast.with_location;
    (*

    This is the raw content, that is the exact string inside the delimiters. In order to get the "processed" content, see Odoc_parser.codeblock_content

    *)
  4. output : Odoc_parser.Ast.nestable_block_element Odoc_parser.Ast.with_location list option;
}
Sourceand nestable_block_element = [
  1. | `Paragraph of Odoc_parser.Ast.inline_element Odoc_parser.Ast.with_location list
  2. | `Code_block of Odoc_parser.Ast.code_block
  3. | `Verbatim of string
    (*

    This is the raw content, that is the exact string inside the delimiters. In order to get the "processed" content, see Odoc_parser.verbatim_content

    *)
  4. | `Modules of string Odoc_parser.Ast.with_location list
  5. | `List of [ `Unordered | `Ordered ] * [ `Light | `Heavy ] * Odoc_parser.Ast.nestable_block_element Odoc_parser.Ast.with_location list list
  6. | `Table of Odoc_parser.Ast.table
  7. | `Math_block of string
    (*
    • since 2.0.0
    *)
  8. | `Media of Odoc_parser.Ast.reference_kind * Odoc_parser.Ast.media_href Odoc_parser.Ast.with_location * string * Odoc_parser.Ast.media
    (*
    • since 3.0.0
    *)
]

Some block elements may be nested within lists or tags, but not all. The `List constructor has a parameter of type [`Light | `Heavy]. This corresponds to the syntactic constructor used (see the manual).

Internal tags are used to exercise fine control over the output of odoc. They are never rendered in the output

ocamldoc tags are those that are specified in the manual)