1OCAMLDOC(1) General Commands Manual OCAMLDOC(1)
2
6 ocamldoc - The OCaml documentation generator
7
11 ocamldoc [ options ] filename ...
12
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 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 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
32 The following command-line options determine the format for the gener‐
33 ated documentation generated by ocamldoc(1).
34 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 -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 -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 -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 -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 -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 -customdir
75 Display the custom generators default directory.
76 -i directory
78 Add the given directory to the path where to look for custom
79 generators.
80 General options
82 -d dir Generate files in directory dir, rather than the current direc‐
83 tory.
84 -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 -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 -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 -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 -load file
108 Load information from file, which has been produced by ocaml‐
109 doc -dump. Several -load options can be given.
110 -m flags
112 Specify merge options between interfaces and implementations.
113 flags can be one or several of the following characters:
114 d merge description
116 a merge @author
118 v merge @version
120 l merge @see
122 s merge @since
124 o merge @deprecated
126 p merge @param
128 e merge @raise
130 r merge @return
132 A merge everything
134 -no-custom-tags
136 Do not allow custom @-tags.
137 -no-stop
139 Keep elements placed after the (**/**) special comment.
140 -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 -pp command
147 Pipe sources through preprocessor command.
148 -ppx command
150 Pipe abstract syntax tree through preprocessor command.
151 -show-missed-crossref
153 Show missed cross-reference opportunities.
154 -sort Sort the list of top-level modules before generating the docu‐
156 mentation.
157 -stars Remove blank characters until the first asterisk ('*') in each
159 line of comments.
160 -t title
162 Use title as the title for the generated documentation.
163 -text file
165 Consider file as a .txt file.
166 -intro file
168 Use content of file as ocamldoc text to use as introduction
169 (HTML, LaTeX and TeXinfo only). For HTML, the file is used to
170 create the whole "index.html" file.
171 -v Verbose mode. Display progress information.
173 -version
175 Print version string and exit.
176 -vnum Print short version number and exit.
178 -warn-error
180 Treat ocamldoc warnings as errors.
181 -hide-warnings
183 Do not print ocamldoc warnings.
184 -help or --help
186 Display a short usage summary and exit.
187 Type-checking options
189 ocamldoc(1) calls the OCaml type-checker to obtain type information.
190 The following options impact the type-checking phase. They have the
191 same meaning as for the ocamlc(1) and ocamlopt(1) commands.
192 -I directory
194 Add directory to the list of directories search for compiled
195 interface files (.cmi files).
196 -nolabels
198 Ignore non-optional labels in types.
199 -rectypes
201 Allow arbitrary recursive types. (See the -rectypes option to
202 ocamlc(1).)
203 Options for generating HTML pages
205 The following options apply in conjunction with the -html option:
206 -all-params
208 Display the complete list of parameters for functions and meth‐
209 ods.
210 -charset s
212 Add information about character encoding being s (default is
213 iso-8859-1).
214 -css-style filename
216 Use filename as the Cascading Style Sheet file.
217 -colorize-code
219 Colorize the OCaml code enclosed in [ ] and \{[ ]\}, using col‐
220 ors to emphasize keywords, etc. If the code fragments are not
221 syntactically correct, no color is added.
222 -index-only
224 Generate only index files.
225 -short-functors
227 Use a short form to display functors: module M : functor (A:Mod‐
228 ule) -> functor (B:Module2) -> sig .. end is displayed as module
229 M (A:Module) (B:Module2) : sig .. end.
230 Options for generating LaTeX files
232 The following options apply in conjunction with the -latex option:
233 -latex-value-prefix prefix
235 Give a prefix to use for the labels of the values in the gener‐
236 ated LaTeX document. The default prefix is the empty string. You
237 can also use the options -latex-type-prefix, -latex-exception-
238 prefix, -latex-module-prefix, -latex-module-type-prefix, -latex-
239 class-prefix, -latex-class-type-prefix, -latex-attribute-pre‐
240 fix, and -latex-method-prefix.
241 These options are useful when you have, for example, a type and
243 a value with the same name. If you do not specify prefixes,
244 LaTeX will complain about multiply defined labels.
245 -latextitle n,style
247 Associate style number n to the given LaTeX sectioning command
248 style, e.g. sectionorsubsection. (LaTeX only.) This is useful
249 when including the generated document in another LaTeX document,
250 at a given sectioning level. The default association is 1 for
251 section, 2 for subsection, 3 for subsubsection, 4 for paragraph
252 and 5 for subparagraph.
253 -noheader
255 Suppress header in generated documentation.
256 -notoc Do not generate a table of contents.
258 -notrailer
260 Suppress trailer in generated documentation.
261 -sepfiles
263 Generate one .tex file per toplevel module, instead of the
264 global ocamldoc.out file.
265 Options for generating TeXinfo files
267 The following options apply in conjunction with the -texi option:
268 -esc8 Escape accented characters in Info files.
270 -info-entry
272 Specify Info directory entry.
273 -info-section
275 Specify section of Info directory.
276 -noheader
278 Suppress header in generated documentation.
279 -noindex
281 Do not build index for Info files.
282 -notrailer
284 Suppress trailer in generated documentation.
285 Options for generating dot graphs
287 The following options apply in conjunction with the -dot option:
288 -dot-colors colors
290 Specify the colors to use in the generated dot code. When gener‐
291 ating module dependencies, ocamldoc(1) uses different colors for
292 modules, depending on the directories in which they reside. When
293 generating types dependencies, ocamldoc(1) uses different colors
294 for types, depending on the modules in which they are defined.
295 colors is a list of color names separated by commas (,), as in
296 Red,Blue,Green. The available colors are the ones supported by
297 the dot(1) tool.
298 -dot-include-all
300 Include all modules in the dot(1) output, not only modules given
301 on the command line or loaded with the -load option.
302 -dot-reduce
304 Perform a transitive reduction of the dependency graph before
305 outputting the dot code. This can be useful if there are a lot
306 of transitive dependencies that clutter the graph.
307 -dot-types
309 Output dot code describing the type dependency graph instead of
310 the module dependency graph.
311 Options for generating man files
313 The following options apply in conjunction with the -man option:
314 -man-mini
316 Generate man pages only for modules, module types, classes and
317 class types, instead of pages for all elements.
318 -man-suffix suffix
320 Set the suffix used for generated man filenames. Default is o,
321 as in List.o.
322 -man-section section
324 Set the section number used for generated man filenames. Default
325 is 3.
326
330 ocaml(1), ocamlc(1), ocamlopt(1).
331 The OCaml user's manual, chapter "The documentation generator".
332 OCAMLDOC(1)