693 lines
15 KiB
HTML
693 lines
15 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of OCAMLDOC</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>OCAMLDOC</H1>
|
|
Section: User Commands (1)<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<P>
|
|
<P>
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
ocamldoc - The OCaml documentation generator
|
|
<P>
|
|
<P>
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>ocamldoc</B>
|
|
|
|
[
|
|
<I>options</I>
|
|
|
|
]
|
|
<I>filename</I> ...
|
|
|
|
<P>
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<P>
|
|
The OCaml documentation generator
|
|
<B><A HREF="/cgi-bin/man/man2html?1+ocamldoc">ocamldoc</A></B>(1)
|
|
|
|
generates documentation from special comments embedded in source files. The
|
|
comments used by
|
|
<B>ocamldoc</B>
|
|
|
|
are of the form
|
|
<I>(** ... *)</I>
|
|
|
|
and follow the format described in the
|
|
<I>The OCaml user's manual</I>.
|
|
|
|
<P>
|
|
<B>ocamldoc</B>
|
|
|
|
can produce documentation in various formats: HTML, LaTeX, TeXinfo,
|
|
Unix man pages, and
|
|
<B><A HREF="/cgi-bin/man/man2html?1+dot">dot</A></B>(1)
|
|
|
|
dependency graphs. Moreover, users can add their own
|
|
custom generators.
|
|
<P>
|
|
In this manpage, we use the word
|
|
<I>element</I>
|
|
|
|
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.
|
|
<P>
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
<P>
|
|
The following command-line options determine the format for the generated
|
|
documentation generated by
|
|
<B><A HREF="/cgi-bin/man/man2html?1+ocamldoc">ocamldoc</A></B>(1).
|
|
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Options for choosing the output format</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="1"><B>-html</B>
|
|
|
|
<DD>
|
|
Generate documentation in HTML default format. The generated HTML pages are
|
|
stored in the current directory, or in the directory specified with the
|
|
<B>-d</B>
|
|
|
|
option. You can customize the style of the generated pages by editing the
|
|
generated
|
|
<I>style.css</I>
|
|
|
|
file, or by providing your own style sheet using option
|
|
<B>-css-style</B>.
|
|
|
|
The file
|
|
<I>style.css</I>
|
|
|
|
is not generated if it already exists.
|
|
<DT id="2"><B>-latex</B>
|
|
|
|
<DD>
|
|
Generate documentation in LaTeX default format. The generated LaTeX document
|
|
is saved in file
|
|
<I>ocamldoc.out</I>,
|
|
|
|
or in the file specified with the
|
|
<B>-o</B>
|
|
|
|
option. The document uses the style file
|
|
<I>ocamldoc.sty</I>.
|
|
|
|
This file is generated when using the
|
|
<B>-latex</B>
|
|
|
|
option, if it does not already exist. You can change this file to customize
|
|
the style of your LaTeX documentation.
|
|
<DT id="3"><B>-texi</B>
|
|
|
|
<DD>
|
|
Generate documentation in TeXinfo default format. The generated LaTeX document
|
|
is saved in file
|
|
<I>ocamldoc.out</I>,
|
|
|
|
or in the file specified with the
|
|
<B>-o</B>
|
|
|
|
option.
|
|
<DT id="4"><B>-man</B>
|
|
|
|
<DD>
|
|
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
|
|
<B>-d</B>
|
|
|
|
option.
|
|
<DT id="5"><B>-dot</B>
|
|
|
|
<DD>
|
|
Generate a dependency graph for the toplevel modules, in a format suitable for
|
|
displaying and processing by
|
|
<I><A HREF="/cgi-bin/man/man2html?1+dot">dot</A></I>(1).
|
|
|
|
The
|
|
<I><A HREF="/cgi-bin/man/man2html?1+dot">dot</A></I>(1)
|
|
|
|
tool is available from
|
|
<I><A HREF="https://graphviz.org/">https://graphviz.org/</A></I>.
|
|
|
|
The textual representation of the graph is written to the file
|
|
<I>ocamldoc.out</I>,
|
|
|
|
or to the file specified with the
|
|
<B>-o</B>
|
|
|
|
option. Use
|
|
<B>dot</B><I> ocamldoc.out</I>
|
|
|
|
to display it.
|
|
<DT id="6"><B>-g</B><I> file</I>
|
|
|
|
<DD>
|
|
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
|
|
<B>ocamldoc</B>
|
|
|
|
looks for it in the custom
|
|
generators default directory, and in the directories specified with the
|
|
<B>-i</B>
|
|
|
|
option.
|
|
<DT id="7"><B>-customdir</B>
|
|
|
|
<DD>
|
|
Display the custom generators default directory.
|
|
<DT id="8"><B>-i</B><I> directory</I>
|
|
|
|
<DD>
|
|
Add the given directory to the path where to look for custom generators.
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H3>General options</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="9"><B>-d</B><I> dir</I>
|
|
|
|
<DD>
|
|
Generate files in directory
|
|
<I>dir</I>,
|
|
|
|
rather than the current directory.
|
|
<DT id="10"><B>-dump</B><I> file</I>
|
|
|
|
<DD>
|
|
Dump collected information into
|
|
<I>file</I>.
|
|
|
|
This information can be read with the
|
|
<B>-load</B>
|
|
|
|
option in a subsequent invocation of
|
|
<B><A HREF="/cgi-bin/man/man2html?1+ocamldoc">ocamldoc</A></B>(1).
|
|
|
|
<DT id="11"><B>-hide</B><I> modules</I>
|
|
|
|
<DD>
|
|
Hide the given complete module names in the generated documentation.
|
|
<I>modules</I>
|
|
|
|
is a list of complete module names are separated by commas (,),
|
|
without blanks. For instance:
|
|
<I>Stdlib,M2.M3</I>.
|
|
|
|
<DT id="12"><B>-inv-merge-ml-mli</B>
|
|
|
|
<DD>
|
|
Reverse the precedence of implementations and interfaces when merging.
|
|
All elements in implementation files are kept, and the
|
|
<B>-m</B>
|
|
|
|
option indicates which parts of the comments in interface files are merged with
|
|
the comments in implementation files.
|
|
<DT id="13"><B>-keep-code</B>
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="14"><B>-load</B><I> file</I>
|
|
|
|
<DD>
|
|
Load information from
|
|
<I>file</I>,
|
|
|
|
which has been produced by
|
|
<B>ocamldoc -dump</B>.
|
|
|
|
Several
|
|
<B>-load</B>
|
|
|
|
options can be given.
|
|
<DT id="15"><B>-m</B><I> flags</I>
|
|
|
|
<DD>
|
|
Specify merge options between interfaces and implementations.
|
|
<I>flags</I>
|
|
|
|
can be one or several of the following characters:
|
|
<P>
|
|
<B>d</B>
|
|
|
|
merge description
|
|
<P>
|
|
<B>a</B>
|
|
|
|
merge @author
|
|
<P>
|
|
<B>v</B>
|
|
|
|
merge @version
|
|
<P>
|
|
<B>l</B>
|
|
|
|
merge @see
|
|
<P>
|
|
<B>s</B>
|
|
|
|
merge @since
|
|
<P>
|
|
<B>o</B>
|
|
|
|
merge @deprecated
|
|
<P>
|
|
<B>p</B>
|
|
|
|
merge @param
|
|
<P>
|
|
<B>e</B>
|
|
|
|
merge @raise
|
|
<P>
|
|
<B>r</B>
|
|
|
|
merge @return
|
|
<P>
|
|
<B>A</B>
|
|
|
|
merge everything
|
|
<DT id="16"><B>-no-custom-tags</B>
|
|
|
|
<DD>
|
|
Do not allow custom @-tags.
|
|
<DT id="17"><B>-no-stop</B>
|
|
|
|
<DD>
|
|
Keep elements placed after the
|
|
<B>(**/**)</B>
|
|
|
|
special comment.
|
|
<DT id="18"><B>-o</B><I> file</I>
|
|
|
|
<DD>
|
|
Output the generated documentation to
|
|
<I>file</I>
|
|
|
|
instead of
|
|
<I>ocamldoc.out</I>.
|
|
|
|
This option is meaningful only in conjunction with the
|
|
<B>-latex</B>,<B> -texi</B>, or<B> -dot</B>
|
|
|
|
options.
|
|
<DT id="19"><B>-open</B><I> module</I>
|
|
|
|
<DD>
|
|
Opens
|
|
<I>module</I>
|
|
|
|
before typing.
|
|
<DT id="20"><B>-pp</B><I> command</I>
|
|
|
|
<DD>
|
|
Pipe sources through preprocessor
|
|
<I>command</I>.
|
|
|
|
<DT id="21"><B>-ppx</B><I> command</I>
|
|
|
|
<DD>
|
|
Pipe abstract syntax tree through preprocessor
|
|
<I>command</I>.
|
|
|
|
<DT id="22"><B>-show-missed-crossref</B>
|
|
|
|
<DD>
|
|
Show missed cross-reference opportunities.
|
|
<DT id="23"><B>-sort</B>
|
|
|
|
<DD>
|
|
Sort the list of top-level modules before generating the documentation.
|
|
<DT id="24"><B>-stars</B>
|
|
|
|
<DD>
|
|
Remove blank characters until the first asterisk ('*') in each line of comments.
|
|
<DT id="25"><B>-t</B><I> title</I>
|
|
|
|
<DD>
|
|
Use
|
|
<I>title</I>
|
|
|
|
as the title for the generated documentation.
|
|
<DT id="26"><B>-text</B><I> file</I>
|
|
|
|
<DD>
|
|
Consider <I>file</I> as a .txt file.
|
|
<DT id="27"><B>-intro</B><I> file</I>
|
|
|
|
<DD>
|
|
Use content of
|
|
<I>file</I>
|
|
|
|
as
|
|
<B>ocamldoc</B>
|
|
|
|
text to use as introduction (HTML, LaTeX and TeXinfo only).
|
|
For HTML, the file is used to create the whole "index.html" file.
|
|
<DT id="28"><B>-v</B>
|
|
|
|
<DD>
|
|
Verbose mode. Display progress information.
|
|
<DT id="29"><B>-version</B>
|
|
|
|
<DD>
|
|
Print version string and exit.
|
|
<DT id="30"><B>-vnum</B>
|
|
|
|
<DD>
|
|
Print short version number and exit.
|
|
<DT id="31"><B>-warn-error</B>
|
|
|
|
<DD>
|
|
Treat
|
|
<B>ocamldoc</B>
|
|
|
|
warnings as errors.
|
|
<DT id="32"><B>-hide-warnings</B>
|
|
|
|
<DD>
|
|
Do not print
|
|
<B>ocamldoc</B>
|
|
|
|
warnings.
|
|
<DT id="33"><B>-help</B> or<B> --help</B>
|
|
|
|
<DD>
|
|
Display a short usage summary and exit.
|
|
</DL>
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Type-checking options</H3>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+ocamldoc">ocamldoc</A></B>(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
|
|
<B><A HREF="/cgi-bin/man/man2html?1+ocamlc">ocamlc</A></B>(1) and<B> <A HREF="/cgi-bin/man/man2html?1+ocamlopt">ocamlopt</A></B>(1)
|
|
|
|
commands.
|
|
<DL COMPACT>
|
|
<DT id="34"><B>-I</B><I> directory</I>
|
|
|
|
<DD>
|
|
Add
|
|
<I>directory</I>
|
|
|
|
to the list of directories search for compiled interface files (.cmi files).
|
|
<DT id="35"><B>-nolabels</B>
|
|
|
|
<DD>
|
|
Ignore non-optional labels in types.
|
|
<DT id="36"><B>-rectypes</B>
|
|
|
|
<DD>
|
|
<BR> Allow arbitrary recursive types. (See the
|
|
<B>-rectypes</B>
|
|
|
|
option to
|
|
<B><A HREF="/cgi-bin/man/man2html?1+ocamlc">ocamlc</A></B>(1).)
|
|
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H3>Options for generating HTML pages</H3>
|
|
|
|
The following options apply in conjunction with the
|
|
<B>-html</B>
|
|
|
|
option:
|
|
<DL COMPACT>
|
|
<DT id="37"><B>-all-params</B>
|
|
|
|
<DD>
|
|
Display the complete list of parameters for functions and methods.
|
|
<DT id="38"><B>-charset</B><I> s</I>
|
|
|
|
<DD>
|
|
Add information about character encoding being <I>s</I>
|
|
(default is <B>iso-8859-1</B>).
|
|
<DT id="39"><B>-css-style</B><I> filename</I>
|
|
|
|
<DD>
|
|
Use
|
|
<I>filename</I>
|
|
|
|
as the Cascading Style Sheet file.
|
|
<DT id="40"><B>-colorize-code</B>
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="41"><B>-index-only</B>
|
|
|
|
<DD>
|
|
Generate only index files.
|
|
<DT id="42"><B>-short-functors</B>
|
|
|
|
<DD>
|
|
Use a short form to display functors:
|
|
<B>module M : functor (A:Module) -> functor (B:Module2) -> sig .. end</B>
|
|
|
|
is displayed as
|
|
<B>module M (A:Module) (B:Module2) : sig .. end</B>.
|
|
|
|
</DL>
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>Options for generating LaTeX files</H3>
|
|
|
|
The following options apply in conjunction with the
|
|
<B>-latex</B>
|
|
|
|
option:
|
|
<DL COMPACT>
|
|
<DT id="43"><B>-latex-value-prefix prefix</B>
|
|
|
|
<DD>
|
|
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
|
|
<B>-latex-type-prefix</B>,
|
|
|
|
<B>-latex-exception-prefix</B>,
|
|
|
|
<B>-latex-module-prefix</B>,
|
|
|
|
<B>-latex-module-type-prefix</B>,
|
|
|
|
<B>-latex-class-prefix</B>,
|
|
|
|
<B>-latex-class-type-prefix</B>,
|
|
|
|
<B>-latex-attribute-prefix</B>, and
|
|
|
|
<B>-latex-method-prefix</B>.
|
|
|
|
<P>
|
|
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.
|
|
<DT id="44"><B>-latextitle</B><I> n,style</I>
|
|
|
|
<DD>
|
|
Associate style number
|
|
<I>n</I>
|
|
|
|
to the given LaTeX sectioning command
|
|
<I>style</I>,
|
|
|
|
e.g.
|
|
<B>section</B>or<B>subsection</B>.
|
|
|
|
(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.
|
|
<DT id="45"><B>-noheader</B>
|
|
|
|
<DD>
|
|
Suppress header in generated documentation.
|
|
<DT id="46"><B>-notoc</B>
|
|
|
|
<DD>
|
|
Do not generate a table of contents.
|
|
<DT id="47"><B>-notrailer</B>
|
|
|
|
<DD>
|
|
Suppress trailer in generated documentation.
|
|
<DT id="48"><B>-sepfiles</B>
|
|
|
|
<DD>
|
|
Generate one .tex file per toplevel module, instead of the global
|
|
<I>ocamldoc.out</I>
|
|
|
|
file.
|
|
</DL>
|
|
<A NAME="lbAK"> </A>
|
|
<H3>Options for generating TeXinfo files</H3>
|
|
|
|
The following options apply in conjunction with the
|
|
<B>-texi</B>
|
|
|
|
option:
|
|
<DL COMPACT>
|
|
<DT id="49"><B>-esc8</B>
|
|
|
|
<DD>
|
|
Escape accented characters in Info files.
|
|
<DT id="50"><B>-info-entry</B>
|
|
|
|
<DD>
|
|
Specify Info directory entry.
|
|
<DT id="51"><B>-info-section</B>
|
|
|
|
<DD>
|
|
Specify section of Info directory.
|
|
<DT id="52"><B>-noheader</B>
|
|
|
|
<DD>
|
|
Suppress header in generated documentation.
|
|
<DT id="53"><B>-noindex</B>
|
|
|
|
<DD>
|
|
Do not build index for Info files.
|
|
<DT id="54"><B>-notrailer</B>
|
|
|
|
<DD>
|
|
Suppress trailer in generated documentation.
|
|
</DL>
|
|
<A NAME="lbAL"> </A>
|
|
<H3>Options for generating dot graphs</H3>
|
|
|
|
The following options apply in conjunction with the
|
|
<B>-dot</B>
|
|
|
|
option:
|
|
<DL COMPACT>
|
|
<DT id="55"><B>-dot-colors</B><I> colors</I>
|
|
|
|
<DD>
|
|
Specify the colors to use in the generated dot code. When generating module
|
|
dependencies,
|
|
<B><A HREF="/cgi-bin/man/man2html?1+ocamldoc">ocamldoc</A></B>(1)
|
|
|
|
uses different colors for modules, depending on the directories in which they
|
|
reside. When generating types dependencies,
|
|
<B><A HREF="/cgi-bin/man/man2html?1+ocamldoc">ocamldoc</A></B>(1)
|
|
|
|
uses different colors for types, depending on the modules in which they are
|
|
defined.
|
|
<I>colors</I>
|
|
|
|
is a list of color names separated by commas (,), as in
|
|
<B>Red,Blue,Green</B>.
|
|
|
|
The available colors are the ones supported by the
|
|
<B><A HREF="/cgi-bin/man/man2html?1+dot">dot</A></B>(1)
|
|
|
|
tool.
|
|
<DT id="56"><B>-dot-include-all</B>
|
|
|
|
<DD>
|
|
Include all modules in the
|
|
<B><A HREF="/cgi-bin/man/man2html?1+dot">dot</A></B>(1)
|
|
|
|
output, not only modules given on the command line or loaded with the
|
|
<B>-load</B>
|
|
|
|
option.
|
|
<DT id="57"><B>-dot-reduce</B>
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="58"><B>-dot-types</B>
|
|
|
|
<DD>
|
|
Output dot code describing the type dependency graph instead of the module
|
|
dependency graph.
|
|
</DL>
|
|
<A NAME="lbAM"> </A>
|
|
<H3>Options for generating man files</H3>
|
|
|
|
The following options apply in conjunction with the
|
|
<B>-man</B>
|
|
|
|
option:
|
|
<DL COMPACT>
|
|
<DT id="59"><B>-man-mini</B>
|
|
|
|
<DD>
|
|
Generate man pages only for modules, module types, classes and class types,
|
|
instead of pages for all elements.
|
|
<DT id="60"><B>-man-suffix</B><I> suffix</I>
|
|
|
|
<DD>
|
|
Set the suffix used for generated man filenames. Default is o, as in
|
|
<I>List.o</I>.
|
|
|
|
<DT id="61"><B>-man-section</B><I> section</I>
|
|
|
|
<DD>
|
|
Set the section number used for generated man filenames. Default is 3.
|
|
<P>
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAN"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+ocaml">ocaml</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+ocamlc">ocamlc</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+ocamlopt">ocamlopt</A></B>(1).
|
|
|
|
<BR>
|
|
|
|
<I>The OCaml user's manual,</I>
|
|
|
|
chapter "The documentation generator".
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="62"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="63"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="64"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="65"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DL>
|
|
<DT id="66"><A HREF="#lbAF">Options for choosing the output format</A><DD>
|
|
<DT id="67"><A HREF="#lbAG">General options</A><DD>
|
|
<DT id="68"><A HREF="#lbAH">Type-checking options</A><DD>
|
|
<DT id="69"><A HREF="#lbAI">Options for generating HTML pages</A><DD>
|
|
<DT id="70"><A HREF="#lbAJ">Options for generating LaTeX files</A><DD>
|
|
<DT id="71"><A HREF="#lbAK">Options for generating TeXinfo files</A><DD>
|
|
<DT id="72"><A HREF="#lbAL">Options for generating dot graphs</A><DD>
|
|
<DT id="73"><A HREF="#lbAM">Options for generating man files</A><DD>
|
|
</DL>
|
|
<DT id="74"><A HREF="#lbAN">SEE ALSO</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:20 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|