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
|
(Introduced in OCaml 4.03)
Comments which start with "**" are treated specially by the
compiler. They are automatically converted during parsing into
attributes (see \ref{s:attributes}) to allow tools to process them as
documentation.
Such comments can take three forms: {\em floating comments}, {\em item
comments} and {\em label comments}. Any comment starting with "**" which
does not match one of these forms will cause the compiler to emit
warning 50.
Comments which start with "**" are also used by the ocamldoc
documentation generator (see \ref{c:ocamldoc}). The three comment forms
recognised by the compiler are a subset of the forms accepted by
ocamldoc (see \ref{s:ocamldoc-comments}).
\subsection{ss:floating-comments}{Floating comments}
Comments surrounded by blank lines that appear within structures,
signatures, classes or class types are converted into
@floating-attribute@s. For example:
\begin{caml_example*}{verbatim}
type t = T
(** Now some definitions for [t] *)
let mkT = T
\end{caml_example*}
will be converted to:
\begin{caml_example*}{verbatim}
type t = T
[@@@ocaml.text " Now some definitions for [t] "]
let mkT = T
\end{caml_example*}
\subsection{ss:item-comments}{Item comments}
Comments which appear {\em immediately before} or {\em immediately
after} a structure item, signature item, class item or class type item
are converted into @item-attribute@s. Immediately before or immediately
after means that there must be no blank lines, ";;", or other
documentation comments between them. For example:
\begin{caml_example*}{verbatim}
type t = T
(** A description of [t] *)
\end{caml_example*}
or
\begin{caml_example*}{verbatim}
(** A description of [t] *)
type t = T
\end{caml_example*}
will be converted to:
\begin{caml_example*}{verbatim}
type t = T
[@@ocaml.doc " A description of [t] "]
\end{caml_example*}
Note that, if a comment appears immediately next to multiple items,
as in:
\begin{caml_example*}{verbatim}
type t = T
(** An ambiguous comment *)
type s = S
\end{caml_example*}
then it will be attached to both items:
\begin{caml_example*}{verbatim}
type t = T
[@@ocaml.doc " An ambiguous comment "]
type s = S
[@@ocaml.doc " An ambiguous comment "]
\end{caml_example*}
and the compiler will emit warning 50.
\subsection{ss:label-comments}{Label comments}
Comments which appear {\em immediately after} a labelled argument,
record field, variant constructor, object method or polymorphic variant
constructor are are converted into @attribute@s. Immediately
after means that there must be no blank lines or other documentation
comments between them. For example:
\begin{caml_example*}{verbatim}
type t1 = lbl:int (** Labelled argument *) -> unit
type t2 = {
fld: int; (** Record field *)
fld2: float;
}
type t3 =
| Cstr of string (** Variant constructor *)
| Cstr2 of string
type t4 = < meth: int * int; (** Object method *) >
type t5 = [
`PCstr (** Polymorphic variant constructor *)
]
\end{caml_example*}
will be converted to:
\begin{caml_example*}{verbatim}
type t1 = lbl:(int [@ocaml.doc " Labelled argument "]) -> unit
type t2 = {
fld: int [@ocaml.doc " Record field "];
fld2: float;
}
type t3 =
| Cstr of string [@ocaml.doc " Variant constructor "]
| Cstr2 of string
type t4 = < meth : int * int [@ocaml.doc " Object method "] >
type t5 = [
`PCstr [@ocaml.doc " Polymorphic variant constructor "]
]
\end{caml_example*}
Note that label comments take precedence over item comments, so:
\begin{caml_example*}{verbatim}
type t = T of string
(** Attaches to T not t *)
\end{caml_example*}
will be converted to:
\begin{caml_example*}{verbatim}
type t = T of string [@ocaml.doc " Attaches to T not t "]
\end{caml_example*}
whilst:
\begin{caml_example*}{verbatim}
type t = T of string
(** Attaches to T not t *)
(** Attaches to t *)
\end{caml_example*}
will be converted to:
\begin{caml_example*}{verbatim}
type t = T of string [@ocaml.doc " Attaches to T not t "]
[@@ocaml.doc " Attaches to t "]
\end{caml_example*}
In the absence of meaningful comment on the last constructor of
a type, an empty comment~"(**)" can be used instead:
\begin{caml_example*}{verbatim}
type t = T of string
(**)
(** Attaches to t *)
\end{caml_example*}
will be converted directly to
\begin{caml_example*}{verbatim}
type t = T of string
[@@ocaml.doc " Attaches to t "]
\end{caml_example*}
|
