The Objective Caml documentation generator
ocamldoc(1) generates documentation from special comments embedded in source files. The
comments used by OCamldoc are of the form
(**...*) and follow the format described in the
"The Objective Caml user's manual" .
OCamldoc can produce documentation in various formats: HTML, LaTeX, TeXinfo,
Unix man pages, and
dot(1) dependency graphs. Moreover, users can add their own
custom generators.
In this manpage, we use the word
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.
OPTIONS
The following command-line options determine the format for the generated
documentation generated by
ocamldoc(1) .
"Options for choosing the output format"
-html
Generate documentation in HTML default format. The generated HTML pages are
stored in the current directory, or in the directory specified with the
-d option. You can customize the style of the generated pages by editing the
generated
style.css file, or by providing your own style sheet using option
-css-style style.css is not generated if it already exists.
-latex
Generate documentation in LaTeX default format. The generated LaTeX document
is saved in file
ocamldoc.out , or in the file specified with the
-o option. The document uses the style file
ocamldoc.sty . This file is generated when using the
-latex option, if it does not already exist. You can change this file to customize
the style of your LaTeX documentation.
-texi
Generate documentation in TeXinfo default format. The generated LaTeX document
is saved in file
ocamldoc.out , or in the file specified with the
-o option.
-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
-d option.
-dot
Generate a dependency graph for the toplevel modules, in a format suitable for
displaying and processing by dot. The
dot(1) tool is available from
http://www.research.att.com/sw/tools/graphviz/ . The textual representation of the graph is written to the file
ocamldoc.out , or to the file specified with the
-o option. Use
dot ocamldoc.out to display it.
-g file
Dynamically load the given file (which extension usually is .cmo or .cma),
which defines a custom documentation generator. This option is supported by the
ocamldoc(1) command, but not by its native-code version
ocamldoc.opt . If the given file is a simple one and does not exist in
the current directory, then ocamldoc looks for it in the custom
generators default directory.
-customdir
Display the custom generators default directory.
-i directory
Add the given directory to the path where to look for custom generators.
"General options"
-d dir
Generate files in directory
dir , rather than in the current directory.
-dump file
Dump collected information into file. This information can be read with the
-load option in a subsequent invocation of
ocamldoc(1) .
-hide modules
Hide the given complete module names in the generated documentation.
modules is a list of complete module names are separated by ',', without blanks. For
instance:
Pervasives,M2.M3 .
-inv-merge-ml-mli
Inverse implementations and interfaces when merging. All elements in
implementation files are kept, and the
-m option indicates which parts of the comments in interface files are merged with
the comments in implementation files.
-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.
-load file
Load information from
file , which has been produced by
ocamldoc -dump . Several
-load options can be given.
-m flags
Specify merge options between interfaces and implementations.
flags can be one or several of the following characters:
d merge description
a merge @author
v merge @version
l merge @see
s merge @since
o merge @deprecated
p merge @param
e merge @raise
r merge @return
A merge everything
-no-custom-tags
Do not allow custom @-tags.
-no-stop
Keep elements placed after the
(**/**) special comment.
-o file
Output the generated documentation to
file instead of
ocamldoc.out . This option is meaningful only in conjunction with the
-latex , -texi , or
-dot options.
-pp command
Pipe sources through preprocessor command.
-sort
Sort the list of top-level modules before generating the documentation.
-stars
Remove blank characters until the first asterisk ('*') in each line of comments.
-t title
Use
title as the title for the generated documentation.
-intro file
Use content of
file as ocamldoc text to use as introduction (HTML, LaTeX and TeXinfo only).
For HTML, the file is used to create the whole "index.html" file.
-v
Verbose mode. Display progress information.
-warn-error
Treat warnings as errors.
"Type-checking options"
ocamldoc(1) calls the Objective Caml type-checker to obtain type informations. The
following options impact the type-checking phase. They have the same meaning
as for the
ocamlc(1) and
ocamlopt(1) commands.
-I directory
Add directory to the list of directories search for compiled interface files
(.cmi files).
-nolabels
Ignore non-optional labels in types.
-rectypes
Allow arbitrary recursive types. (See the
-rectypes option to
ocamlc(1) .)
"Options for generating HTML pages"
The following options apply in conjunction with the
-html option:
-all-params
Display the complete list of parameters for functions and methods.
-css-style filename
Use filename as the Cascading Style Sheet file.
-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.
-index-only
Generate only index files.
"Options for generating LaTeX files"
The following options apply in conjunction with the
-latex option:
-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
-latex-type-prefix , -latex-exception-prefix , -latex-module-prefix , -latex-module-type-prefix , -latex-class-prefix , -latex-class-type-prefix , -latex-attribute-prefix and
-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.
-latextitle n,style
Associate style number
n to the given LaTeX sectioning command style, e.g. 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.
-noheader
Suppress header in generated documentation.
-notoc
Do not generate a table of contents.
-notrailer
Suppress trailer in generated documentation.
-sepfiles
Generate one .tex file per toplevel module, instead of the global
ocamldoc.out file.
"Options for generating TeXinfo files"
The following options apply in conjunction with the
-texi option:
-esc8
Escape accented characters in Info files.
-info-entry
Specify Info directory entry.
-info-section
Specify section of Info directory.
-noheader
Suppress header in generated documentation.
-noindex
Do not build index for Info files.
-notrailer
Suppress trailer in generated documentation.
"Options for generating dot graphs"
The following options apply in conjunction with the
-dot option:
-dot-colors colors
Specify the colors to use in the generated dot code. When generating module
dependencies,
ocamldoc(1) uses different colors for modules, depending on the directories in which they
reside. When generating types dependencies,
ocamldoc(1) uses different colors for types, depending on the modules in which they are
defined. colors is a list of color names separated by ',', as in
Red,Blue,Green . The available colors are the ones supported by the
dot(1) tool.
-dot-include-all
Include all modules in the
dot(1) output, not only modules given on the command line or loaded with the
-load option.
-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.
-dot-types
Output dot code describing the type dependency graph instead of the module
dependency graph.
"Options for generating man files"
The following options apply in conjunction with the
-man option:
-man-mini
Generate man pages only for modules, module types, classes and class types,
instead of pages for all elements.
-man-suffix
Set the suffix used for generated man filenames. Default is 'o', like in
List.o .