jon.recoil.org
this repo has no description
1(** Abstract syntax tree representing ocamldoc comments *)
2
3(** This is a syntactic representation of ocamldoc comments. See
4 {{:https://ocaml.org/releases/4.12/htmlman/ocamldoc.html}The manual} for a
5 detailed description of the syntax understood. Note that there is no attempt
6 at semantic analysis, and hence these types are capable of representing
7 values that will be rejected by further stages, for example, invalid
8 references or headings that are out of range. *)
9
10type 'a with_location = 'a Loc.with_location
11type style = [ `Bold | `Italic | `Emphasis | `Superscript | `Subscript ]
12type alignment = [ `Left | `Center | `Right ]
13
14type reference_kind = [ `Simple | `With_text ]
15(** References in doc comments can be of two kinds: [{!simple}] or
16 [{{!ref}With text}]. *)
17
18type inline_element =
19 [ `Space of string
20 | `Word of string
21 | `Code_span of string
22 | `Raw_markup of string option * string
23 | `Styled of style * inline_element with_location list
24 | `Reference of
25 reference_kind * string with_location * inline_element with_location list
26 | `Link of string * inline_element with_location list
27 | `Math_span of string (** @since 2.0.0 *) ]
28(** Inline elements are equivalent to what would be found in a [span] in HTML.
29 Mostly these are straightforward. The [`Reference] constructor takes a
30 triple whose second element is the reference itself, and the third the
31 replacement text. Similarly the [`Link] constructor has the link itself as
32 first parameter and the second is the replacement text. *)
33
34type 'a cell = 'a with_location list * [ `Header | `Data ]
35type 'a row = 'a cell list
36type 'a grid = 'a row list
37type 'a abstract_table = 'a grid * alignment option list option
38
39type code_block_tag =
40 [ `Tag of string with_location
41 | `Binding of string with_location * string with_location ]
42
43type code_block_tags = code_block_tag list
44
45type code_block_meta = {
46 language : string with_location;
47 tags : code_block_tags;
48}
49
50type media = Token.media
51type media_href = Token.media_href
52
53type code_block = {
54 meta : code_block_meta option;
55 delimiter : string option;
56 content : string with_location;
57 (** This is the raw content, that is the exact string inside the
58 delimiters. In order to get the "processed" content, see
59 {!Odoc_parser.codeblock_content} *)
60 output : nestable_block_element with_location list option;
61}
62
63and nestable_block_element =
64 [ `Paragraph of inline_element with_location list
65 | `Code_block of code_block
66 | `Verbatim of string
67 (** This is the raw content, that is the exact string inside the delimiters.
68 In order to get the "processed" content, see
69 {!Odoc_parser.verbatim_content} *)
70 | `Modules of string with_location list
71 | `List of
72 [ `Unordered | `Ordered ]
73 * [ `Light | `Heavy ]
74 * nestable_block_element with_location list list
75 | `Table of table
76 | `Math_block of string (** @since 2.0.0 *)
77 | `Media of reference_kind * media_href with_location * string * media
78 (** @since 3.0.0 *) ]
79(** Some block elements may be nested within lists or tags, but not all. The
80 [`List] constructor has a parameter of type [[`Light | `Heavy]]. This
81 corresponds to the syntactic constructor used (see the
82 {{:https://ocaml.org/releases/4.12/htmlman/ocamldoc.html#sss:ocamldoc-list}manual}).
83*)
84
85and table = nestable_block_element abstract_table * [ `Light | `Heavy ]
86
87type internal_tag =
88 [ `Canonical of string with_location
89 | `Inline
90 | `Open
91 | `Closed
92 | `Hidden
93 | `Children_order of nestable_block_element with_location list
94 | `Toc_status of nestable_block_element with_location list
95 | `Order_category of nestable_block_element with_location list
96 | `Short_title of nestable_block_element with_location list ]
97(** Internal tags are used to exercise fine control over the output of odoc.
98 They are never rendered in the output *)
99
100type ocamldoc_tag =
101 [ `Author of string
102 | `Deprecated of nestable_block_element with_location list
103 | `Param of string * nestable_block_element with_location list
104 | `Raise of string * nestable_block_element with_location list
105 | `Custom of string * nestable_block_element with_location list
106 | `Return of nestable_block_element with_location list
107 | `See of
108 [ `Url | `File | `Document ]
109 * string
110 * nestable_block_element with_location list
111 | `Since of string
112 | `Before of string * nestable_block_element with_location list
113 | `Version of string ]
114(** ocamldoc tags are those that are specified in the
115 {{:https://ocaml.org/releases/4.12/htmlman/ocamldoc.html#ss:ocamldoc-tags}manual})
116*)
117
118type tag = [ ocamldoc_tag | internal_tag ]
119type heading = int * string option * inline_element with_location list
120
121type block_element =
122 [ nestable_block_element | `Heading of heading | `Tag of tag ]
123
124type t = block_element with_location list