1 .\"**************************************************************************
2 .\"* *
3 .\"* OCaml *
4 .\"* *
5 .\"* Maxence Guesdon, projet Cristal, INRIA Rocquencourt *
6 .\"* *
7 .\"* Copyright 2004 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 .TH OCAMLDOC 1
17
18 \" .de Sh \" Subsection heading
19 \" .br
20 \" .if t .Sp
21 \" .ne 5
22 \" .PP
23 \" \fB\\$1\fR
24 \" .PP
25 \" ..
26
27 .SH NAME
28 ocamldoc \- The OCaml documentation generator
29
30
31 .SH SYNOPSIS
32 .B ocamldoc
33 [
34 .I options
35 ]
36 .IR filename \ ...
37
38 .SH DESCRIPTION
39
40 The OCaml documentation generator
41 .BR ocamldoc (1)
42 generates documentation from special comments embedded in source files. The
43 comments used by
44 .B ocamldoc
45 are of the form
46 .I (** ... *)
47 and follow the format described in the
48 .IR "The OCaml user's manual" .
49
50 .B ocamldoc
51 can produce documentation in various formats: HTML, LaTeX, TeXinfo,
52 Unix man pages, and
53 .BR dot (1)
54 dependency graphs. Moreover, users can add their own
55 custom generators.
56
57 In this manpage, we use the word
58 .I element
59 to refer to any of the following parts of an OCaml source file: a type
60 declaration, a value, a module, an exception, a module type, a type
61 constructor, a record field, a class, a class type, a class method, a class
62 value or a class inheritance clause.
63
64 .SH OPTIONS
65
66 The following command-line options determine the format for the generated
67 documentation generated by
68 .BR ocamldoc (1).
69 .SS "Options for choosing the output format"
70 .TP
71 .B \-html
72 Generate documentation in HTML default format. The generated HTML pages are
73 stored in the current directory, or in the directory specified with the
74 .B \-d
75 option. You can customize the style of the generated pages by editing the
76 generated
77 .I style.css
78 file, or by providing your own style sheet using option
79 .BR \-css\-style .
80 The file
81 .I style.css
82 is not generated if it already exists.
83 .TP
84 .B \-latex
85 Generate documentation in LaTeX default format. The generated LaTeX document
86 is saved in file
87 .IR ocamldoc.out ,
88 or in the file specified with the
89 .B -o
90 option. The document uses the style file
91 .IR ocamldoc.sty .
92 This file is generated when using the
93 .B \-latex
94 option, if it does not already exist. You can change this file to customize
95 the style of your LaTeX documentation.
96 .TP
97 .B \-texi
98 Generate documentation in TeXinfo default format. The generated LaTeX document
99 is saved in file
100 .IR ocamldoc.out ,
101 or in the file specified with the
102 .B -o
103 option.
104 .TP
105 .B \-man
106 Generate documentation as a set of Unix man pages. The generated pages are
107 stored in the current directory, or in the directory specified with the
108 .B \-d
109 option.
110 .TP
111 .B \-dot
112 Generate a dependency graph for the toplevel modules, in a format suitable for
113 displaying and processing by
114 .IR dot (1).
115 The
116 .IR dot (1)
117 tool is available from
118 .IR https://graphviz.org/ .
119 The textual representation of the graph is written to the file
120 .IR ocamldoc.out ,
121 or to the file specified with the
122 .B -o
123 option. Use
124 .BI dot \ ocamldoc.out
125 to display it.
126 .TP
127 .BI \-g \ file
128 Dynamically load the given file (which extension usually is .cmo or .cma),
129 which defines a custom documentation generator.
130 If the given file is a simple one and does not exist in
131 the current directory, then
132 .B ocamldoc
133 looks for it in the custom
134 generators default directory, and in the directories specified with the
135 .B \-i
136 option.
137 .TP
138 .BI \-customdir
139 Display the custom generators default directory.
140 .TP
141 .BI \-i \ directory
142 Add the given directory to the path where to look for custom generators.
143 .SS "General options"
144 .TP
145 .BI \-d \ dir
146 Generate files in directory
147 .IR dir ,
148 rather than the current directory.
149 .TP
150 .BI \-dump \ file
151 Dump collected information into
152 .IR file .
153 This information can be read with the
154 .B \-load
155 option in a subsequent invocation of
156 .BR ocamldoc (1).
157 .TP
158 .BI \-hide \ modules
159 Hide the given complete module names in the generated documentation.
160 .I modules
161 is a list of complete module names are separated by commas (,),
162 without blanks. For instance:
163 .IR Stdlib,M2.M3 .
164 .TP
165 .B \-inv\-merge\-ml\-mli
166 Reverse the precedence of implementations and interfaces when merging.
167 All elements in implementation files are kept, and the
168 .B \-m
169 option indicates which parts of the comments in interface files are merged with
170 the comments in implementation files.
171 .TP
172 .B \-keep\-code
173 Always keep the source code for values, methods and instance variables, when
174 available. The source code is always kept when a .ml
175 file is given, but is by default discarded when a .mli
176 is given. This option allows the source code to be always kept.
177 .TP
178 .BI \-load \ file
179 Load information from
180 .IR file ,
181 which has been produced by
182 .BR ocamldoc\ \-dump .
183 Several
184 .B -load
185 options can be given.
186 .TP
187 .BI \-m \ flags
188 Specify merge options between interfaces and implementations.
189 .I flags
190 can be one or several of the following characters:
191
192 .B d
193 merge description
194
195 .B a
196 merge @author
197
198 .B v
199 merge @version
200
201 .B l
202 merge @see
203
204 .B s
205 merge @since
206
207 .B o
208 merge @deprecated
209
210 .B p
211 merge @param
212
213 .B e
214 merge @raise
215
216 .B r
217 merge @return
218
219 .B A
220 merge everything
221 .TP
222 .B \-no\-custom\-tags
223 Do not allow custom @-tags.
224 .TP
225 .B \-no\-stop
226 Keep elements placed after the
227 .B (**/**)
228 special comment.
229 .TP
230 .BI \-o \ file
231 Output the generated documentation to
232 .I file
233 instead of
234 .IR ocamldoc.out .
235 This option is meaningful only in conjunction with the
236 .BR \-latex , \ \-texi ,\ or \ \-dot
237 options.
238 .TP
239 .BI \-open \ module
240 Opens
241 .I module
242 before typing.
243 .TP
244 .BI \-pp \ command
245 Pipe sources through preprocessor
246 .IR command .
247 .TP
248 .BI \-ppx \ command
249 Pipe abstract syntax tree through preprocessor
250 .IR command .
251 .TP
252 .BR \-show\-missed\-crossref
253 Show missed cross-reference opportunities.
254 .TP
255 .B \-sort
256 Sort the list of top-level modules before generating the documentation.
257 .TP
258 .B \-stars
259 Remove blank characters until the first asterisk ('*') in each line of comments.
260 .TP
261 .BI \-t \ title
262 Use
263 .I title
264 as the title for the generated documentation.
265 .TP
266 .BI \-text \ file
267 Consider \fIfile\fR as a .txt file.
268 .TP
269 .BI \-intro \ file
270 Use content of
271 .I file
272 as
273 .B ocamldoc
274 text to use as introduction (HTML, LaTeX and TeXinfo only).
275 For HTML, the file is used to create the whole "index.html" file.
276 .TP
277 .B \-v
278 Verbose mode. Display progress information.
279 .TP
280 .B \-version
281 Print version string and exit.
282 .TP
283 .B \-vnum
284 Print short version number and exit.
285 .TP
286 .B \-warn\-error
287 Treat
288 .B ocamldoc
289 warnings as errors.
290 .TP
291 .B \-hide\-warnings
292 Do not print
293 .B ocamldoc
294 warnings.
295 .TP
296 .BR \-help \ or \ \-\-help
297 Display a short usage summary and exit.
298 .SS "Type-checking options"
299 .BR ocamldoc (1)
300 calls the OCaml type-checker to obtain type information. The
301 following options impact the type-checking phase. They have the same meaning
302 as for the
303 .BR ocamlc (1)\ and \ ocamlopt (1)
304 commands.
305 .TP
306 .BI \-I \ directory
307 Add
308 .I directory
309 to the list of directories search for compiled interface files (.cmi files).
310 .TP
311 .B \-nolabels
312 Ignore non-optional labels in types.
313 .TP
314 .B \-rectypes
315 Allow arbitrary recursive types. (See the
316 .B \-rectypes
317 option to
318 .BR ocamlc (1).)
319 .SS "Options for generating HTML pages"
320 The following options apply in conjunction with the
321 .B \-html
322 option:
323 .TP
324 .B \-all\-params
325 Display the complete list of parameters for functions and methods.
326 .TP
327 .BI \-charset \ s
328 Add information about character encoding being \fIs\fR
329 (default is \fBiso-8859-1\fR).
330 .TP
331 .BI \-css\-style \ filename
332 Use
333 .I filename
334 as the Cascading Style Sheet file.
335 .TP
336 .B \-colorize\-code
337 Colorize the OCaml code enclosed in [ ] and \\{[ ]\\}, using colors to emphasize
338 keywords, etc. If the code fragments are not syntactically correct, no color
339 is added.
340 .TP
341 .B \-index\-only
342 Generate only index files.
343 .TP
344 .B \-short\-functors
345 Use a short form to display functors:
346 .B "module M : functor (A:Module) -> functor (B:Module2) -> sig .. end"
347 is displayed as
348 .BR "module M (A:Module) (B:Module2) : sig .. end" .
349 .SS "Options for generating LaTeX files"
350 The following options apply in conjunction with the
351 .B \-latex
352 option:
353 .TP
354 .B \-latex\-value\-prefix prefix
355 Give a prefix to use for the labels of the values in the generated LaTeX
356 document. The default prefix is the empty string. You can also use the options
357 .BR -latex-type-prefix ,
358 .BR -latex-exception-prefix ,
359 .BR -latex-module-prefix ,
360 .BR -latex-module-type-prefix ,
361 .BR -latex-class-prefix ,
362 .BR -latex-class-type-prefix ,
363 .BR -latex-attribute-prefix ,\ and
364 .BR -latex-method-prefix .
365
366 These options are useful when you have, for example, a type and a value
367 with the same name. If you do not specify prefixes, LaTeX will complain about
368 multiply defined labels.
369 .TP
370 .BI \-latextitle \ n,style
371 Associate style number
372 .I n
373 to the given LaTeX sectioning command
374 .IR style ,
375 e.g.
376 .BR section or subsection .
377 (LaTeX only.) This is useful when including the generated document in another
378 LaTeX document, at a given sectioning level. The default association is 1 for
379 section, 2 for subsection, 3 for subsubsection, 4 for paragraph and 5 for
380 subparagraph.
381 .TP
382 .B \-noheader
383 Suppress header in generated documentation.
384 .TP
385 .B \-notoc
386 Do not generate a table of contents.
387 .TP
388 .B \-notrailer
389 Suppress trailer in generated documentation.
390 .TP
391 .B \-sepfiles
392 Generate one .tex file per toplevel module, instead of the global
393 .I ocamldoc.out
394 file.
395 .SS "Options for generating TeXinfo files"
396 The following options apply in conjunction with the
397 .B -texi
398 option:
399 .TP
400 .B \-esc8
401 Escape accented characters in Info files.
402 .TP
403 .B
404 \-info\-entry
405 Specify Info directory entry.
406 .TP
407 .B \-info\-section
408 Specify section of Info directory.
409 .TP
410 .B \-noheader
411 Suppress header in generated documentation.
412 .TP
413 .B \-noindex
414 Do not build index for Info files.
415 .TP
416 .B \-notrailer
417 Suppress trailer in generated documentation.
418 .SS "Options for generating dot graphs"
419 The following options apply in conjunction with the
420 .B \-dot
421 option:
422 .TP
423 .BI \-dot\-colors \ colors
424 Specify the colors to use in the generated dot code. When generating module
425 dependencies,
426 .BR ocamldoc (1)
427 uses different colors for modules, depending on the directories in which they
428 reside. When generating types dependencies,
429 .BR ocamldoc (1)
430 uses different colors for types, depending on the modules in which they are
431 defined.
432 .I colors
433 is a list of color names separated by commas (,), as in
434 .BR Red,Blue,Green .
435 The available colors are the ones supported by the
436 .BR dot (1)
437 tool.
438 .TP
439 .B \-dot\-include\-all
440 Include all modules in the
441 .BR dot (1)
442 output, not only modules given on the command line or loaded with the
443 .B \-load
444 option.
445 .TP
446 .B \-dot\-reduce
447 Perform a transitive reduction of the dependency graph before outputting the
448 dot code. This can be useful if there are a lot of transitive dependencies
449 that clutter the graph.
450 .TP
451 .B \-dot\-types
452 Output dot code describing the type dependency graph instead of the module
453 dependency graph.
454 .SS "Options for generating man files"
455 The following options apply in conjunction with the
456 .B \-man
457 option:
458 .TP
459 .B \-man\-mini
460 Generate man pages only for modules, module types, classes and class types,
461 instead of pages for all elements.
462 .TP
463 .BI \-man\-suffix \ suffix
464 Set the suffix used for generated man filenames. Default is o, as in
465 .IR List.o .
466 .TP
467 .BI \-man\-section \ section
468 Set the section number used for generated man filenames. Default is 3.
469
470
471 .SH SEE ALSO
472 .BR ocaml (1),
473 .BR ocamlc (1),
474 .BR ocamlopt (1).
475 .br
476 .IR "The OCaml user's manual",
477 chapter "The documentation generator".
478