<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.06-7 of 2001-11-14">
<TITLE>
The documentation generator (ocamldoc)
</TITLE>
</HEAD>
<BODY TEXT=black BGCOLOR=white>
<A HREF="manual028.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<A HREF="manual030.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#2de52d"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc147"><B><FONT SIZE=6>Chapter 15</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=6>The documentation generator (ocamldoc)</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE> <A NAME="c:ocamldoc"></A>
<BR>
This chapter describes OCamldoc, a tool that generates documentation from
special comments embedded in source files. The comments used by OCamldoc
are of the form <TT>(**</TT>...<TT>*)</TT> and follow the format described
in section <A HREF="#s:ocamldoc-comments">15.2</A>.<BR>
<BR>
OCamldoc can produce documentation in various formats: HTML, L<sup>A</sup>T<sub>E</sub>X,
TeXinfo, Unix man pages, and <TT>dot</TT> dependency graphs. Moreover,
users can add their own custom generators, as explained in
section <A HREF="#s:ocamldoc-custom-generators">15.3</A>.<BR>
<BR>
In this chapter, we use the word <EM>element</EM> 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.<BR>
<BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#66ff66"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc148"><B><FONT SIZE=5>15.1</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=5>Usage</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE> <A NAME="s:ocamldoc-usage"></A><BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#7fff7f"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc149"><B><FONT SIZE=4>15.1.1</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=4>Invocation</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><BR>
OCamldoc is invoked via the command <TT>ocamldoc</TT>, as follows:
<PRE>
ocamldoc <I>options</I> <I>sourcefiles</I>
</PRE>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98ff98"><DIV ALIGN=center><TABLE>
<TR><TD><B>Options for choosing the output format</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><BR>
The following options determine the format for the generated
documentation.
<DL COMPACT=compact><DT>
<B><TT>-html</TT></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><TT>-d</TT></B> option. You can customize the style of the
generated pages by editing the generated <TT>style.css</TT> file, or by providing
your own style sheet using option <TT>-css-style</TT>.<BR>
<BR>
<DT><B><TT>-latex</TT></B><DD>
Generate documentation in L<sup>A</sup>T<sub>E</sub>X default format. The generated
L<sup>A</sup>T<sub>E</sub>X document is saved in file <TT>ocamldoc.out</TT>, or in the file
specified with the <B><TT>-o</TT></B> option. The document uses the style file
<TT>ocamldoc.sty</TT> included in the OCamldoc distribution. You can change
this file to customize the style of your L<sup>A</sup>T<sub>E</sub>X documentation.<BR>
<BR>
<DT><B><TT>-texi</TT></B><DD>
Generate documentation in TeXinfo default format. The generated
L<sup>A</sup>T<sub>E</sub>X document is saved in file <TT>ocamldoc.out</TT>, or in the file
specified with the <B><TT>-o</TT></B> option.<BR>
<BR>
<DT><B><TT>-man</TT></B><DD>
Generate documentation as a set of Unix <TT>man</TT> pages. The generated pages
are stored in the current directory, or in the directory specified
with the <B><TT>-d</TT></B> option.<BR>
<BR>
<DT><B><TT>-dot</TT></B><DD>
Generate a dependency graph for the toplevel modules, in a format suitable
for displaying and processing by <TT>dot</TT>. The <TT>dot</TT> tool is available from
<A HREF="http://www.research.att.com/sw/tools/graphviz/"><TT>http://www.research.att.com/sw/tools/graphviz/</TT></A>.
The textual representation of the graph is written to the file
<TT>ocamldoc.out</TT>, or to the file specified with the <B><TT>-o</TT></B> option.
Use <TT>dot ocamldoc.out</TT> to display it.<BR>
<BR>
<DT><B><TT>-g</TT> <I>file.cm[o,a]</I></B><DD>
Dynamically load the given file, which defines a custom documentation
generator. See section <A HREF="#s:ocamldoc-compilation-and-usage">15.4.1</A>. This
option is supported by the <TT>ocamldoc</TT> command, but not by its
native-code version <TT>ocamldoc.opt</TT>.</DL>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98ff98"><DIV ALIGN=center><TABLE>
<TR><TD><B>General options</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
<DL COMPACT=compact><DT><B><TT>-d</TT> <I>dir</I></B><DD>
Generate files in directory <I>dir</I>, rather than in the current directory.<BR>
<BR>
<DT><B><TT>-dump</TT> <I>file</I></B><DD>
Dump collected information into <I>file</I>. This information can be
read with the <TT>-load</TT> option in a subsequent invocation of <TT>ocamldoc</TT>.<BR>
<BR>
<DT><B><TT>-hide</TT> <I>modules</I></B><DD>
Hide the given complete module names in the generated documentation
<I>modules</I> is a list of complete module names are separated
by '<TT>,</TT>', without blanks. For instance: <TT>Pervasives,M2.M3</TT>.<BR>
<BR>
<DT><B><TT>-inv-merge-ml-mli</TT></B><DD>
Inverse implementations and interfaces when merging. All elements
in implementation files are kept, and the <B><TT>-m</TT></B> option
indicates which parts of the comments in interface files are merged
with the comments in implementation files.<BR>
<BR>
<DT><B><TT>-keep-code</TT></B><DD>
Always keep the source code for values, methods and instance variables,
when available.
The source code is always kept when a <TT>.ml</TT>
file is given, but is by default discarded when a <TT>.mli</TT> is given.
This option allows to always keep the source code.<BR>
<BR>
<DT><B><TT>-load</TT> <I>file</I></B><DD>
Load information from <I>file</I>, which has been produced by
<TT>ocamldoc -dump</TT>. Several <TT>-load</TT> options can be given.<BR>
<BR>
<DT><B><TT>-m</TT> <I>flags</I></B><DD>
Specify merge options between interfaces and implementations.
(see section <A HREF="#s:ocamldoc-merge">15.1.2</A> for details).
<I>flags</I> can be one or several of the following characters:
<DL COMPACT=compact><DT>
<B><TT>d</TT></B><DD> merge description
<DT><B><TT>a</TT></B><DD> merge @author
<DT><B><TT>v</TT></B><DD> merge @version
<DT><B><TT>l</TT></B><DD> merge @see
<DT><B><TT>s</TT></B><DD> merge @since
<DT><B><TT>o</TT></B><DD> merge @deprecated
<DT><B><TT>p</TT></B><DD> merge @param
<DT><B><TT>e</TT></B><DD> merge @raise
<DT><B><TT>r</TT></B><DD> merge @return
<DT><B><TT>A</TT></B><DD> merge everything
</DL><BR>
<BR>
<DT><B><TT>-no-custom-tags</TT></B><DD>
Do not allow custom @-tags (see section <A HREF="#s:ocamldoc-tags">15.2.5</A>).<BR>
<BR>
<DT><B><TT>-no-stop</TT></B><DD>
Keep elements placed after the <TT>(**/**)</TT> special comment
(see section <A HREF="#s:ocamldoc-comments">15.2</A>).<BR>
<BR>
<DT><B><TT>-o</TT> <I>file</I></B><DD>
Output the generated documentation to <I>file</I> instead of <TT>ocamldoc.out</TT>.
This option is meaningful only in conjunction with the
<B><TT>-latex</TT></B>, <B><TT>-texi</TT></B>, or <B><TT>-dot</TT></B> options.<BR>
<BR>
<DT><B><TT>-pp</TT> <I>command</I></B><DD>
Pipe sources through preprocessor <I>command</I>.<BR>
<BR>
<DT><B><TT>-sort</TT></B><DD>
Sort the list of top-level modules before generating the documentation.<BR>
<BR>
<DT><B><TT>-stars</TT></B><DD>
Remove blank characters until the first asterisk ('<TT>*</TT>') in each
line of comments.<BR>
<BR>
<DT><B><TT>-t</TT> <I>title</I></B><DD>
Use <I>title</I> as the title for the generated documentation.<BR>
<BR>
<DT><B><TT>-v</TT></B><DD>
Verbose mode. Display progress information.<BR>
<BR>
<DT><B><TT>-warn-error</TT></B><DD>
Treat warnings as errors.</DL>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98ff98"><DIV ALIGN=center><TABLE>
<TR><TD><B>Type-checking options</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><BR>
OCamldoc calls the Objective Caml type-checker to obtain type
informations. The following options impact the type-checking phase.
They have the same meaning as for the <TT>ocamlc</TT> and <TT>ocamlopt</TT> commands.
<DL COMPACT=compact><DT><B><TT>-I</TT> <I>directory</I></B><DD>
Add <I>directory</I> to the list of directories search for compiled
interface files (<TT>.cmi</TT> files).<BR>
<BR>
<DT><B><TT>-nolabels</TT></B><DD>
Ignore non-optional labels in types.<BR>
<BR>
<DT><B><TT>-rectypes</TT></B><DD>
Allow arbitrary recursive types. (See the <TT>-rectypes</TT> option to <TT>ocamlc</TT>.)</DL>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98ff98"><DIV ALIGN=center><TABLE>
<TR><TD><B>Options for generating HTML pages</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><BR>
The following options apply in conjunction with the <TT>-html</TT> option:
<DL COMPACT=compact><DT>
<B><TT>-all-params</TT></B><DD>
Display the complete list of parameters for functions and methods.<BR>
<BR>
<DT><B><TT>-css-style</TT> <I>filename</I></B><DD>
Use <I>filename</I> as the Cascading Style Sheet file.<BR>
<BR>
<DT><B><TT>-colorize-code</TT></B><DD>
Colorize the OCaml code enclosed in <TT>[ ]</TT> and <TT>\{[ ]\}</TT>, using colors
to emphasize keywords, etc. If the code fragments are not
syntactically correct, no color is added.<BR>
<BR>
<DT><B><TT>-index-only</TT></B><DD>
Generate only index files.</DL>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98ff98"><DIV ALIGN=center><TABLE>
<TR><TD><B>Options for generating L<sup>A</sup>T<sub>E</sub>X files</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><BR>
The following options apply in conjunction with the <TT>-latex</TT> option:
<DL COMPACT=compact><DT>
<B><TT>-latex-value-prefix</TT> <I>prefix</I></B><DD>
Give a prefix to use for the labels of the values in the generated L<sup>A</sup>T<sub>E</sub>X document.
The default prefix is the empty string. You can also use the options
<TT>-latex-type-prefix</TT>, <TT>-latex-exception-prefix</TT>, <TT>-latex-module-prefix</TT>,
<TT>-latex-module-type-prefix</TT>, <TT>-latex-class-prefix</TT>, <TT>-latex-class-type-prefix</TT>,
<TT>-latex-attribute-prefix</TT> and <TT>-latex-method-prefix</TT>.<BR>
<BR>
These options are useful when you have, for example, a type and a value with
the same name. If you do not specify prefixes, L<sup>A</sup>T<sub>E</sub>X will complain about
multiply defined labels.<BR>
<BR>
<DT><B><TT>-latextitle</TT> <I>n,style</I></B><DD>
Associate style number <I>n</I> to the given L<sup>A</sup>T<sub>E</sub>X sectioning command
<I>style</I>, e.g. <TT>section</TT> or <TT>subsection</TT>. (L<sup>A</sup>T<sub>E</sub>X only.) This is
useful when including the generated document in another L<sup>A</sup>T<sub>E</sub>X document,
at a given sectioning level. The default association is 1 for <TT>section</TT>,
2 for <TT>subsection</TT>, 3 for <TT>subsubsection</TT>, 4 for <TT>paragraph</TT> and 5 for
<TT>subparagraph</TT>.<BR>
<BR>
<DT><B><TT>-noheader</TT></B><DD>
Suppress header in generated documentation.<BR>
<BR>
<DT><B><TT>-notoc</TT></B><DD>
Do not generate a table of contents (L<sup>A</sup>T<sub>E</sub>X only).<BR>
<BR>
<DT><B><TT>-notrailer</TT></B><DD>
Suppress trailer in generated documentation.<BR>
<BR>
<DT><B><TT>-sepfiles</TT></B><DD>
Generate one <TT>.tex</TT> file per toplevel module, instead of the global
<TT>ocamldoc.out</TT> file.
</DL>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98ff98"><DIV ALIGN=center><TABLE>
<TR><TD><B>Options for generating TeXinfo files</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><BR>
The following options apply in conjunction with the <TT>-texi</TT> option:
<DL COMPACT=compact><DT>
<B><TT>-esc8</TT></B><DD>
Escape accented characters in Info files.<BR>
<BR>
<DT><B><TT>-noindex</TT></B><DD>
Do not build index for Info files.
</DL>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98ff98"><DIV ALIGN=center><TABLE>
<TR><TD><B>Options for generating <TT>dot</TT> graphs</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><BR>
The following options apply in conjunction with the <TT>-dot</TT> option:
<DL COMPACT=compact><DT>
<B><TT>-dot-colors</TT> <I>colors</I></B><DD>
Specify the colors to use in the generated <TT>dot</TT> code.
When generating module dependencies, <TT>ocamldoc</TT> uses different colors
for modules, depending on the directories in which they reside.
When generating types dependencies, <TT>ocamldoc</TT> 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 '<TT>,</TT>', as
in <TT>Red,Blue,Green</TT>. The available colors are the ones supported by
the <TT>dot</TT> tool.<BR>
<BR>
<DT><B><TT>-dot-include-all</TT></B><DD>
Include all modules in the <TT>dot</TT> output, not only modules given
on the command line or loaded with the <B><TT>-load</TT></B> option.<BR>
<BR>
<DT><B><TT>-dot-reduce</TT></B><DD>
Perform a transitive reduction of the dependency graph before
outputting the <TT>dot</TT> code. This can be useful if there are
a lot of transitive dependencies that clutter the graph.<BR>
<BR>
<DT><B><TT>-dot-types</TT></B><DD>
Output <TT>dot</TT> code describing the type dependency graph instead of
the module dependency graph.
</DL>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98ff98"><DIV ALIGN=center><TABLE>
<TR><TD><B>Options for generating man files</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><BR>
The following options apply in conjunction with the <TT>-man</TT> option:
<DL COMPACT=compact><DT>
<B><TT>-man-mini</TT></B><DD>
Generate man pages only for modules, module types, clases and class
types, instead of pages for all elements.<BR>
<BR>
<DT><B><TT>-man-suffix</TT></B><DD>
Set the suffix used for generated man filenames. Default is '<TT>o</TT>',
like in <TT>List.o</TT>.</DL>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#7fff7f"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc150"><B><FONT SIZE=4>15.1.2</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=4>Merging of module information</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
<A NAME="s:ocamldoc-merge"></A><BR>
Information on a module can be extracted either from the <TT>.mli</TT> or <TT>.ml</TT>
file, or both, depending on the files given on the command line.
When both <TT>.mli</TT> and <TT>.ml</TT> files are given for the same module,
information extracted from these files is merged according to the
following rules:
<UL><LI>
Only elements (values, types, classes, ...) declared in the <TT>.mli</TT>
file are kept. In other terms, definitions from the <TT>.ml</TT> file that are
not exported in the <TT>.mli</TT> file are not documented.
<LI>Descriptions of elements and descriptions in @-tags are handled
as follows. If a description for the same element or in the same
@-tag of the same element is present in both files, then the
description of the <TT>.ml</TT> file is concatenated to the one in the <TT>.mli</TT> file,
if the corresponding <TT>-m</TT> flag is given on the command line.
If a description is present in the <TT>.ml</TT> file and not in the
<TT>.mli</TT> file, the <TT>.ml</TT> description is kept.
In either case, all the information given in the <TT>.mli</TT> file is kept.
</UL>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#7fff7f"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc151"><B><FONT SIZE=4>15.1.3</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=4>Coding rules</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
<A NAME="s:ocamldoc-rules"></A>
The following rules must be respected in order to avoid name clashes
resulting in cross-reference errors:
<UL><LI>
In a module, there must not be two modules, two module types or
a module and a module type with the same name.
<LI>In a module, there must not be two classes, two class types or
a class and a class type with the same name.
<LI>In a module, there must not be two values, two types, or two
exceptions with the same name.
<LI>Values defined in tuple, as in <TT>let (x,y,z) = (1,2,3)</TT>
are not kept by OCamldoc.
<LI>Avoid the following construction:
<PRE>
open Foo (* which has a module Bar with a value x *)
module Foo =
struct
module Bar =
struct
let x = 1
end
end
let dummy = Bar.x
</PRE>In this case, OCamldoc will associate <TT>Bar.x</TT> to the <TT>x</TT> of module
<TT>Foo</TT> defined just above, instead of to the <TT>Bar.x</TT> defined in the
opened module <TT>Foo</TT>.
</UL>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#66ff66"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc152"><B><FONT SIZE=5>15.2</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=5>Syntax of documentation comments</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
<A NAME="s:ocamldoc-comments"></A><BR>
Comments containing documentation material are called <EM>special
comments</EM> and are written between <TT>(**</TT> and <TT>*)</TT>. Special comments
must start exactly with <TT>(**</TT>. Comments beginning with <TT>(</TT> and more
than two <TT>*</TT> are ignored.<BR>
<BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#7fff7f"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc153"><B><FONT SIZE=4>15.2.1</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=4>Placement of documentation comments</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
OCamldoc can associate comments to some elements of the language
encountered in the source files. The association is made according to
the locations of comments with respect to the language elements. The
locations of comments in <TT>.mli</TT> and <TT>.ml</TT> files are different.<BR>
<BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98ff98"><DIV ALIGN=center><TABLE>
<TR><TD><B>Comments in <TT>.mli</TT> files</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
A special comment is associated to an element if it is placed before or
after the element.<BR>
A special comment before an element is associated to this element if :
<UL><LI>
There is no blank line or another special comment between the special
comment and the element. However, a regular comment can occur between
the special comment and the element.
<LI>The special comment is not already associated to the previous element.
<LI>The special comment is not the first one of a toplevel module.
</UL>
A special comment after an element is associated to this element if
there is no blank line or comment between the special comment and the
element.<BR>
<BR>
There are two exceptions: for type constructors and record fields in
type definitions, the associated comment can only be placed after the
constructor or field definition, without blank lines or other comments
between them.<BR>
<BR>
The following sample interface file <TT>foo.mli</TT> illustrates the
placement rules for comments in <TT>.mli</TT> files.
<PRE>
(** The first special comment of the file is the comment associated
with the whole module.*)
(** Special comments can be placed between elements and are kept
by the OCamldoc tool, but are not associated to any element.
@-tags in these comments are ignored.*)
(*******************************************************************)
(** Comments like the one above, with more than two asterisks,
are ignored. *)
(** The comment for function f. *)
val f : int -> int -> int
(** The continuation of the comment for function f. *)
(** Comment for exception My_exception, even with a simple comment
between the special comment and the exception.*)
(* Hello, I'm a simple comment :-) *)
exception My_exception of (int -> int) * int
(** Comment for type weather *)
type weather =
| Rain of int (** The comment for construtor Rain *)
| Sun (** The comment for constructor Sun *)
(** Comment for type weather2 *)
type weather2 =
| Rain of int (** The comment for construtor Rain *)
| Sun (** The comment for constructor Sun *)
(** I can continue the comment for type weather2 here
because there is already a comment associated to the last constructor.*)
(** The comment for type my_record *)
type my_record = {
val foo : int ; (** Comment for field foo *)
val bar : string ; (** Comment for field bar *)
}
(** Continuation of comment for type my_record *)
(** Comment for foo *)
val foo : string
(** This comment is associated to foo and not to bar. *)
val bar : string
(** This comment is assciated to bar. *)
(** The comment for class my_class *)
class my_class :
object
(** A comment to describe inheritance from cl *)
inherit cl
(** The comment for attribute tutu *)
val mutable tutu : string
(** The comment for attribute toto. *)
val toto : int
(** This comment is not attached to titi since
there is a blank line before titi, but is kept
as a comment in the class. *)
val titi : string
(** Comment for method toto *)
method toto : string
(** Comment for method m *)
method m : float -> int
end
(** The comment for the class type my_class_type *)
class type my_class_type =
object
(** The comment for variable x. *)
val mutable x : int
(** The commend for method m. *)
method m : int -> int
end
(** The comment for module Foo *)
module Foo =
struct
(** The comment for x *)
val x : int
(** A special comment that is kept but not associated to any element *)
end
(** The comment for module type my_module_type. *)
module type my_module_type =
sig
(** The comment for value x. *)
val x : int
(** The comment for module M. *)
module M =
struct
(** The comment for value y. *)
val y : int
(* ... *)
end
end
</PRE>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98ff98"><DIV ALIGN=center><TABLE>
<TR><TD><B>Comments in <TT>.ml</TT> files</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><BR>
A special comment is associated to an element if it is placed before
the element and there is no blank line between the comment and the
element. Meanwhile, there can be a simple comment between the special
comment and the element. There are two exceptions, for type
constructors and record fields in type definitions, whose associated
comment must be placed after the constructor or field definition,
without blank line between them.<BR>
<BR>
The following example of file <TT>toto.ml</TT> shows where to place comments
in a <TT>.ml</TT> file.
<PRE>
(** The first special comment of the file is the comment associated
to the whole module.*)
(** The comment for function f *)
let f x y = x + y
(** This comment is not attached to any element since there is another
special comment just before the next element. *)
(** Comment for exception My_exception, even with a simple comment
between the special comment and the exception.*)
(* A simple comment. *)
exception My_exception of (int -> int) * int
(** Comment for type weather *)
type weather =
| Rain of int (** The comment for constructor Rain *)
| Sun (** The comment for constructor Sun *)
(** The comment for type my_record *)
type my_record = {
val foo : int ; (** Comment for field foo *)
val bar : string ; (** Comment for field bar *)
}
(** The comment for class my_class *)
class my_class =
object
(** A comment to describe inheritance from cl *)
inherit cl
(** The comment for the instance variable tutu *)
val mutable tutu = "tutu"
(** The comment for toto *)
val toto = 1
val titi = "titi"
(** Comment for method toto *)
method toto = tutu ^ "!"
(** Comment for method m *)
method m (f : float) = 1
end
(** The comment for class type my_class_type *)
class type my_class_type =
object
(** The comment for the instance variable x. *)
val mutable x : int
(** The commend for method m. *)
method m : int -> int
end
(** The comment for module Foo *)
module Foo =
struct
(** The comment for x *)
val x : int
(** A special comment in the class, but not associated to any element. *)
end
(** The comment for module type my_module_type. *)
module type my_module_type =
sig
(* Comment for value x. *)
val x : int
(* ... *)
end
</PRE>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#7fff7f"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc154"><B><FONT SIZE=4>15.2.2</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=4>The Stop special comment</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
The special comment <TT>(**/**)</TT> tells OCamldoc to discard
elements placed after this comment, up to the end of the current
class, class type, module or module type. For instance:
<PRE>
class type foo =
object
(** comment for method m *)
method m : string
(**/**)
(** This method won't appear in the documentation *)
method bar : int
end
(** This value appears in the documentation, since the Stop special comment
in the class does not affect the parent module of the class.*)
val foo : string
(**/**)
(** The value bar does not appear in the documentation.*)
val bar : string
(** The type t does not appear either. *)
type t = string
</PRE>
The <B><TT>-no-stop</TT></B> option to <TT>ocamldoc</TT> causes the Stop special
comments to be ignored.<BR>
<BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#7fff7f"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc155"><B><FONT SIZE=4>15.2.3</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=4>Syntax of documentation comments</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><BR>
The inside of documentation comments <TT>(**</TT>...<TT>*)</TT> consists of
free-form text with optional formatting annotations, followed by
optional <EM>tags</EM> giving more specific information about parameters,
version, authors, ... The tags are distinguished by a leading @
character. Thus, a documentation comment has the following shape:
<PRE>
(** The comment begins with a description, which is text formatted
according to the rules described in the next section.
The description continues until the first non-escaped '@' character.
@author Mr Smith
@param x description for parameter x
*)
</PRE>Some elements support only a subset of all @-tags. Tags that are not
relevant to the documented element are simply ignored. For instance,
all tags are ignored when documenting type constructors, record
fields, and class inheritance clauses. Similarly, a <TT>@param</TT> tag on a
class instance variable is ignored.<BR>
<BR>
At last, <TT>(**)</TT> is the empty documentation comment.<BR>
<BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#7fff7f"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc156"><B><FONT SIZE=4>15.2.4</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=4>Text formatting</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><BR>
Here is the BNF grammar for the simple markup language used to format
text descriptions.<BR>
<BR>
<I>text</I> ::= (<I>text_element</I>)<TT>+</TT><BR>
<I>text_element</I> ::= <BR>
<TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| {[0-9]+ <I>text</I>}</TT></TD>
<TD VALIGN=top ALIGN=left>format <I>text</I> as a section header;
the integer following <TT>{</TT> indicates the sectioning level.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| {[0-9]+:<I>label</I> <I>text</I>}</TT></TD>
<TD VALIGN=top ALIGN=left>same, but also associate the name <I>label</I> to the current point.
This point can be referenced by its fully-qualified label in a
<TT>{!</TT> command, just like any other element.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| {b <I>text</I>}</TT></TD>
<TD VALIGN=top ALIGN=left>set <I>text</I> in bold.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| {i <I>text</I>}</TT></TD>
<TD VALIGN=top ALIGN=left>set <I>text</I> in italic.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| {e <I>text</I>}</TT></TD>
<TD VALIGN=top ALIGN=left>emphasize <I>text</I>.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| {C <I>text</I>}</TT></TD>
<TD VALIGN=top ALIGN=left>center <I>text</I>.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| {L <I>text</I>}</TT></TD>
<TD VALIGN=top ALIGN=left>left align <I>text</I>.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| {R <I>text</I>}</TT></TD>
<TD VALIGN=top ALIGN=left>right align <I>text</I>.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| {ul <I>list</I>}</TT></TD>
<TD VALIGN=top ALIGN=left>build a list.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| {ol <I>list</I>}</TT></TD>
<TD VALIGN=top ALIGN=left>build an enumerated list.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| {{:<I>string</I>}<I>text</I>}</TT></TD>
<TD VALIGN=top ALIGN=left>put a link to the given address
(given as a string) on the given text.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| [<I>string</I>]</TT></TD>
<TD VALIGN=top ALIGN=left>set the given <I>string</I> in source code style.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| {[<I>string</I>]}</TT></TD>
<TD VALIGN=top ALIGN=left>set the given <I>string</I> in preformatted
source code style.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| {v <I>string</I> v}</TT></TD>
<TD VALIGN=top ALIGN=left>set the given <I>string</I> in verbatim style.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| {% <I>string</I> %}</TT></TD>
<TD VALIGN=top ALIGN=left>take the given <I>string</I>
as raw L<sup>A</sup>T<sub>E</sub>X code.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| {!<I>string</I>}</TT></TD>
<TD VALIGN=top ALIGN=left>insert a reference to the element named
<I>string</I>. <I>string</I> must be a fully qualified element name,
for example <TT>Foo.Bar.t</TT>.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| {^ <I>text</I>}</TT></TD>
<TD VALIGN=top ALIGN=left>set text in superscript.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| {_ <I>text</I>}</TT></TD>
<TD VALIGN=top ALIGN=left>set text in subscript.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| <I>escaped_string</I></TT></TD>
<TD VALIGN=top ALIGN=left>typeset the given string as is;
special characters ('<TT>{</TT>', '<TT>}</TT>', '<TT>[</TT>', '<TT>]</TT>' and '<TT>@</TT>')
must be escaped by a '<TT>\</TT>'</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>| <I>blank_line</I> </TT></TD>
<TD VALIGN=top ALIGN=left>force a new line.</TD>
</TR></TABLE> <BR>
<I>list</I> ::= <BR>
<TT>| ({- <I>text</I>})+</TT><BR>
<TT>| ({li <I>text</I>})+</TT><BR>
A shortcut syntax exists for lists and enumerated lists:
<PRE>
(** Here is a {b list}
- item 1
- item 2
- item 3
The list is ended by the blank line.*)
</PRE>is equivalent to:
<PRE>
(** Here is a {b list}
{ul {- item 1}
{- item 2}
{- item 3}}
The list is ended by the blank line.*)
</PRE>
The same shortcut is available for enumerated lists, using '<TT>+</TT>'
instead of '<TT>-</TT>'.
Note that only one list can be defined by this shortcut in nested lists.<BR>
<BR>
In the description of a value, type, exception, module, module type, class
or class type, the <EM>first sentence</EM> is sometimes used in indexes, or
when just a part of the description is needed. The first sentence
is composed of the first characters of the description, until
<UL><LI>
the first dot followed by a blank, or
<LI>the first blank line
</UL>
outside of the following text formatting :
<TT>{ul <EM>list</EM>}</TT>,
<TT>{ol <EM>list</EM>}</TT>,
<TT>[<EM>string</EM>]</TT>,
<TT>{[<EM>string</EM>]}</TT>,
<TT>{v <EM>string</EM> v}</TT>,
<TT>{% <EM>string</EM>%}</TT>,
<TT>{!<EM>string</EM>}</TT>,
<TT>{^ <EM>text</EM>}</TT>,
<TT>{_ <EM>text</EM>}</TT>.<BR>
<BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#7fff7f"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc157"><B><FONT SIZE=4>15.2.5</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=4>Documentation tags (@-tags)</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
<A NAME="s:ocamldoc-tags"></A><BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98ff98"><DIV ALIGN=center><TABLE>
<TR><TD><B>Predefined tags</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
The folowing table gives the list of predefined @-tags, with their
syntax and meaning.<BR>
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1>
<TR><TD VALIGN=top ALIGN=left><TT>@author </TT><EM>string</EM></TD>
<TD VALIGN=top ALIGN=left>The author of the element. One author by <TT>@author</TT> tag.
There may be several <TT>@author</TT> tags for the same element.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>@deprecated </TT><EM>text</EM></TD>
<TD VALIGN=top ALIGN=left>The <EM>text</EM> should describe when the element was
deprecated, what to use as a replacement, and possibly the reason
for deprecation.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>@param </TT><EM>id text</EM></TD>
<TD VALIGN=top ALIGN=left>Associate the given description (<EM>text</EM>) to the
given parameter name <EM>id</EM>. This tag is used for functions,
methods, classes and functors.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>@raise Exc </TT><EM>text</EM></TD>
<TD VALIGN=top ALIGN=left>Explain that the element may raise
the exception <TT>Exc</TT>.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>@return </TT><EM>text</EM></TD>
<TD VALIGN=top ALIGN=left>Describe the return value and
its possible values. This tag is used for functions
and methods.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>@see <url> </TT><EM>text</EM></TD>
<TD VALIGN=top ALIGN=left>Add a reference to the URL between '<TT><</TT>' and '<TT>></TT>'
with the given text as comment.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>@see 'filename' </TT><EM>text</EM></TD>
<TD VALIGN=top ALIGN=left>Add a reference to the given file name
(written between single quotes), with the given text as comment.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>@see "document name" </TT><EM>text</EM></TD>
<TD VALIGN=top ALIGN=left>Add a reference to the given
document name (written between double quotes), with the given text
as comment.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>@since </TT><EM>string</EM></TD>
<TD VALIGN=top ALIGN=left>Indicates when the element was introduced.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>@version </TT><EM>string</EM></TD>
<TD VALIGN=top ALIGN=left>The version number for the element.</TD>
</TR></TABLE><BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98ff98"><DIV ALIGN=center><TABLE>
<TR><TD><B>Custom tags</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
<A NAME="s:ocamldoc-custom-tags"></A>
You can use custom tags in the documentation comments, but they will
have no effect if the generator used does not handle them. To use a
custom tag, for example <TT>foo</TT>, just put <TT>@foo</TT> with some text in your
comment, as in:
<PRE>
(** My comment to show you a custom tag.
@foo this is the text argument to the [foo] custom tag.
*)
</PRE>
To handle custom tags, you need to define a custom generator,
as explained in section <A HREF="#s:ocamldoc-handling-custom-tags">15.3.2</A>.<BR>
<BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#66ff66"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc158"><B><FONT SIZE=5>15.3</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=5>Custom generators</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
<A NAME="s:ocamldoc-custom-generators"></A><BR>
OCamldoc operates in two steps:
<OL type=1><LI>
analysis of the source files;
<LI>generation of documentation, through a documentation generator,
which is an object of class <TT>Odoc_args.class_generator</TT>.
</OL>
Users can provide their own documentation generator to be used during
step 2 instead of the default generators.
All the information retrieved during the analysis step is available through
the <TT>Odoc_info</TT> module, which gives access to all the types and functions
representing the elements found in the given modules, with their associated
description.<BR>
<BR>
The files you can used to define custom generators are installed in the
<TT>ocamldoc</TT> sub-directory of the OCaml standard library.<BR>
<BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#7fff7f"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc159"><B><FONT SIZE=4>15.3.1</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=4>The generator class</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
A generator class is a class of type <TT>Odoc_args.doc_generator</TT>.
It has only one method<BR>
<TT>generator : Odoc_info.Module.t_module list -> unit</TT><BR>
This method will be called with the list of analysed and possibly
merged <TT>Odoc_info.t_module</TT> structures.
Of course the class can have other methods, but the object of this
class must be coerced to <TT>Odoc_args.doc_generator</TT> before being
passed to the function<BR>
<TT>Odoc_args.set_doc_generator : Odoc_args.doc_generator -> unit</TT><BR>
which installs the new documentation generator.<BR>
<BR>
The following example shows how to define and install a new documentation generator.
See the <TT>odoc_fhtml</TT> generator (in the Ocamldoc Hump) for a complete example.
<PRE>
class my_doc_gen =
object
(* ... *)
method generate module_list =
(* ... *)
()
(* ... *)
end
let my_generator = new my_doc_gen
let _ = Odoc_args.set_doc_generator (my_generator :> Odoc_args.doc_generator)
</PRE>
Note: The new class can inherit from <TT>Odoc_html.html</TT>, <TT>Odoc_latex.latex</TT>,
<TT>Odoc_man.man</TT>, <TT>Odoc_texi.texi</TT> or <TT>Odoc_dot.dot</TT>, and
redefine only some methods to benefit from the existing methods. <BR>
<BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#7fff7f"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc160"><B><FONT SIZE=4>15.3.2</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=4>Handling custom tags</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
<A NAME="s:ocamldoc-handling-custom-tags"></A><BR>
Making a custom generator handle custom tags (see
<A HREF="#s:ocamldoc-custom-tags">15.2.5</A>) is very simple.<BR>
<BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98ff98"><DIV ALIGN=center><TABLE>
<TR><TD><B>For HTML</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
Here is how to develop a HTML generator handling your custom tags.<BR>
<BR>
The class <TT>Odoc_html.html</TT> inherits
from the class <TT>Odoc_html.info</TT>, containing a field <TT>tag_functions</TT> which is a
list pairs composed of a custom tag (e.g. 'foo') and a function taking a <TT>text</TT>
and returning HTML code (of type <TT>string</TT>).
To handle a new tag <TT>bar</TT>, create a HTML generator class from the existing one
and complete the <TT>tag_functions</TT> field:
<PRE>
class my_gen =
object(self)
inherit Odoc_html.html
(** Return HTML code for the given text of a bar tag. *)
method html_of_bar t = (* your code here *)
initializer
tag_functions <- ("bar", self#html_of_bar) :: tag_functions
end
</PRE>
Another method of the class <TT>Odoc_html.info</TT> will look for the
function associated to a custom tag and apply it to the text given to
the tag. If no function is associated to a custom tag, then the method
prints a warning message on <TT>stderr</TT>.<BR>
<BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98ff98"><DIV ALIGN=center><TABLE>
<TR><TD><B>For other generators</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
As for the HTML custom generator, you can define a new L<sup>A</sup>T<sub>E</sub>X(resp. <TT>man</TT>) generator by inheriting from the class
<TT>Odoc_latex.latex</TT> (resp. <TT>Odoc_man.man</TT>) and
adding your own tag handler to the field <TT>tag_functions</TT>.<BR>
<BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#66ff66"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc161"><B><FONT SIZE=5>15.4</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=5>Adding command line options</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
The command line analysis is performed after loading the module containing the
documentation generator, thus allowing command line options to be added to the
list of existing ones. Adding an option can be done with the function<BR>
<TT>Odoc_args.add_option : string * Arg.spec * string -> unit</TT><BR>
Note: Existing command line options can be redefined using this function.<BR>
<BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#7fff7f"><DIV ALIGN=center><TABLE>
<TR><TD><A NAME="htoc162"><B><FONT SIZE=4>15.4.1</FONT></B></A></TD>
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=4>Compilation and usage</FONT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
<A NAME="s:ocamldoc-compilation-and-usage"></A><BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98ff98"><DIV ALIGN=center><TABLE>
<TR><TD><B>Defining a custom generator class in one file</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
Let <TT>custom.ml</TT> be the file defining a new generator class.
Compilation of <TT>custom.ml</TT> can be performed by the following command :<BR>
<TT>ocamlc -I +ocamldoc -c custom.ml</TT><BR>
The file <TT>custom.cmo</TT> is created and can be used this way :<BR>
<TT>ocamldoc -g custom.cmo <EM>other_options</EM> <EM>source_files</EM></TT><BR>
It is important not to give the <B><TT>-html</TT></B> or any other option selecting a
built in generator to <TT>ocamldoc</TT>,
which would result in using this generator instead of the one you just loaded.<BR>
<BR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98ff98"><DIV ALIGN=center><TABLE>
<TR><TD><B>Defining a custom generator class in several files</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
It is possible to define a generator class in several modules, which
are defined in several files <TT>file1.ml[i]</TT>, <TT>file2.ml[i]</TT>, ...,
<TT>fileN.ml[i]</TT>. A <TT>.cma</TT> library file must
be created, including all these files.<BR>
The following commands create the <TT>custom.cma</TT> file from files <TT>file1.ml[i]</TT>, ...,
<TT>fileN.ml[i]</TT> :<BR>
<TT>ocamlc -I +ocamldoc -c file1.ml[i]<BR>
ocamlc -I +ocamldoc -c file2.ml[i]<BR>
...<BR>
ocamlc -I +ocamldoc -c fileN.ml[i]<BR>
ocamlc -o custom.cma -a file1.cmo file2.cmo ... fileN.cmo</TT><BR>
Then, the following command uses <TT>custom.cma</TT> as custom generator:<BR>
<TT>ocamldoc -g custom.cma <EM>other_options</EM> <EM>source_files</EM></TT><BR>
Again, it is important not to give the <B><TT>-html</TT></B> or any other option selecting a
built in generator to <TT>ocamldoc</TT>,
which would result in using this generator instead of the one you just loaded.<BR>
<BR>
<BR>
<BR>
<HR>
<A HREF="manual028.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<A HREF="manual030.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
