Source

mutated_ocaml / man / ocamldoc.m

Full commit
camlspotter 35cc436 











camlspotter 4eace9a 
camlspotter 35cc436 
j...@vmware 743bd00 











camlspotter 35cc436 
j...@vmware 743bd00 










camlspotter 35cc436 
j...@vmware 743bd00 

camlspotter 35cc436 


j...@vmware 743bd00 

camlspotter 35cc436 
j...@vmware 743bd00 
camlspotter 35cc436 

j...@vmware 743bd00 












































































camlspotter b4974e6 
j...@vmware 743bd00 
camlspotter 35cc436 


j...@vmware 743bd00 


























































































































camlspotter 4eace9a 
camlspotter 35cc436 

j...@vmware 743bd00 





camlspotter 2f3f8b6 



j...@vmware 743bd00 

camlspotter 35cc436 


j...@vmware 743bd00 

camlspotter 35cc436 


j...@vmware 743bd00 




camlspotter 35cc436 
j...@vmware 743bd00 










































































































































































camlspotter 35cc436 
j...@vmware 743bd00 
  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
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
.\"***********************************************************************
.\"*                                                                     *
.\"*                                OCaml                                *
.\"*                                                                     *
.\"*            Maxence Guesdon, projet Cristal, INRIA Rocquencourt      *
.\"*                                                                     *
.\"*  Copyright 2004 Institut National de Recherche en Informatique et   *
.\"*  en Automatique.  All rights reserved.  This file is distributed    *
.\"*  under the terms of the Q Public License version 1.0.               *
.\"*                                                                     *
.\"***********************************************************************
.\"
.\" $Id: ocamldoc.m 12800 2012-07-30 18:59:07Z doligez $
.\"
.TH OCAMLDOC 1

\" .de Sh \" Subsection heading
\" .br
\" .if t .Sp
\" .ne 5
\" .PP
\" \fB\\$1\fR
\" .PP
\" ..

.SH NAME
ocamldoc \- The OCaml documentation generator


.SH SYNOPSIS
.B ocamldoc
[
.I options
]
.IR filename \ ...

.SH DESCRIPTION

The OCaml documentation generator
.BR ocamldoc (1)
generates documentation from special comments embedded in source files. The
comments used by
.B ocamldoc
are of the form
.I (** ... *)
and follow the format described in the
.IR "The OCaml user's manual" .

.B ocamldoc
can produce documentation in various formats: HTML, LaTeX, TeXinfo,
Unix man pages, and
.BR dot (1)
dependency graphs. Moreover, users can add their own
custom generators.

In this manpage, we use the word
.I element
to refer to any of the following parts of an OCaml source file: a type
declaration, a value, a module, an exception, a module type, a type
constructor, a record field, a class, a class type, a class method, a class
value or a class inheritance clause.

.SH OPTIONS

