Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Thursday, March 14, 2019

ocamldoc (1)


ocamldoc - The Objective Caml documentation generator


ocamldoc [ options ] filename ...


OCAMLDOC(1)                 General Commands Manual                OCAMLDOC(1)

       ocamldoc - The Objective Caml documentation generator

       ocamldoc [ options ] filename ...

       The  Objective Caml documentation generator ocamldoc(1) generates docu-
       mentation 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 follow-
       ing  parts of an OCaml source file: a type declaration, a value, a mod-
       ule, 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 inheri-
       tance clause.

       The following command-line options determine the format for the  gener-
       ated 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 direc-
              tory  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 for-
              mat 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 ocaml-
              doc.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

              Display the custom generators default directory.

       -i directory
              Add the given directory to the path where  to  look  for  custom

   General options
       -d dir Generate  files in directory dir, rather than the current direc-

       -dump file
              Dump collected information into file.  This information  can  be
              read  with the -load option in a subsequent invocation of ocaml-

       -hide modules
              Hide the given complete module names in the generated documenta-
              tion.   modules is a list of complete module names are separated
              by commas (,), without blanks. For instance: Pervasives,M2.M3.

              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.

              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  ocaml-
              doc -dump.  Several -load options can be given.

              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

              Do not allow custom @-tags.

              Keep elements placed after the (**/**) special comment.

       -o file
              Output the generated documentation to  file  instead  of  ocaml-
              doc.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  docu-

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

              Print the version string and exit.

              Treat Ocamldoc warnings as errors.

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

              Ignore non-optional labels in types.

               Allow  arbitrary  recursive types. (See the -rectypes option to

   Options for generating HTML pages
       The following options apply in conjunction with the -html option:

              Display the complete list of parameters for functions and  meth-

       -css-style filename
              Use filename as the Cascading Style Sheet file.

              Colorize  the OCaml code enclosed in [ ] and \{[ ]\}, using col-
              ors to emphasize keywords, etc. If the code  fragments  are  not
              syntactically correct, no color is added.

              Generate only index files.

              Use a short form to display functors: module M : functor (A:Mod-
              ule) -> 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 gener-
              ated 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-pre-
              fix, 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.

              Suppress trailer in generated documentation.

              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.

              Specify Info directory entry.

              Specify section of Info directory.

              Suppress header in generated documentation.

              Do not build index for Info files.

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

              Include all modules in the dot(1) output, not only modules given
              on the command line or loaded with the -load option.

              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.

              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:

              Generate  man  pages only for modules, module types, classes and
              class types, instead of pages for all elements.

              Set the suffix used for generated man filenames. Default  is  o,
              as in List.o.

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

       See attributes(7) for descriptions of the following attributes:

       |Availability   | runtime/ocaml    |
       |Stability      | Volatile         |
       ocaml(1), ocamlc(1), ocamlopt(1).
       The Objective Caml user's manual, chapter  "The  documentation  genera-

       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source      was      downloaded     from      http://caml.inria.fr/dis-

       Further information about this software can be found on the open source
       community website at http://www.ocaml.org.