ocamldoc - The OCaml documentation generator
ocamldoc [ options ] filename ...
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.
The following command-line options determine the format for the
generated documentation generated by ocamldoc(1).
- -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.
- -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.
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).)
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.
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.
- 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.
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.
- Suppress header in generated documentation.
- -noindex
- Do not build index for Info files.
- -notrailer
- Suppress trailer in generated documentation.
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.
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.