The following command-line options determine the format for the generated
documentation generated by
.BR ocamldoc (1).
.SS "Options for choosing the output format"
.TP
.B \-html
Generate documentation in HTML default format. The generated HTML pages are
stored in the current directory, or in the directory specified with the
.B \-d
option. You can customize the style of the generated pages by editing the
generated
.I style.css
file, or by providing your own style sheet using option
.BR \-css\-style .
The file
.I style.css
is not generated if it already exists.
.TP
.B \-latex
Generate documentation in LaTeX default format. The generated LaTeX document
is saved in file
.IR ocamldoc.out ,
or in the file specified with the
.B -o
option. The document uses the style file
.IR ocamldoc.sty .
This file is generated when using the
.B \-latex
option, if it does not already exist. You can change this file to customize
the style of your LaTeX documentation.
.TP
.B \-texi
Generate documentation in TeXinfo default format. The generated LaTeX document
is saved in file
.IR ocamldoc.out ,
or in the file specified with the
.B -o
option.
.TP
.B \-man
Generate documentation as a set of Unix man pages. The generated pages are
stored in the current directory, or in the directory specified with the
.B \-d
option.
.TP
.B \-dot
Generate a dependency graph for the toplevel modules, in a format suitable for
displaying and processing by
.IR dot (1).
The
.IR dot (1)
tool is available from
.IR http://www.research.att.com/sw/tools/graphviz/ .
The textual representation of the graph is written to the file
.IR ocamldoc.out ,
or to the file specified with the
.B -o
option. Use
.BI dot \ ocamldoc.out
to display it.
.TP
.BI \-g \ file
Dynamically load the given file (which extension usually is .cmo or .cma),
which defines a custom documentation generator.
If the given file is a simple one and does not exist in
the current directory, then
.B ocamldoc
looks for it in the custom
generators default directory, and in the directories specified with the
.B \-i
option.
.TP
.BI \-customdir
Display the custom generators default directory.
.TP
.BI \-i \ directory
Add the given directory to the path where to look for custom generators.
.SS "General options"
.TP
.BI \-d \ dir
Generate files in directory
.IR dir ,
rather than the current directory.
.TP
.BI \-dump \ file
Dump collected information into
.IR file .
This information can be read with the
.B \-load
option in a subsequent invocation of
.BR ocamldoc (1).
.TP
.BI \-hide \ modules
Hide the given complete module names in the generated documentation.
.I modules
is a list of complete module names are separated by commas (,),
without blanks. For instance:
.IR Pervasives,M2.M3 .
.TP
.B \-inv\-merge\-ml\-mli
Reverse the precedence of implementations and interfaces when merging.
All elements in implementation files are kept, and the
.B \-m
option indicates which parts of the comments in interface files are merged with
the comments in implementation files.
.TP
.B \-keep\-code
Always keep the source code for values, methods and instance variables, when
available. The source code is always kept when a .ml
file is given, but is by default discarded when a .mli
is given. This option allows to always keep the source code.
.TP
.BI \-load \ file
Load information from
.IR file ,
which has been produced by
.BR ocamldoc\ \-dump .
Several
.B -load
options can be given.
.TP
.BI \-m flags
Specify merge options between interfaces and implementations.
.I flags
can be one or several of the following characters:

.B d
merge description

.B a
merge @author

.B v
merge @version

.B l
merge @see

.B s
merge @since

.B o
merge @deprecated

.B p
merge @param

.B e
merge @raise

.B r
merge @return

