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