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
224
225
226
227
228
229
230
|
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="generator" content="hevea 2.32">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1">
<link rel="stylesheet" type="text/css" href="manual.css">
<title>8.18 Documentation comments</title>
</head>
<body>
<a href="inlinerecords.html"><img src="previous_motif.svg" alt="Previous"></a>
<a href="extn.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="indexops.html"><img src="next_motif.svg" alt="Next"></a>
<hr>
<h2 class="section" id="s:doc-comments"><a class="section-anchor" href="#s:doc-comments" aria-hidden="true"></a>8.18 Documentation comments</h2>
<ul>
<li><a href="doccomments.html#ss%3Afloating-comments">8.18.1 Floating comments</a>
</li><li><a href="doccomments.html#ss%3Aitem-comments">8.18.2 Item comments</a>
</li><li><a href="doccomments.html#ss%3Alabel-comments">8.18.3 Label comments</a>
</li></ul>
<p>
(Introduced in OCaml 4.03)</p><p>Comments which start with <span class="c003">**</span> are treated specially by the
compiler. They are automatically converted during parsing into
attributes (see <a href="attributes.html#s%3Aattributes">8.12</a>) to allow tools to process them as
documentation.</p><p>Such comments can take three forms: <em>floating comments</em>, <em>item
comments</em> and <em>label comments</em>. Any comment starting with <span class="c003">**</span> which
does not match one of these forms will cause the compiler to emit
warning 50.</p><p>Comments which start with <span class="c003">**</span> are also used by the ocamldoc
documentation generator (see <a href="ocamldoc.html#c%3Aocamldoc">16</a>). The three comment forms
recognised by the compiler are a subset of the forms accepted by
ocamldoc (see <a href="ocamldoc.html#s%3Aocamldoc-comments">16.2</a>).</p>
<h3 class="subsection" id="ss:floating-comments"><a class="section-anchor" href="#ss:floating-comments" aria-hidden="true"></a>8.18.1 Floating comments</h3>
<p>Comments surrounded by blank lines that appear within structures,
signatures, classes or class types are converted into
<a class="syntax" href="attributes.html#floating-attribute"><span class="c010">floating-attribute</span></a>s. For example:</p><div class="caml-example verbatim">
<div class="ocaml">
<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T
<span class="ocamlcomment">(** Now some definitions for [t] *)</span>
<span class="ocamlkeyword">let</span> mkT = T</div></div>
</div><p>will be converted to:</p><div class="caml-example verbatim">
<div class="ocaml">
<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T
[@@@ocaml.text <span class="ocamlstring">" Now some definitions for [t] "</span>]
<span class="ocamlkeyword">let</span> mkT = T</div></div>
</div>
<h3 class="subsection" id="ss:item-comments"><a class="section-anchor" href="#ss:item-comments" aria-hidden="true"></a>8.18.2 Item comments</h3>
<p>Comments which appear <em>immediately before</em> or <em>immediately
after</em> a structure item, signature item, class item or class type item
are converted into <a class="syntax" href="attributes.html#item-attribute"><span class="c010">item-attribute</span></a>s. Immediately before or immediately
after means that there must be no blank lines, <span class="c003">;;</span>, or other
documentation comments between them. For example:</p><div class="caml-example verbatim">
<div class="ocaml">
<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T
<span class="ocamlcomment">(** A description of [t] *)</span></div></div>
</div><p>or</p><div class="caml-example verbatim">
<div class="ocaml">
<div class="pre caml-input"> <span class="ocamlcomment">(** A description of [t] *)</span>
<span class="ocamlkeyword">type</span> t = T</div></div>
</div><p>will be converted to:</p><div class="caml-example verbatim">
<div class="ocaml">
<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T
[@@ocaml.doc <span class="ocamlstring">" A description of [t] "</span>]</div></div>
</div><p>Note that, if a comment appears immediately next to multiple items,
as in:</p><div class="caml-example verbatim">
<div class="ocaml">
<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T
<span class="ocamlcomment">(** An ambiguous comment *)</span>
<span class="ocamlkeyword">type</span> s = S</div></div>
</div><p>then it will be attached to both items:</p><div class="caml-example verbatim">
<div class="ocaml">
<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T
[@@ocaml.doc <span class="ocamlstring">" An ambiguous comment "</span>]
<span class="ocamlkeyword">type</span> s = S
[@@ocaml.doc <span class="ocamlstring">" An ambiguous comment "</span>]</div></div>
</div><p>and the compiler will emit warning 50.</p>
<h3 class="subsection" id="ss:label-comments"><a class="section-anchor" href="#ss:label-comments" aria-hidden="true"></a>8.18.3 Label comments</h3>
<p>Comments which appear <em>immediately after</em> a labelled argument,
record field, variant constructor, object method or polymorphic variant
constructor are are converted into <a class="syntax" href="attributes.html#attribute"><span class="c010">attribute</span></a>s. Immediately
after means that there must be no blank lines or other documentation
comments between them. For example:</p><div class="caml-example verbatim">
<div class="ocaml">
<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t1 = lbl:int <span class="ocamlcomment">(** Labelled argument *)</span> -> unit
<span class="ocamlkeyword">type</span> t2 = {
fld: int; <span class="ocamlcomment">(** Record field *)</span>
fld2: float;
}
<span class="ocamlkeyword">type</span> t3 =
| Cstr <span class="ocamlkeyword">of</span> string <span class="ocamlcomment">(** Variant constructor *)</span>
| Cstr2 <span class="ocamlkeyword">of</span> string
<span class="ocamlkeyword">type</span> t4 = < meth: int * int; <span class="ocamlcomment">(** Object method *)</span> >
<span class="ocamlkeyword">type</span> t5 = [
`PCstr <span class="ocamlcomment">(** Polymorphic variant constructor *)</span>
]</div></div>
</div><p>will be converted to:</p><div class="caml-example verbatim">
<div class="ocaml">
<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t1 = lbl:(int [@ocaml.doc <span class="ocamlstring">" Labelled argument "</span>]) -> unit
<span class="ocamlkeyword">type</span> t2 = {
fld: int [@ocaml.doc <span class="ocamlstring">" Record field "</span>];
fld2: float;
}
<span class="ocamlkeyword">type</span> t3 =
| Cstr <span class="ocamlkeyword">of</span> string [@ocaml.doc <span class="ocamlstring">" Variant constructor "</span>]
| Cstr2 <span class="ocamlkeyword">of</span> string
<span class="ocamlkeyword">type</span> t4 = < meth : int * int [@ocaml.doc <span class="ocamlstring">" Object method "</span>] >
<span class="ocamlkeyword">type</span> t5 = [
`PCstr [@ocaml.doc <span class="ocamlstring">" Polymorphic variant constructor "</span>]
]</div></div>
</div><p>Note that label comments take precedence over item comments, so:</p><div class="caml-example verbatim">
<div class="ocaml">
<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T <span class="ocamlkeyword">of</span> string
<span class="ocamlcomment">(** Attaches to T not t *)</span></div></div>
</div><p>will be converted to:</p><div class="caml-example verbatim">
<div class="ocaml">
<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T <span class="ocamlkeyword">of</span> string [@ocaml.doc <span class="ocamlstring">" Attaches to T not t "</span>]</div></div>
</div><p>whilst:</p><div class="caml-example verbatim">
<div class="ocaml">
<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T <span class="ocamlkeyword">of</span> string
<span class="ocamlcomment">(** Attaches to T not t *)</span>
<span class="ocamlcomment">(** Attaches to t *)</span></div></div>
</div><p>will be converted to:</p><div class="caml-example verbatim">
<div class="ocaml">
<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T <span class="ocamlkeyword">of</span> string [@ocaml.doc <span class="ocamlstring">" Attaches to T not t "</span>]
[@@ocaml.doc <span class="ocamlstring">" Attaches to t "</span>]</div></div>
</div><p>In the absence of meaningful comment on the last constructor of
a type, an empty comment <span class="c003">(**)</span> can be used instead:</p><div class="caml-example verbatim">
<div class="ocaml">
<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T <span class="ocamlkeyword">of</span> string
<span class="ocamlcomment">(**)</span>
<span class="ocamlcomment">(** Attaches to t *)</span></div></div>
</div><p>will be converted directly to</p><div class="caml-example verbatim">
<div class="ocaml">
<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T <span class="ocamlkeyword">of</span> string
[@@ocaml.doc <span class="ocamlstring">" Attaches to t "</span>]</div></div>
</div>
<hr>
<a href="inlinerecords.html"><img src="previous_motif.svg" alt="Previous"></a>
<a href="extn.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="indexops.html"><img src="next_motif.svg" alt="Next"></a>
</body>
</html>
|
