1OCAMLDOC(1)                 General Commands Manual                OCAMLDOC(1)
2
3
4

NAME

6       ocamldoc - The OCaml documentation generator
7
8
9

SYNOPSIS

11       ocamldoc [ options ] filename ...
12
13

DESCRIPTION

15       The  OCaml  documentation generator ocamldoc(1) generates documentation
16       from special comments embedded in source files. The  comments  used  by
17       ocamldoc  are of the form (** ... *) and follow the format described in
18       the The OCaml user's manual.
19
20       ocamldoc can produce documentation in  various  formats:  HTML,  LaTeX,
21       TeXinfo,  Unix man pages, and dot(1) dependency graphs. Moreover, users
22       can add their own custom generators.
23
24       In this manpage, we use the word element to refer to any of the follow‐
25       ing  parts of an OCaml source file: a type declaration, a value, a mod‐
26       ule, an exception, a module type, a type constructor, a record field, a
27       class,  a  class type, a class method, a class value or a class inheri‐
28       tance clause.
29
30

OPTIONS

32       The following command-line options determine the format for the  gener‐
33       ated documentation generated by ocamldoc(1).
34
35   Options for choosing the output format
36       -html  Generate  documentation  in  HTML  default format. The generated
37              HTML pages are stored in the current directory, or in the direc‐
38              tory  specified  with the -d option. You can customize the style
39              of the generated pages by editing the generated style.css  file,
40              or  by  providing  your own style sheet using option -css-style.
41              The file style.css is not generated if it already exists.
42
43       -latex Generate documentation in LaTeX default  format.  The  generated
44              LaTeX  document  is  saved  in file ocamldoc.out, or in the file
45              specified with the -o option. The document uses the  style  file
46              ocamldoc.sty.   This  file  is  generated  when using the -latex
47              option, if it does not already exist. You can change  this  file
48              to customize the style of your LaTeX documentation.
49
50       -texi  Generate  documentation in TeXinfo default format. The generated
51              LaTeX document is saved in file ocamldoc.out,  or  in  the  file
52              specified with the -o option.
53
54       -man   Generate documentation as a set of Unix man pages. The generated
55              pages are stored in the current directory, or in  the  directory
56              specified with the -d option.
57
58       -dot   Generate  a dependency graph for the toplevel modules, in a for‐
59              mat suitable for  displaying  and  processing  by  dot(1).   The
60              dot(1)          tool          is          available         from
61              http://www.research.att.com/sw/tools/graphviz/.    The   textual
62              representation of the graph is written to the file ocamldoc.out,
63              or to the file specified with  the  -o  option.  Use  dot ocaml‐
64              doc.out to display it.
65
66       -g file
67              Dynamically load the given file (which extension usually is .cmo
68              or .cma), which defines a custom  documentation  generator.   If
69              the given file is a simple one and does not exist in the current
70              directory, then ocamldoc looks for it in the  custom  generators
71              default  directory, and in the directories specified with the -i
72              option.
73
74       -customdir
75              Display the custom generators default directory.
76
77       -i directory
78              Add the given directory to the path where  to  look  for  custom
79              generators.
80
81   General options
82       -d dir Generate  files in directory dir, rather than the current direc‐
83              tory.
84
85       -dump file
86              Dump collected information into file.  This information  can  be
87              read  with the -load option in a subsequent invocation of ocaml‐
88              doc(1).
89
90       -hide modules
91              Hide the given complete module names in the generated documenta‐
92              tion.   modules is a list of complete module names are separated
93              by commas (,), without blanks. For instance: Pervasives,M2.M3.
94
95       -inv-merge-ml-mli
96              Reverse the precedence of implementations  and  interfaces  when
97              merging.  All elements in implementation files are kept, and the
98              -m option indicates which parts of  the  comments  in  interface
99              files are merged with the comments in implementation files.
100
101       -keep-code
102              Always  keep  the  source  code for values, methods and instance
103              variables, when available. The source code is always kept when a
104              .ml  file  is  given, but is by default discarded when a .mli is
105              given. This option allows the source code to be always kept.
106
107       -load file
108              Load information from file, which has been  produced  by  ocaml‐
109              doc -dump.  Several -load options can be given.
110
111       -m flags
112              Specify  merge  options  between interfaces and implementations.
113              flags can be one or several of the following characters:
114
115              d merge description
116
117              a merge @author
118
119              v merge @version
120
121              l merge @see
122
123              s merge @since
124
125              o merge @deprecated
126
127              p merge @param
128
129              e merge @raise
130
131              r merge @return
132
133              A merge everything
134
135       -no-custom-tags
136              Do not allow custom @-tags.
137
138       -no-stop
139              Keep elements placed after the (**/**) special comment.
140
141       -o file
142              Output the generated documentation to  file  instead  of  ocaml‐
143              doc.out.  This option is meaningful only in conjunction with the
144              -latex, -texi, or -dot options.
145
146       -pp command
147              Pipe sources through preprocessor command.
148
149       -ppx command
150              Pipe abstract syntax tree through preprocessor command.
151
152       -sort  Sort the list of top-level modules before generating  the  docu‐
153              mentation.
154
155       -stars Remove  blank  characters until the first asterisk ('*') in each
156              line of comments.
157
158       -t title
159              Use title as the title for the generated documentation.
160
161       -intro file
162              Use content of file as ocamldoc  text  to  use  as  introduction
163              (HTML,  LaTeX  and TeXinfo only).  For HTML, the file is used to
164              create the whole "index.html" file.
165
166       -v     Verbose mode. Display progress information.
167
168       -version
169              Print version string and exit.
170
171       -vnum  Print short version number and exit.
172
173       -warn-error
174              Treat ocamldoc warnings as errors.
175
176       -hide-warnings
177              Do not print ocamldoc warnings.
178
179       -help or --help
180              Display a short usage summary and exit.
181
182   Type-checking options
183       ocamldoc(1) calls the OCaml type-checker to  obtain  type  information.
184       The  following  options  impact  the type-checking phase. They have the
185       same meaning as for the ocamlc(1) and ocamlopt(1) commands.
186
187       -I directory
188              Add directory to the list of  directories  search  for  compiled
189              interface files (.cmi files).
190
191       -nolabels
192              Ignore non-optional labels in types.
193
194       -rectypes
195               Allow  arbitrary  recursive types. (See the -rectypes option to
196              ocamlc(1).)
197
198   Options for generating HTML pages
199       The following options apply in conjunction with the -html option:
200
201       -all-params
202              Display the complete list of parameters for functions and  meth‐
203              ods.
204
205       -css-style filename
206              Use filename as the Cascading Style Sheet file.
207
208       -colorize-code
209              Colorize  the OCaml code enclosed in [ ] and \{[ ]\}, using col‐
210              ors to emphasize keywords, etc. If the code  fragments  are  not
211              syntactically correct, no color is added.
212
213       -index-only
214              Generate only index files.
215
216       -short-functors
217              Use a short form to display functors: module M : functor (A:Mod‐
218              ule) -> functor (B:Module2) -> sig .. end is displayed as module
219              M (A:Module) (B:Module2) : sig .. end.
220
221   Options for generating LaTeX files
222       The following options apply in conjunction with the -latex option:
223
224       -latex-value-prefix prefix
225              Give  a prefix to use for the labels of the values in the gener‐
226              ated LaTeX document. The default prefix is the empty string. You
227              can  also  use the options -latex-type-prefix, -latex-exception-
228              prefix, -latex-module-prefix, -latex-module-type-prefix, -latex-
229              class-prefix,   -latex-class-type-prefix,  -latex-attribute-pre‐
230              fix, and -latex-method-prefix.
231
232              These options are useful when you have, for example, a type  and
233              a  value  with  the  same  name. If you do not specify prefixes,
234              LaTeX will complain about multiply defined labels.
235
236       -latextitle n,style
237              Associate style number n to the given LaTeX  sectioning  command
238              style,  e.g.  sectionorsubsection.  (LaTeX only.) This is useful
239              when including the generated document in another LaTeX document,
240              at  a  given  sectioning level. The default association is 1 for
241              section, 2 for subsection, 3 for subsubsection, 4 for  paragraph
242              and 5 for subparagraph.
243
244       -noheader
245              Suppress header in generated documentation.
246
247       -notoc Do not generate a table of contents.
248
249       -notrailer
250              Suppress trailer in generated documentation.
251
252       -sepfiles
253              Generate  one  .tex  file  per  toplevel  module, instead of the
254              global ocamldoc.out file.
255
256   Options for generating TeXinfo files
257       The following options apply in conjunction with the -texi option:
258
259       -esc8  Escape accented characters in Info files.
260
261       -info-entry
262              Specify Info directory entry.
263
264       -info-section
265              Specify section of Info directory.
266
267       -noheader
268              Suppress header in generated documentation.
269
270       -noindex
271              Do not build index for Info files.
272
273       -notrailer
274              Suppress trailer in generated documentation.
275
276   Options for generating dot graphs
277       The following options apply in conjunction with the -dot option:
278
279       -dot-colors colors
280              Specify the colors to use in the generated dot code. When gener‐
281              ating module dependencies, ocamldoc(1) uses different colors for
282              modules, depending on the directories in which they reside. When
283              generating types dependencies, ocamldoc(1) uses different colors
284              for types, depending on the modules in which they  are  defined.
285              colors  is  a list of color names separated by commas (,), as in
286              Red,Blue,Green.  The available colors are the ones supported  by
287              the dot(1) tool.
288
289       -dot-include-all
290              Include all modules in the dot(1) output, not only modules given
291              on the command line or loaded with the -load option.
292
293       -dot-reduce
294              Perform a transitive reduction of the  dependency  graph  before
295              outputting  the  dot code. This can be useful if there are a lot
296              of transitive dependencies that clutter the graph.
297
298       -dot-types
299              Output dot code describing the type dependency graph instead  of
300              the module dependency graph.
301
302   Options for generating man files
303       The following options apply in conjunction with the -man option:
304
305       -man-mini
306              Generate  man  pages only for modules, module types, classes and
307              class types, instead of pages for all elements.
308
309       -man-suffix suffix
310              Set the suffix used for generated man filenames. Default  is  o,
311              as in List.o.
312
313       -man-section section
314              Set the section number used for generated man filenames. Default
315              is 3.
316
317
318

SEE ALSO

320       ocaml(1), ocamlc(1), ocamlopt(1).
321       The OCaml user's manual, chapter "The documentation generator".
322
323
324
325                                                                   OCAMLDOC(1)
Impressum