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