.B A
merge everything
.TP
.B \-no\-custom\-tags
Do not allow custom @-tags.
.TP
.B \-no\-stop
Keep elements placed after the
.B (**/**)
special comment.
.TP
.BI \-o \ file
Output the generated documentation to
.I file
instead of
.IR ocamldoc.out .
This option is meaningful only in conjunction with the
.BR \-latex , \ \-texi ,\ or \ \-dot
options.
.TP
.BI \-pp \ command
Pipe sources through preprocessor
.IR command .
.TP
.B \-sort
Sort the list of top-level modules before generating the documentation.
.TP
.B \-stars
Remove blank characters until the first asterisk ('*') in each line of comments.
.TP
.BI \-t \ title
Use
.I title
as the title for the generated documentation.
.TP
.BI \-intro \ file
Use content of
.I file
as
.B ocamldoc
text to use as introduction (HTML, LaTeX and TeXinfo only).
For HTML, the file is used to create the whole "index.html" file.
.TP
.B \-v
Verbose mode. Display progress information.
.TP
.B \-version
Print version string and exit.
.TP
.B \-vnum
Print short version number and exit.
.TP
.B \-warn\-error
Treat
.B ocamldoc
warnings as errors.
.TP
.B \-hide\-warnings
Do not print
.B ocamldoc
warnings.
.TP
.BR \-help \ or \ \-\-help
Display a short usage summary and exit.
.SS "Type-checking options"
.BR ocamldoc (1)
calls the OCaml type-checker to obtain type information. The
following options impact the type-checking phase. They have the same meaning
as for the
.BR ocamlc (1)\ and \ ocamlopt (1)
commands.
.TP
.BI \-I \ directory
Add
.I directory
to the list of directories search for compiled interface files (.cmi files).
.TP
.B \-nolabels
Ignore non-optional labels in types.
.TP
.B \-rectypes
 Allow arbitrary recursive types. (See the
.B \-rectypes
option to
.BR ocamlc (1).)
.SS "Options for generating HTML pages"
The following options apply in conjunction with the
.B \-html
option:
.TP
.B \-all\-params
Display the complete list of parameters for functions and methods.
.TP
.BI \-css\-style \ filename
Use
.I filename
as the Cascading Style Sheet file.
.TP
.B \-colorize\-code
Colorize the OCaml code enclosed in [ ] and \\{[ ]\\}, using colors to emphasize
keywords, etc. If the code fragments are not syntactically correct, no color
is added.
.TP
.B \-index\-only
Generate only index files.
.TP
.B \-short\-functors
Use a short form to display functors:
.B "module M : functor (A:Module) -> functor (B:Module2) -> sig .. end"
is displayed as
.BR "module M (A:Module) (B:Module2) : sig .. end" .
.SS "Options for generating LaTeX files"
The following options apply in conjunction with the
.B \-latex
option:
.TP
.B \-latex\-value\-prefix prefix
Give a prefix to use for the labels of the values in the generated LaTeX
document. The default prefix is the empty string. You can also use the options
.BR -latex-type-prefix ,
.BR -latex-exception-prefix ,
.BR -latex-module-prefix ,
.BR -latex-module-type-prefix ,
.BR -latex-class-prefix ,
.BR -latex-class-type-prefix ,
.BR -latex-attribute-prefix ,\ and
.BR -latex-method-prefix .

These options are useful when you have, for example, a type and a value
with the same name. If you do not specify prefixes, LaTeX will complain about
multiply defined labels.
.TP
.BI \-latextitle \ n,style
Associate style number
.I n
to the given LaTeX sectioning command
.IR style ,
e.g.
.BR section or subsection .
(LaTeX only.) This is useful when including the generated document in another
LaTeX document, at a given sectioning level. The default association is 1 for
section, 2 for subsection, 3 for subsubsection, 4 for paragraph and 5 for
subparagraph.
.TP
.B \-noheader
Suppress header in generated documentation.
.TP
.B \-notoc
Do not generate a table of contents.
.TP
.B \-notrailer
Suppress trailer in generated documentation.
.TP
.B \-sepfiles
Generate one .tex file per toplevel module, instead of the global
.I ocamldoc.out
file.
.SS "Options for generating TeXinfo files"
The following options apply in conjunction with the
.B -texi
option:
.TP
.B \-esc8
Escape accented characters in Info files.
.TP
.B
\-info\-entry
Specify Info directory entry.
.TP
.B \-info\-section
Specify section of Info directory.
.TP
.B \-noheader
Suppress header in generated documentation.
.TP
.B \-noindex
Do not build index for Info files.
.TP
.B \-notrailer
Suppress trailer in generated documentation.
.SS "Options for generating dot graphs"
The following options apply in conjunction with the
.B \-dot
option:
.TP
.BI \-dot\-colors \ colors
Specify the colors to use in the generated dot code. When generating module
dependencies,
.BR ocamldoc (1)
uses different colors for modules, depending on the directories in which they
reside. When generating types dependencies,
.BR ocamldoc (1)
uses different colors for types, depending on the modules in which they are
defined.
.I colors
is a list of color names separated by commas (,), as in
.BR Red,Blue,Green .
The available colors are the ones supported by the
.BR dot (1)
tool.
.TP
.B \-dot\-include\-all
Include all modules in the
.BR dot (1)
output, not only modules given on the command line or loaded with the
.B \-load
option.
.TP
.B \-dot\-reduce
Perform a transitive reduction of the dependency graph before outputting the
dot code. This can be useful if there are a lot of transitive dependencies
that clutter the graph.
.TP
.B \-dot\-types
Output dot code describing the type dependency graph instead of the module
dependency graph.
.SS "Options for generating man files"
The following options apply in conjunction with the
.B \-man
option:
.TP
.B \-man\-mini
Generate man pages only for modules, module types, classes and class types,
instead of pages for all elements.
.TP
.BI \-man\-suffix suffix
Set the suffix used for generated man filenames. Default is o, as in
.IR List.o .
.TP
.BI \-man\-section section
Set the section number used for generated man filenames. Default is 3.


.SH SEE ALSO
.BR ocaml (1),
.BR ocamlc (1),
.BR ocamlopt (1).
.br
.IR "The OCaml user's manual",
chapter "The documentation generator".