1 (**************************************************************************)
2 (* *)
3 (* OCaml *)
4 (* *)
5 (* Leo White *)
6 (* *)
7 (* Copyright 1996 Institut National de Recherche en Informatique et *)
8 (* en Automatique. *)
9 (* *)
10 (* All rights reserved. This file is distributed under the terms of *)
11 (* the GNU Lesser General Public License version 2.1, with the *)
12 (* special exception on linking described in the file LICENSE. *)
13 (* *)
14 (**************************************************************************)
15
16 (** Documentation comments
17
18 {b Warning:} this module is unstable and part of
19 {{!Compiler_libs}compiler-libs}.
20
21 *)
22
23 (** (Re)Initialise all docstring state *)
24 val init : unit -> unit
25
26 (** Emit warnings for unattached and ambiguous docstrings *)
27 val warn_bad_docstrings : unit -> unit
28
29 (** {2 Docstrings} *)
30
31 (** Documentation comments *)
32 type docstring
33
34 (** Create a docstring *)
35 val docstring : string -> Location.t -> docstring
36
37 (** Register a docstring *)
38 val register : docstring -> unit
39
40 (** Get the text of a docstring *)
41 val docstring_body : docstring -> string
42
43 (** Get the location of a docstring *)
44 val docstring_loc : docstring -> Location.t
45
46 (** {2 Set functions}
47
48 These functions are used by the lexer to associate docstrings to
49 the locations of tokens. *)
50
51 (** Docstrings immediately preceding a token *)
52 val set_pre_docstrings : Lexing.position -> docstring list -> unit
53
54 (** Docstrings immediately following a token *)
55 val set_post_docstrings : Lexing.position -> docstring list -> unit
56
57 (** Docstrings not immediately adjacent to a token *)
58 val set_floating_docstrings : Lexing.position -> docstring list -> unit
59
60 (** Docstrings immediately following the token which precedes this one *)
61 val set_pre_extra_docstrings : Lexing.position -> docstring list -> unit
62
63 (** Docstrings immediately preceding the token which follows this one *)
64 val set_post_extra_docstrings : Lexing.position -> docstring list -> unit
65
66 (** {2 Items}
67
68 The {!docs} type represents documentation attached to an item. *)
69
70 type docs =
71 { docs_pre: docstring option;
72 docs_post: docstring option; }
73
74 val empty_docs : docs
75
76 val docs_attr : docstring -> Parsetree.attribute
77
78 (** Convert item documentation to attributes and add them to an
79 attribute list *)
80 val add_docs_attrs : docs -> Parsetree.attributes -> Parsetree.attributes
81
82 (** Fetch the item documentation for the current symbol. This also
83 marks this documentation (for ambiguity warnings). *)
84 val symbol_docs : unit -> docs
85 val symbol_docs_lazy : unit -> docs Lazy.t
86
87 (** Fetch the item documentation for the symbols between two
88 positions. This also marks this documentation (for ambiguity
89 warnings). *)
90 val rhs_docs : int -> int -> docs
91 val rhs_docs_lazy : int -> int -> docs Lazy.t
92
93 (** Mark the item documentation for the current symbol (for ambiguity
94 warnings). *)
95 val mark_symbol_docs : unit -> unit
96
97 (** Mark as associated the item documentation for the symbols between
98 two positions (for ambiguity warnings) *)
99 val mark_rhs_docs : int -> int -> unit
100
101 (** {2 Fields and constructors}
102
103 The {!info} type represents documentation attached to a field or
104 constructor. *)
105
106 type info = docstring option
107
108 val empty_info : info
109
110 val info_attr : docstring -> Parsetree.attribute
111
112 (** Convert field info to attributes and add them to an
113 attribute list *)
114 val add_info_attrs : info -> Parsetree.attributes -> Parsetree.attributes
115
116 (** Fetch the field info for the current symbol. *)
117 val symbol_info : unit -> info
118
119 (** Fetch the field info following the symbol at a given position. *)
120 val rhs_info : int -> info
121
122 (** {2 Unattached comments}
123
124 The {!text} type represents documentation which is not attached to
125 anything. *)
126
127 type text = docstring list
128
129 val empty_text : text
130 val empty_text_lazy : text Lazy.t
131
132 val text_attr : docstring -> Parsetree.attribute
133
134 (** Convert text to attributes and add them to an attribute list *)
135 val add_text_attrs : text -> Parsetree.attributes -> Parsetree.attributes
136
137 (** Fetch the text preceding the current symbol. *)
138 val symbol_text : unit -> text
139 val symbol_text_lazy : unit -> text Lazy.t
140
141 (** Fetch the text preceding the symbol at the given position. *)
142 val rhs_text : int -> text
143 val rhs_text_lazy : int -> text Lazy.t
144
145 (** {2 Extra text}
146
147 There may be additional text attached to the delimiters of a block
148 (e.g. [struct] and [end]). This is fetched by the following
149 functions, which are applied to the contents of the block rather
150 than the delimiters. *)
151
152 (** Fetch additional text preceding the current symbol *)
153 val symbol_pre_extra_text : unit -> text
154
155 (** Fetch additional text following the current symbol *)
156 val symbol_post_extra_text : unit -> text
157
158 (** Fetch additional text preceding the symbol at the given position *)
159 val rhs_pre_extra_text : int -> text
160
161 (** Fetch additional text following the symbol at the given position *)
162 val rhs_post_extra_text : int -> text
163
164 (** Fetch text following the symbol at the given position *)
165 val rhs_post_text : int -> text
166
167 module WithMenhir: sig
168 (** Fetch the item documentation for the current symbol. This also
169 marks this documentation (for ambiguity warnings). *)
170 val symbol_docs : Lexing.position * Lexing.position -> docs
171 val symbol_docs_lazy : Lexing.position * Lexing.position -> docs Lazy.t
172
173 (** Fetch the item documentation for the symbols between two
174 positions. This also marks this documentation (for ambiguity
175 warnings). *)
176 val rhs_docs : Lexing.position -> Lexing.position -> docs
177 val rhs_docs_lazy : Lexing.position -> Lexing.position -> docs Lazy.t
178
179 (** Mark the item documentation for the current symbol (for ambiguity
180 warnings). *)
181 val mark_symbol_docs : Lexing.position * Lexing.position -> unit
182
183 (** Mark as associated the item documentation for the symbols between
184 two positions (for ambiguity warnings) *)
185 val mark_rhs_docs : Lexing.position -> Lexing.position -> unit
186
187 (** Fetch the field info for the current symbol. *)
188 val symbol_info : Lexing.position -> info
189
190 (** Fetch the field info following the symbol at a given position. *)
191 val rhs_info : Lexing.position -> info
192
193 (** Fetch the text preceding the current symbol. *)
194 val symbol_text : Lexing.position -> text
195 val symbol_text_lazy : Lexing.position -> text Lazy.t
196
197 (** Fetch the text preceding the symbol at the given position. *)
198 val rhs_text : Lexing.position -> text
199 val rhs_text_lazy : Lexing.position -> text Lazy.t
200
201 (** {3 Extra text}
202
203 There may be additional text attached to the delimiters of a block
204 (e.g. [struct] and [end]). This is fetched by the following
205 functions, which are applied to the contents of the block rather
206 than the delimiters. *)
207
208 (** Fetch additional text preceding the current symbol *)
209 val symbol_pre_extra_text : Lexing.position -> text
210
211 (** Fetch additional text following the current symbol *)
212 val symbol_post_extra_text : Lexing.position -> text
213
214 (** Fetch additional text preceding the symbol at the given position *)
215 val rhs_pre_extra_text : Lexing.position -> text
216
217 (** Fetch additional text following the symbol at the given position *)
218 val rhs_post_extra_text : Lexing.position -> text
219
220 (** Fetch text following the symbol at the given position *)
221 val rhs_post_text : Lexing.position -> text
222
223 end
224