Tribblix: manual page: ocamldoc.1

OCAMLDOC(1) User Commands OCAMLDOC(1)

NAME

ocamldoc - The OCaml documentation generator

SYNOPSIS

ocamldoc [ options ] filename ...

DESCRIPTION

The OCaml 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 OCaml 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. The file 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(1). The
dot(1) tool is available from https://graphviz.org/. 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.
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, and in the directories specified
with the -i option.

-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 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 commas (,), without blanks. For instance:
Stdlib,M2.M3.

-inv-merge-ml-mli
Reverse the precedence of 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 the source code to be always
kept.

-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.

-open module
Opens module before typing.

-pp command
Pipe sources through preprocessor command.

-ppx command
Pipe abstract syntax tree through preprocessor command.

-show-missed-crossref
Show missed cross-reference opportunities.

-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.

-text file
Consider file as a .txt file.

-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.

-version
Print version string and exit.

-vnum Print short version number and exit.

-warn-error
Treat ocamldoc warnings as errors.

-hide-warnings
Do not print ocamldoc warnings.

-help or --help
Display a short usage summary and exit.

Type-checking options
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 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.

-charset s
Add information about character encoding being s (default is
iso-8859-1).

-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.

-short-functors
Use a short form to display functors: module M : functor
(A:Module) -> functor (B:Module2) -> sig .. end is displayed
as module M (A:Module) (B:Module2) : sig .. end.

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. sectionorsubsection. (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 commas (,), 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 suffix
Set the suffix used for generated man filenames. Default is o,
as in List.o.

-man-section section
Set the section number used for generated man filenames.
Default is 3.