OCAMLDOC(1)

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

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