NAME¶
ocamldoc - The Objective Caml documentation generator
SYNOPSIS¶
ocamldoc [
options ]
filename ...
DESCRIPTION¶
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).
- -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
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. 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:
Pervasives,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 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.
- -mflags
- 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.
- -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 Objective Caml 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.
- -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-suffixsuffix
- Set the suffix used for generated man filenames. Default is
o, as in List.o.
- -man-sectionsection
- Set the section number used for generated man filenames.
Default is 3.
SEE ALSO¶
ocaml(1),
ocamlc(1),
ocamlopt(1).
The Objective Caml user's manual, chapter "The documentation
generator".
