<!DOCTYPE html> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <meta name="generator" content="hevea 2.00"> <link rel="stylesheet" type="text/css" href="manual.css"> <title>The documentation generator (ocamldoc)</title> </head> <body> <a href="browser.html"><img src="previous_motif.gif" alt="Previous"></a> <a href="index.html"><img src="contents_motif.gif" alt="Up"></a> <a href="debugger.html"><img src="next_motif.gif" alt="Next"></a> <hr> <h1 class="chapter" id="sec296">Chapter 15  The documentation generator (ocamldoc)</h1> <ul> <li><a href="ocamldoc.html#sec297">Usage</a> </li><li><a href="ocamldoc.html#sec309">Syntax of documentation comments</a> </li><li><a href="ocamldoc.html#sec324">Custom generators</a> </li><li><a href="ocamldoc.html#sec329">Adding command line options</a> </li></ul> <p> <a id="c:ocamldoc"></a> </p><p>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 <span class="c007">(**</span>…<span class="c007">*)</span> and follow the format described in section <a href="#s%3Aocamldoc-comments">15.2</a>.</p><p>OCamldoc can produce documentation in various formats: HTML, L<sup>A</sup>T<sub>E</sub>X, TeXinfo, Unix man pages, and <span class="c007">dot</span> dependency graphs. Moreover, users can add their own custom generators, as explained in section <a href="#s%3Aocamldoc-custom-generators">15.3</a>.</p><p>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.</p> <h2 class="section" id="sec297">15.1  Usage</h2> <p> <a id="s:ocamldoc-usage"></a></p> <h3 class="subsection" id="sec298">15.1.1  Invocation</h3> <p>OCamldoc is invoked via the command <span class="c007">ocamldoc</span>, as follows: </p><pre> ocamldoc <span class="c013">options sourcefiles</span> </pre><h4 class="subsubsection" id="sec299">Options for choosing the output format</h4> <p>The following options determine the format for the generated documentation.</p><dl class="description"><dt class="dt-description"> <span class="c010">-html</span></dt><dd class="dd-description"> Generate documentation in HTML default format. The generated HTML pages are stored in the current directory, or in the directory specified with the <span class="c010">-d</span> option. You can customize the style of the generated pages by editing the generated <span class="c007">style.css</span> file, or by providing your own style sheet using option <span class="c007">-css-style</span>. The file <span class="c007">style.css</span> is not generated if it already exists or if -css-style is used.</dd><dt class="dt-description"><span class="c010">-latex</span></dt><dd class="dd-description"> 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 <span class="c007">ocamldoc.out</span>, or in the file specified with the <span class="c010">-o</span> option. The document uses the style file <span class="c007">ocamldoc.sty</span>. This file is generated when using the <span class="c007">-latex</span> option, if it does not already exist. You can change this file to customize the style of your L<sup>A</sup>T<sub>E</sub>X documentation.</dd><dt class="dt-description"><span class="c010">-texi</span></dt><dd class="dd-description"> Generate documentation in TeXinfo default format. The generated L<sup>A</sup>T<sub>E</sub>X document is saved in file <span class="c007">ocamldoc.out</span>, or in the file specified with the <span class="c010">-o</span> option.</dd><dt class="dt-description"><span class="c010">-man</span></dt><dd class="dd-description"> Generate documentation as a set of Unix <span class="c007">man</span> pages. The generated pages are stored in the current directory, or in the directory specified with the <span class="c010">-d</span> option.</dd><dt class="dt-description"><span class="c010">-dot</span></dt><dd class="dd-description"> Generate a dependency graph for the toplevel modules, in a format suitable for displaying and processing by <span class="c007">dot</span>. The <span class="c007">dot</span> tool is available from <a href="http://www.research.att.com/sw/tools/graphviz/"><span class="c007">http://www.research.att.com/sw/tools/graphviz/</span></a>. The textual representation of the graph is written to the file <span class="c007">ocamldoc.out</span>, or to the file specified with the <span class="c010">-o</span> option. Use <span class="c007">dot ocamldoc.out</span> to display it.</dd><dt class="dt-description"><span class="c019"><span class="c007">-g</span> <span class="c013">file.cm[o,a,xs]</span></span></dt><dd class="dd-description"> Dynamically load the given file, which defines a custom documentation generator. See section <a href="#s%3Aocamldoc-compilation-and-usage">15.4.1</a>. This option is supported by the <span class="c007">ocamldoc</span> command (to load <span class="c007">.cmo</span> and <span class="c007">.cma</span> files) and by its native-code version <span class="c007">ocamldoc.opt</span> (to load <span class="c007">.cmxs</span> files). 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 optional <span class="c007">-i</span> options.</dd><dt class="dt-description"><span class="c010">-customdir</span></dt><dd class="dd-description"> Display the custom generators default directory.</dd><dt class="dt-description"><span class="c019"><span class="c007">-i</span> <span class="c013">directory</span></span></dt><dd class="dd-description"> Add the given directory to the path where to look for custom generators.</dd></dl><h4 class="subsubsection" id="sec300">General options</h4> <dl class="description"><dt class="dt-description"><span class="c019"><span class="c007">-d</span> <span class="c013">dir</span></span></dt><dd class="dd-description"> Generate files in directory <span class="c013">dir</span>, rather than the current directory.</dd><dt class="dt-description"><span class="c019"><span class="c007">-dump</span> <span class="c013">file</span></span></dt><dd class="dd-description"> Dump collected information into <span class="c013">file</span>. This information can be read with the <span class="c007">-load</span> option in a subsequent invocation of <span class="c007">ocamldoc</span>.</dd><dt class="dt-description"><span class="c019"><span class="c007">-hide</span> <span class="c013">modules</span></span></dt><dd class="dd-description"> Hide the given complete module names in the generated documentation. <span class="c013">modules</span> is a list of complete module names separated by ’<span class="c007">,</span>’, without blanks. For instance: <span class="c007">Pervasives,M2.M3</span>.</dd><dt class="dt-description"><span class="c010">-inv-merge-ml-mli</span></dt><dd class="dd-description"> Reverse the precedence of implementations and interfaces when merging. All elements in implementation files are kept, and the <span class="c010">-m</span> option indicates which parts of the comments in interface files are merged with the comments in implementation files.</dd><dt class="dt-description"><span class="c010">-keep-code</span></dt><dd class="dd-description"> Always keep the source code for values, methods and instance variables, when available. The source code is always kept when a <span class="c007">.ml</span> file is given, but is by default discarded when a <span class="c007">.mli</span> is given. This option keeps the source code in all cases.</dd><dt class="dt-description"><span class="c019"><span class="c007">-load</span> <span class="c013">file</span></span></dt><dd class="dd-description"> Load information from <span class="c013">file</span>, which has been produced by <span class="c007">ocamldoc -dump</span>. Several <span class="c007">-load</span> options can be given.</dd><dt class="dt-description"><span class="c019"><span class="c007">-m</span> <span class="c013">flags</span></span></dt><dd class="dd-description"> Specify merge options between interfaces and implementations. (see section <a href="#s%3Aocamldoc-merge">15.1.2</a> for details). <span class="c013">flags</span> can be one or several of the following characters: <dl class="description"><dt class="dt-description"> <span class="c010">d</span></dt><dd class="dd-description"> merge description </dd><dt class="dt-description"><span class="c010">a</span></dt><dd class="dd-description"> merge <span class="c007">@author</span> </dd><dt class="dt-description"><span class="c010">v</span></dt><dd class="dd-description"> merge <span class="c007">@version</span> </dd><dt class="dt-description"><span class="c010">l</span></dt><dd class="dd-description"> merge <span class="c007">@see</span> </dd><dt class="dt-description"><span class="c010">s</span></dt><dd class="dd-description"> merge <span class="c007">@since</span> </dd><dt class="dt-description"><span class="c010">b</span></dt><dd class="dd-description"> merge <span class="c007">@before</span> </dd><dt class="dt-description"><span class="c010">o</span></dt><dd class="dd-description"> merge <span class="c007">@deprecated</span> </dd><dt class="dt-description"><span class="c010">p</span></dt><dd class="dd-description"> merge <span class="c007">@param</span> </dd><dt class="dt-description"><span class="c010">e</span></dt><dd class="dd-description"> merge <span class="c007">@raise</span> </dd><dt class="dt-description"><span class="c010">r</span></dt><dd class="dd-description"> merge <span class="c007">@return</span> </dd><dt class="dt-description"><span class="c010">A</span></dt><dd class="dd-description"> merge everything </dd></dl></dd><dt class="dt-description"><span class="c010">-no-custom-tags</span></dt><dd class="dd-description"> Do not allow custom @-tags (see section <a href="#s%3Aocamldoc-tags">15.2.5</a>).</dd><dt class="dt-description"><span class="c010">-no-stop</span></dt><dd class="dd-description"> Keep elements placed after/between the <span class="c007">(**/**)</span> special comment(s) (see section <a href="#s%3Aocamldoc-comments">15.2</a>).</dd><dt class="dt-description"><span class="c019"><span class="c007">-o</span> <span class="c013">file</span></span></dt><dd class="dd-description"> Output the generated documentation to <span class="c013">file</span> instead of <span class="c007">ocamldoc.out</span>. This option is meaningful only in conjunction with the <span class="c010">-latex</span>, <span class="c010">-texi</span>, or <span class="c010">-dot</span> options.</dd><dt class="dt-description"><span class="c019"><span class="c007">-pp</span> <span class="c013">command</span></span></dt><dd class="dd-description"> Pipe sources through preprocessor <span class="c013">command</span>.</dd><dt class="dt-description"><span class="c019"><span class="c007">-impl</span> <span class="c013">filename</span></span></dt><dd class="dd-description"> Process the file <span class="c013">filename</span> as an implementation file, even if its extension is not <span class="c007">.ml</span>.</dd><dt class="dt-description"><span class="c019"><span class="c007">-intf</span> <span class="c013">filename</span></span></dt><dd class="dd-description"> Process the file <span class="c013">filename</span> as an interface file, even if its extension is not <span class="c007">.mli</span>.</dd><dt class="dt-description"><span class="c019"><span class="c007">-text</span> <span class="c013">filename</span></span></dt><dd class="dd-description"> Process the file <span class="c013">filename</span> as a text file, even if its extension is not <span class="c007">.txt</span>.</dd><dt class="dt-description"><span class="c010">-sort</span></dt><dd class="dd-description"> Sort the list of top-level modules before generating the documentation.</dd><dt class="dt-description"><span class="c010">-stars</span></dt><dd class="dd-description"> Remove blank characters until the first asterisk (’<span class="c007">*</span>’) in each line of comments.</dd><dt class="dt-description"><span class="c019"><span class="c007">-t</span> <span class="c013">title</span></span></dt><dd class="dd-description"> Use <span class="c013">title</span> as the title for the generated documentation.</dd><dt class="dt-description"><span class="c019"><span class="c007">-intro</span> <span class="c013">file</span></span></dt><dd class="dd-description"> Use content of <span class="c013">file</span> as ocamldoc text to use as introduction (HTML, L<sup>A</sup>T<sub>E</sub>X and TeXinfo only). For HTML, the file is used to create the whole <span class="c007">index.html</span> file.</dd><dt class="dt-description"><span class="c010">-v</span></dt><dd class="dd-description"> Verbose mode. Display progress information.</dd><dt class="dt-description"><span class="c010">-version</span></dt><dd class="dd-description"> Print version string and exit.</dd><dt class="dt-description"><span class="c010">-vnum</span></dt><dd class="dd-description"> Print short version number and exit.</dd><dt class="dt-description"><span class="c010">-warn-error</span></dt><dd class="dd-description"> Treat Ocamldoc warnings as errors.</dd><dt class="dt-description"><span class="c010">-hide-warnings</span></dt><dd class="dd-description"> Do not print OCamldoc warnings.</dd><dt class="dt-description"><span class="c019"><span class="c007">-help</span> or <span class="c007">--help</span></span></dt><dd class="dd-description"> Display a short usage summary and exit. </dd></dl><h4 class="subsubsection" id="sec301">Type-checking options</h4> <p>OCamldoc 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 <span class="c007">ocamlc</span> and <span class="c007">ocamlopt</span> commands.</p><dl class="description"><dt class="dt-description"><span class="c019"><span class="c007">-I</span> <span class="c013">directory</span></span></dt><dd class="dd-description"> Add <span class="c013">directory</span> to the list of directories search for compiled interface files (<span class="c007">.cmi</span> files).</dd><dt class="dt-description"><span class="c010">-nolabels</span></dt><dd class="dd-description"> Ignore non-optional labels in types.</dd><dt class="dt-description"><span class="c010">-rectypes</span></dt><dd class="dd-description"> Allow arbitrary recursive types. (See the <span class="c007">-rectypes</span> option to <span class="c007">ocamlc</span>.)</dd></dl><h4 class="subsubsection" id="sec302">Options for generating HTML pages</h4> <p>The following options apply in conjunction with the <span class="c007">-html</span> option:</p><dl class="description"><dt class="dt-description"> <span class="c010">-all-params</span></dt><dd class="dd-description"> Display the complete list of parameters for functions and methods.</dd><dt class="dt-description"><span class="c019"><span class="c007">-charset</span> <span class="c013">charset</span></span></dt><dd class="dd-description"> Add information about character encoding being <span class="c013">charset</span> (default is iso-8859-1).</dd><dt class="dt-description"><span class="c010">-colorize-code</span></dt><dd class="dd-description"> Colorize the OCaml code enclosed in <span class="c007">[ ]</span> and <span class="c007">{[ ]}</span>, using colors to emphasize keywords, etc. If the code fragments are not syntactically correct, no color is added.</dd><dt class="dt-description"><span class="c019"><span class="c007">-css-style</span> <span class="c013">filename</span></span></dt><dd class="dd-description"> Use <span class="c013">filename</span> as the Cascading Style Sheet file.</dd><dt class="dt-description"><span class="c010">-index-only</span></dt><dd class="dd-description"> Generate only index files.</dd><dt class="dt-description"><span class="c010">-short-functors</span></dt><dd class="dd-description"> Use a short form to display functors: <pre> module M : functor (A:Module) -> functor (B:Module2) -> sig .. end </pre> is displayed as: <pre> module M (A:Module) (B:Module2) : sig .. end </pre></dd></dl><h4 class="subsubsection" id="sec303">Options for generating L<sup>A</sup>T<sub>E</sub>X files</h4> <p>The following options apply in conjunction with the <span class="c007">-latex</span> option:</p><dl class="description"><dt class="dt-description"> <span class="c019"><span class="c007">-latex-value-prefix</span> <span class="c013">prefix</span></span></dt><dd class="dd-description"> 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 <span class="c007">-latex-type-prefix</span>, <span class="c007">-latex-exception-prefix</span>, <span class="c007">-latex-module-prefix</span>, <span class="c007">-latex-module-type-prefix</span>, <span class="c007">-latex-class-prefix</span>, <span class="c007">-latex-class-type-prefix</span>, <span class="c007">-latex-attribute-prefix</span> and <span class="c007">-latex-method-prefix</span>.<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, L<sup>A</sup>T<sub>E</sub>X will complain about multiply defined labels.</p></dd><dt class="dt-description"><span class="c019"><span class="c007">-latextitle</span> <span class="c013">n,style</span></span></dt><dd class="dd-description"> Associate style number <span class="c013">n</span> to the given L<sup>A</sup>T<sub>E</sub>X sectioning command <span class="c013">style</span>, e.g. <span class="c007">section</span> or <span class="c007">subsection</span>. (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 <span class="c007">section</span>, 2 for <span class="c007">subsection</span>, 3 for <span class="c007">subsubsection</span>, 4 for <span class="c007">paragraph</span> and 5 for <span class="c007">subparagraph</span>.</dd><dt class="dt-description"><span class="c010">-noheader</span></dt><dd class="dd-description"> Suppress header in generated documentation.</dd><dt class="dt-description"><span class="c010">-notoc</span></dt><dd class="dd-description"> Do not generate a table of contents.</dd><dt class="dt-description"><span class="c010">-notrailer</span></dt><dd class="dd-description"> Suppress trailer in generated documentation.</dd><dt class="dt-description"><span class="c010">-sepfiles</span></dt><dd class="dd-description"> Generate one <span class="c007">.tex</span> file per toplevel module, instead of the global <span class="c007">ocamldoc.out</span> file. </dd></dl><h4 class="subsubsection" id="sec304">Options for generating TeXinfo files</h4> <p>The following options apply in conjunction with the <span class="c007">-texi</span> option:</p><dl class="description"><dt class="dt-description"> <span class="c010">-esc8</span></dt><dd class="dd-description"> Escape accented characters in Info files.</dd><dt class="dt-description"><span class="c010">-info-entry</span></dt><dd class="dd-description"> Specify Info directory entry.</dd><dt class="dt-description"><span class="c010">-info-section</span></dt><dd class="dd-description"> Specify section of Info directory.</dd><dt class="dt-description"><span class="c010">-noheader</span></dt><dd class="dd-description"> Suppress header in generated documentation.</dd><dt class="dt-description"><span class="c010">-noindex</span></dt><dd class="dd-description"> Do not build index for Info files.</dd><dt class="dt-description"><span class="c010">-notrailer</span></dt><dd class="dd-description"> Suppress trailer in generated documentation. </dd></dl><h4 class="subsubsection" id="sec305">Options for generating <span class="c007">dot</span> graphs</h4> <p>The following options apply in conjunction with the <span class="c007">-dot</span> option:</p><dl class="description"><dt class="dt-description"> <span class="c019"><span class="c007">-dot-colors</span> <span class="c013">colors</span></span></dt><dd class="dd-description"> Specify the colors to use in the generated <span class="c007">dot</span> code. When generating module dependencies, <span class="c007">ocamldoc</span> uses different colors for modules, depending on the directories in which they reside. When generating types dependencies, <span class="c007">ocamldoc</span> uses different colors for types, depending on the modules in which they are defined. <span class="c013">colors</span> is a list of color names separated by ’<span class="c007">,</span>’, as in <span class="c007">Red,Blue,Green</span>. The available colors are the ones supported by the <span class="c007">dot</span> tool.</dd><dt class="dt-description"><span class="c010">-dot-include-all</span></dt><dd class="dd-description"> Include all modules in the <span class="c007">dot</span> output, not only modules given on the command line or loaded with the <span class="c010">-load</span> option.</dd><dt class="dt-description"><span class="c010">-dot-reduce</span></dt><dd class="dd-description"> Perform a transitive reduction of the dependency graph before outputting the <span class="c007">dot</span> code. This can be useful if there are a lot of transitive dependencies that clutter the graph.</dd><dt class="dt-description"><span class="c010">-dot-types</span></dt><dd class="dd-description"> Output <span class="c007">dot</span> code describing the type dependency graph instead of the module dependency graph. </dd></dl><h4 class="subsubsection" id="sec306">Options for generating man files</h4> <p>The following options apply in conjunction with the <span class="c007">-man</span> option:</p><dl class="description"><dt class="dt-description"> <span class="c010">-man-mini</span></dt><dd class="dd-description"> Generate man pages only for modules, module types, clases and class types, instead of pages for all elements.</dd><dt class="dt-description"><span class="c019"><span class="c007">-man-suffix</span> <span class="c013">suffix</span></span></dt><dd class="dd-description"> Set the suffix used for generated man filenames. Default is ’<span class="c007">3o</span>’, as in <span class="c007">List.3o</span>.</dd><dt class="dt-description"><span class="c019"><span class="c007">-man-section</span> <span class="c013">section</span></span></dt><dd class="dd-description"> Set the section number used for generated man filenames. Default is ’<span class="c007">3</span>’.</dd></dl> <h3 class="subsection" id="sec307">15.1.2  Merging of module information</h3> <p> <a id="s:ocamldoc-merge"></a></p><p>Information on a module can be extracted either from the <span class="c007">.mli</span> or <span class="c007">.ml</span> file, or both, depending on the files given on the command line. When both <span class="c007">.mli</span> and <span class="c007">.ml</span> files are given for the same module, information extracted from these files is merged according to the following rules: </p><ul class="itemize"><li class="li-itemize"> Only elements (values, types, classes, ...) declared in the <span class="c007">.mli</span> file are kept. In other terms, definitions from the <span class="c007">.ml</span> file that are not exported in the <span class="c007">.mli</span> file are not documented. </li><li class="li-itemize">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 <span class="c007">.ml</span> file is concatenated to the one in the <span class="c007">.mli</span> file, if the corresponding <span class="c007">-m</span> flag is given on the command line. If a description is present in the <span class="c007">.ml</span> file and not in the <span class="c007">.mli</span> file, the <span class="c007">.ml</span> description is kept. In either case, all the information given in the <span class="c007">.mli</span> file is kept. </li></ul> <h3 class="subsection" id="sec308">15.1.3  Coding rules</h3> <p> <a id="s:ocamldoc-rules"></a> The following rules must be respected in order to avoid name clashes resulting in cross-reference errors: </p><ul class="itemize"><li class="li-itemize"> In a module, there must not be two modules, two module types or a module and a module type with the same name. In the default HTML generator, modules <span class="c007">ab</span> and <span class="c007">AB</span> will be printed to the same file on case insensitive file systems. </li><li class="li-itemize">In a module, there must not be two classes, two class types or a class and a class type with the same name. </li><li class="li-itemize">In a module, there must not be two values, two types, or two exceptions with the same name. </li><li class="li-itemize">Values defined in tuple, as in <span class="c007">let (x,y,z) = (1,2,3)</span> are not kept by OCamldoc. </li><li class="li-itemize">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 <span class="c007">Bar.x</span> to the <span class="c007">x</span> of module <span class="c007">Foo</span> defined just above, instead of to the <span class="c007">Bar.x</span> defined in the opened module <span class="c007">Foo</span>. </li></ul> <h2 class="section" id="sec309">15.2  Syntax of documentation comments</h2> <p> <a id="s:ocamldoc-comments"></a></p><p>Comments containing documentation material are called <em>special comments</em> and are written between <span class="c007">(**</span> and <span class="c007">*)</span>. Special comments must start exactly with <span class="c007">(**</span>. Comments beginning with <span class="c007">(</span> and more than two <span class="c007">*</span> are ignored.</p> <h3 class="subsection" id="sec310">15.2.1  Placement of documentation comments</h3> <p> 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 <span class="c007">.mli</span> and <span class="c007">.ml</span> files are different.</p> <h4 class="subsubsection" id="sec311">Comments in <span class="c007">.mli</span> files</h4> <p> 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 : </p><ul class="itemize"><li class="li-itemize"> 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><li class="li-itemize">The special comment is not already associated to the previous element. </li><li class="li-itemize">The special comment is not the first one of a toplevel module. </li></ul><p>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.</p><p>There are two exceptions: for 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. The special comment for a constructor with another constructor following must be placed before the ’<span class="c007">|</span>’ character separating the two constructors.</p><p>The following sample interface file <span class="c007">foo.mli</span> illustrates the placement rules for comments in <span class="c007">.mli</span> files.</p><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> <h4 class="subsubsection" id="sec312">Comments in <span class="c007">.ml</span> files</h4> <p>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 constructors and record fields in type definitions, whose associated comment must be placed after the constructor or field definition, without blank line between them. The special comment for a constructor with another constructor following must be placed before the ’<span class="c007">|</span>’ character separating the two constructors.</p><p>The following example of file <span class="c007">toto.ml</span> shows where to place comments in a <span class="c007">.ml</span> file.</p><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> <h3 class="subsection" id="sec313">15.2.2  The Stop special comment</h3> <p> The special comment <span class="c007">(**/**)</span> tells OCamldoc to discard elements placed after this comment, up to the end of the current class, class type, module or module type, or up to the next stop comment. For instance: </p><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 appears since in the documentation since the previous stop comment toggled off the "no documentation mode". *) type t = string </pre><p> The <span class="c010">-no-stop</span> option to <span class="c007">ocamldoc</span> causes the Stop special comments to be ignored.</p> <h3 class="subsection" id="sec314">15.2.3  Syntax of documentation comments</h3> <p>The inside of documentation comments <span class="c007">(**</span>…<span class="c007">*)</span> 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 <span class="c007">@</span> character. Thus, a documentation comment has the following shape: </p><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><p>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 <span class="c007">@param</span> tag on a class instance variable is ignored.</p><p>At last, <span class="c007">(**)</span> is the empty documentation comment.</p> <h3 class="subsection" id="sec315">15.2.4  Text formatting</h3> <p>Here is the BNF grammar for the simple markup language used to format text descriptions.</p><table class="display dcenter"><tr class="c026"><td class="dcell"><table class="c002 cellpading0"><tr><td class="c025"> <a class="syntax" id="text"><span class="c014">text</span></a></td><td class="c022">::=</td><td class="c024"> {<a class="syntax" href="#text-element"><span class="c014">text-element</span></a>}<sup>+</sup>  </td></tr> <tr><td class="c025"> </td></tr> </table></td></tr> </table><table class="c002 cellpading0"><tr><td class="c025"> <a class="syntax" id="text-element"><span class="c014">text-element</span></a></td><td class="c022">::=</td></tr> </table><table class="c002 cellpading0"><tr><td class="c031">∣ </td><td class="c030"> <span class="c008">{</span> { <span class="c008">0</span> … <span class="c008">9</span> }<sup>+</sup> <a class="syntax" href="#text"><span class="c014">text</span></a> <span class="c008">}</span> </td><td class="c027">format <a class="syntax" href="#text"><span class="c014">text</span></a> as a section header; the integer following <span class="c007">{</span> indicates the sectioning level. </td></tr> <tr><td class="c031">∣ </td><td class="c030"> <span class="c008">{</span> { <span class="c008">0</span> … <span class="c008">9</span> }<sup>+</sup> <span class="c008">:</span> <span class="c014">label</span> <a class="syntax" href="#text"><span class="c014">text</span></a> <span class="c008">}</span> </td><td class="c027"> same, but also associate the name <span class="c014">label</span> to the current point. This point can be referenced by its fully-qualified label in a <span class="c007">{!</span> command, just like any other element. </td></tr> <tr><td class="c031">∣ </td><td class="c030"> <span class="c008">{b</span> <a class="syntax" href="#text"><span class="c014">text</span></a> <span class="c008">}</span> </td><td class="c027">set <a class="syntax" href="#text"><span class="c014">text</span></a> in bold. </td></tr> <tr><td class="c031">∣ </td><td class="c030"> <span class="c008">{i</span> <a class="syntax" href="#text"><span class="c014">text</span></a> <span class="c008">}</span> </td><td class="c027">set <a class="syntax" href="#text"><span class="c014">text</span></a> in italic. </td></tr> <tr><td class="c031">∣ </td><td class="c030"> <span class="c008">{e</span> <a class="syntax" href="#text"><span class="c014">text</span></a> <span class="c008">}</span> </td><td class="c027">emphasize <a class="syntax" href="#text"><span class="c014">text</span></a>. </td></tr> <tr><td class="c031">∣ </td><td class="c030"> <span class="c008">{C</span> <a class="syntax" href="#text"><span class="c014">text</span></a> <span class="c008">}</span> </td><td class="c027">center <a class="syntax" href="#text"><span class="c014">text</span></a>. </td></tr> <tr><td class="c031">∣ </td><td class="c030"> <span class="c008">{L</span> <a class="syntax" href="#text"><span class="c014">text</span></a> <span class="c008">}</span> </td><td class="c027">left align <a class="syntax" href="#text"><span class="c014">text</span></a>. </td></tr> <tr><td class="c031">∣ </td><td class="c030"> <span class="c008">{R</span> <a class="syntax" href="#text"><span class="c014">text</span></a> <span class="c008">}</span> </td><td class="c027">right align <a class="syntax" href="#text"><span class="c014">text</span></a>. </td></tr> <tr><td class="c031">∣ </td><td class="c030"> <span class="c008">{ul</span> <a class="syntax" href="#list"><span class="c014">list</span></a> <span class="c008">}</span> </td><td class="c027">build a list. </td></tr> <tr><td class="c031">∣ </td><td class="c030"> <span class="c008">{ol</span> <a class="syntax" href="#list"><span class="c014">list</span></a> <span class="c008">}</span> </td><td class="c027">build an enumerated list. </td></tr> <tr><td class="c031">∣ </td><td class="c030"> <span class="c005"><span class="c007">{{:</span> <span class="c014">string</span> <span class="c007">}</span></span>  <a class="syntax" href="#text"><span class="c014">text</span></a> <span class="c008">}</span> </td><td class="c027">put a link to the given address (given as <span class="c014">string</span>) on the given <a class="syntax" href="#text"><span class="c014">text</span></a>. </td></tr> <tr><td class="c031">∣ </td><td class="c030"> <span class="c005"><span class="c007">[</span> <span class="c014">string</span> <span class="c007">]</span></span> </td><td class="c027">set the given <span class="c014">string</span> in source code style. </td></tr> <tr><td class="c031">∣ </td><td class="c030"> <span class="c005"><span class="c007">{[</span> <span class="c014">string</span> <span class="c007">]}</span></span> </td><td class="c027">set the given <span class="c014">string</span> in preformatted source code style.</td></tr> <tr><td class="c031">∣ </td><td class="c030"> <span class="c005"><span class="c007">{v</span> <span class="c014">string</span> <span class="c007">v}</span></span> </td><td class="c027">set the given <span class="c014">string</span> in verbatim style. </td></tr> <tr><td class="c031">∣ </td><td class="c030"> <span class="c005"><span class="c007">{%</span> <span class="c014">string</span> <span class="c007">%}</span></span> </td><td class="c027">target-specific content (L<sup>A</sup>T<sub>E</sub>X code by default, see details in <a href="#sec319">15.2.4</a>) </td></tr> <tr><td class="c031">∣ </td><td class="c030"> <span class="c005"><span class="c007">{!</span> <span class="c014">string</span> <span class="c007">}</span></span> </td><td class="c027">insert a cross-reference to an element (see below <a href="#sec317">15.2.4</a> for the syntax of cross-references).</td></tr> <tr><td class="c031">∣ </td><td class="c030"> <span class="c008">{!modules:</span> <span class="c014">string</span>  <span class="c014">string</span> ... <span class="c008">}</span> </td><td class="c027">insert an index table for the given module names. Used in HTML only.</td></tr> <tr><td class="c031">∣ </td><td class="c030"> <span class="c008">{!indexlist}</span> </td><td class="c027">insert a table of links to the various indexes (types, values, modules, ...). Used in HTML only.</td></tr> <tr><td class="c031">∣ </td><td class="c030"> <span class="c008">{^</span> <a class="syntax" href="#text"><span class="c014">text</span></a> <span class="c008">}</span> </td><td class="c027">set text in superscript.</td></tr> <tr><td class="c031">∣ </td><td class="c030"> <span class="c008">{_</span> <a class="syntax" href="#text"><span class="c014">text</span></a> <span class="c008">}</span> </td><td class="c027">set text in subscript.</td></tr> <tr><td class="c031">∣ </td><td class="c030"><span class="c014">escaped-string</span></td><td class="c027">typeset the given string as is; special characters (’<span class="c007">{</span>’, ’<span class="c007">}</span>’, ’<span class="c007">[</span>’, ’<span class="c007">]</span>’ and ’<span class="c007">@</span>’) must be escaped by a ’<span class="c007">\</span>’</td></tr> <tr><td class="c031">∣ </td><td class="c030"><span class="c014">blank-line</span></td><td class="c027">force a new line. </td></tr> </table><p> <br> </p><h4 class="subsubsection" id="sec316">List formatting</h4> <table class="display dcenter"><tr class="c026"><td class="dcell"><table class="c002 cellpading0"><tr><td class="c025"> <a class="syntax" id="list"><span class="c014">list</span></a></td><td class="c022">::=</td><td class="c024">  </td></tr> <tr><td class="c025"> </td><td class="c022">∣</td><td class="c024"> { <span class="c008">{-</span> <a class="syntax" href="#text"><span class="c014">text</span></a> <span class="c008">}</span> }<sup>+</sup>  </td></tr> <tr><td class="c025"> </td><td class="c022">∣</td><td class="c024"> { <span class="c008">{li</span> <a class="syntax" href="#text"><span class="c014">text</span></a> <span class="c008">}</span> }<sup>+</sup> </td></tr> </table></td></tr> </table><p>A shortcut syntax exists for lists and enumerated lists: </p><pre>(** Here is a {b list} - item 1 - item 2 - item 3 The list is ended by the blank line.*) </pre><p>is equivalent to: </p><pre>(** Here is a {b list} {ul {- item 1} {- item 2} {- item 3}} The list is ended by the blank line.*) </pre><p> The same shortcut is available for enumerated lists, using ’<span class="c007">+</span>’ instead of ’<span class="c007">-</span>’. Note that only one list can be defined by this shortcut in nested lists.</p><h4 class="subsubsection" id="sec317">Cross-reference formatting</h4> <p>Cross-references are fully qualified element names, as in the example <span class="c007">{!Foo.Bar.t}</span>. This is an ambiguous reference as it may designate a type name, a value name, a class name, etc. It is possible to make explicit the intended syntactic class, using <span class="c007">{!type:Foo.Bar.t}</span> to designate a type, and <span class="c007">{!val:Foo.Bar.t}</span> a value of the same name.</p><p>The list of possible syntactic class is as follows: </p><ul class="itemize"><li class="li-itemize"> <span class="c007">module:</span> module </li><li class="li-itemize"><span class="c007">modtype:</span> module type </li><li class="li-itemize"><span class="c007">class:</span> class </li><li class="li-itemize"><span class="c007">classtype:</span> class type </li><li class="li-itemize"><span class="c007">val:</span> value </li><li class="li-itemize"><span class="c007">type:</span> type </li><li class="li-itemize"><span class="c007">exception:</span> exception </li><li class="li-itemize"><span class="c007">attribute:</span> attribute </li><li class="li-itemize"><span class="c007">method:</span> class method </li><li class="li-itemize"><span class="c007">section:</span> ocamldoc section </li><li class="li-itemize"><span class="c007">const:</span> variant constructor </li><li class="li-itemize"><span class="c007">recfield:</span> record field </li></ul><p>In the case of variant constructors or record field, the constructor or field name should be preceded by the name of the correspond type – to avoid the ambiguity of several types having the same constructor names. For example, the constructor <span class="c007">Node</span> of the type <span class="c007">tree</span> will be referenced as <span class="c007">{!tree.Node}</span> or <span class="c007">{!const:tree.Node}</span>, or possibly <span class="c007">{!Mod1.Mod2.tree.Node}</span> from outside the module.</p><h4 class="subsubsection" id="sec318">First sentence</h4> <p>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 </p><ul class="itemize"><li class="li-itemize"> the first dot followed by a blank, or </li><li class="li-itemize">the first blank line </li></ul><p> outside of the following text formatting : <span class="c008">{ul</span> <a class="syntax" href="#list"><span class="c014">list</span></a> <span class="c008">}</span> , <span class="c008">{ol</span> <a class="syntax" href="#list"><span class="c014">list</span></a> <span class="c008">}</span> , <span class="c005"><span class="c007">[</span> <span class="c014">string</span> <span class="c007">]</span></span> , <span class="c005"><span class="c007">{[</span> <span class="c014">string</span> <span class="c007">]}</span></span> , <span class="c005"><span class="c007">{v</span> <span class="c014">string</span> <span class="c007">v}</span></span> , <span class="c005"><span class="c007">{%</span> <span class="c014">string</span> <span class="c007">%}</span></span> , <span class="c005"><span class="c007">{!</span> <span class="c014">string</span> <span class="c007">}</span></span> , <span class="c008">{^</span> <a class="syntax" href="#text"><span class="c014">text</span></a> <span class="c008">}</span> , <span class="c008">{_</span> <a class="syntax" href="#text"><span class="c014">text</span></a> <span class="c008">}</span> .</p><h4 class="subsubsection" id="sec319">Target-specific formatting</h4> <p>The content inside <span class="c007">{%foo: ... %}</span> is target-specific and will only be interpreted by the backend <span class="c007">foo</span>, and ignored by the others. The backends of the distribution are <span class="c007">latex</span>, <span class="c007">html</span>, <span class="c007">texi</span> and <span class="c007">man</span>. If no target is specified (syntax <span class="c007">{% ... %}</span>), <span class="c007">latex</span> is chosen by default. Custom generators may support their own target prefix.</p><h4 class="subsubsection" id="sec320">Recognized HTML tags</h4> <p> The HTML tags <span class="c007"><b>..</b></span>, <span class="c007"><code>..</code></span>, <span class="c007"><i>..</i></span>, <span class="c007"><ul>..</ul></span>, <span class="c007"><ol>..</ol></span>, <span class="c007"><li>..</li></span>, <span class="c007"><center>..</center></span> and <span class="c007"><h[0-9]>..</h[0-9]></span> can be used instead of, respectively, <span class="c008">{b ..}</span> , <span class="c008">[..]</span> , <span class="c008">{i ..}</span> , <span class="c008">{ul ..}</span> , <span class="c008">{ol ..}</span> , <span class="c008">{li ..}</span> , <span class="c008">{C ..}</span> and <span class="c007">{[0-9] ..}</span>.</p> <h3 class="subsection" id="sec321">15.2.5  Documentation tags (@-tags)</h3> <p> <a id="s:ocamldoc-tags"></a></p> <h4 class="subsubsection" id="sec322">Predefined tags</h4> <p> The following table gives the list of predefined @-tags, with their syntax and meaning.<br> </p><table class="c000 cellpadding1" border=1><tr><td class="c028"> <span class="c008">@author</span> <span class="c014">string</span> </td><td class="c028">The author of the element. One author per <span class="c007">@author</span> tag. There may be several <span class="c007">@author</span> tags for the same element. </td></tr> <tr><td class="c028"> <span class="c008">@deprecated</span> <a class="syntax" href="#text"><span class="c014">text</span></a> </td><td class="c028">The <a class="syntax" href="#text"><span class="c014">text</span></a> should describe when the element was deprecated, what to use as a replacement, and possibly the reason for deprecation. </td></tr> <tr><td class="c028"> <span class="c008">@param</span> <span class="c014">id</span>  <a class="syntax" href="#text"><span class="c014">text</span></a> </td><td class="c028">Associate the given description (<a class="syntax" href="#text"><span class="c014">text</span></a>) to the given parameter name <span class="c014">id</span>. This tag is used for functions, methods, classes and functors. </td></tr> <tr><td class="c028"> <span class="c008">@raise</span> <span class="c014">Exc</span>  <a class="syntax" href="#text"><span class="c014">text</span></a> </td><td class="c028">Explain that the element may raise the exception <span class="c014">Exc</span>. </td></tr> <tr><td class="c028"> <span class="c008">@return</span> <a class="syntax" href="#text"><span class="c014">text</span></a> </td><td class="c028">Describe the return value and its possible values. This tag is used for functions and methods. </td></tr> <tr><td class="c028"> <span class="c005"><span class="c007">@see</span> <span class="c007"><</span> <span class="c014">URL</span> <span class="c007">></span></span>  <a class="syntax" href="#text"><span class="c014">text</span></a> </td><td class="c028">Add a reference to the <span class="c014">URL</span> with the given <a class="syntax" href="#text"><span class="c014">text</span></a> as comment. </td></tr> <tr><td class="c028"> <span class="c005"><span class="c007">@see</span> <span class="c007">'</span><span class="c014">filename</span><span class="c007">'</span></span> <a class="syntax" href="#text"><span class="c014">text</span></a> </td><td class="c028">Add a reference to the given file name (written between single quotes), with the given <a class="syntax" href="#text"><span class="c014">text</span></a> as comment. </td></tr> <tr><td class="c028"> <span class="c005"><span class="c007">@see</span> <span class="c007">"</span><span class="c014">document-name</span><span class="c007">"</span></span> <a class="syntax" href="#text"><span class="c014">text</span></a> </td><td class="c028">Add a reference to the given document name (written between double quotes), with the given <a class="syntax" href="#text"><span class="c014">text</span></a> as comment. </td></tr> <tr><td class="c028"> <span class="c008">@since</span> <span class="c014">string</span> </td><td class="c028">Indicate when the element was introduced. </td></tr> <tr><td class="c028"> <span class="c008">@before</span> <span class="c014">version</span> <a class="syntax" href="#text"><span class="c014">text</span></a> </td><td class="c028">Associate the given description (<a class="syntax" href="#text"><span class="c014">text</span></a>) to the given <span class="c014">version</span> in order to document compatibility issues. </td></tr> <tr><td class="c028"> <span class="c008">@version</span> <span class="c014">string</span> </td><td class="c028">The version number for the element. </td></tr> </table> <h4 class="subsubsection" id="sec323">Custom tags</h4> <p> <a id="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 <span class="c007">foo</span>, just put <span class="c007">@foo</span> with some text in your comment, as in: </p><pre>(** My comment to show you a custom tag. @foo this is the text argument to the [foo] custom tag. *) </pre><p> To handle custom tags, you need to define a custom generator, as explained in section <a href="#s%3Aocamldoc-handling-custom-tags">15.3.2</a>.</p> <h2 class="section" id="sec324">15.3  Custom generators</h2> <p> <a id="s:ocamldoc-custom-generators"></a></p><p>OCamldoc operates in two steps: </p><ol class="enumerate" type=1><li class="li-enumerate"> analysis of the source files; </li><li class="li-enumerate">generation of documentation, through a documentation generator, which is an object of class <span class="c007">Odoc_args.class_generator</span>. </li></ol><p> 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 <span class="c007">Odoc_info</span> module, which gives access to all the types and functions representing the elements found in the given modules, with their associated description.</p><p>The files you can use to define custom generators are installed in the <span class="c007">ocamldoc</span> sub-directory of the OCaml standard library.</p> <h3 class="subsection" id="sec325">15.3.1  The generator modules</h3> <p> The type of a generator module depends on the kind of generated documentation. Here is the list of generator module types, with the name of the generator class in the module : </p><ul class="itemize"><li class="li-itemize"> for HTML : <span class="c007">Odoc_html.Html_generator</span> (class <span class="c007">html</span>), </li><li class="li-itemize">for L<sup>A</sup>T<sub>E</sub>X : <span class="c007">Odoc_latex.Latex_generator</span> (class <span class="c007">latex</span>), </li><li class="li-itemize">for TeXinfo : <span class="c007">Odoc_texi.Texi_generator</span> (class <span class="c007">texi</span>), </li><li class="li-itemize">for man pages : <span class="c007">Odoc_man.Man_generator</span> (class <span class="c007">man</span>), </li><li class="li-itemize">for graphviz (dot) : <span class="c007">Odoc_dot.Dot_generator</span> (class <span class="c007">dot</span>), </li><li class="li-itemize">for other kinds : <span class="c007">Odoc_gen.Base</span> (class <span class="c007">generator</span>). </li></ul><p> That is, to define a new generator, one must implement a module with the expected signature, and with the given generator class, providing the <span class="c007">generate</span> method as entry point to make the generator generates documentation for a given list of modules :</p><pre> method generate : Odoc_info.Module.t_module list -> unit </pre><p> This method will be called with the list of analysed and possibly merged <span class="c007">Odoc_info.t_module</span> structures.</p><p>It is recommanded to inherit from the current generator of the same kind as the one you want to define. Doing so, it is possible to load various custom generators to combine improvments brought by each one.</p><p>This is done using first class modules (see chapter <a href="extn.html#s-first-class-modules">7.14</a>).</p><p>The easiest way to define a custom generator is the following this example, here extending the current HTML generator. We don’t have to know if this is the original HTML generator defined in ocamldoc or if it has been extended already by a previously loaded custom generator :</p><pre>module Generator (G : Odoc_html.Html_generator) = struct class html = object(self) inherit G.html as html (* ... *) method generate module_list = (* ... *) () (* ... *) end end;; let _ = Odoc_args.extend_html_generator (module Generator : Odoc_gen.Html_functor);; </pre><p> To know which methods to override and/or which methods are available, have a look at the different base implementations, depending on the kind of generator you are extending : </p><ul class="itemize"><li class="li-itemize"> for HTML : <a href="http://caml.inria.fr/cgi-bin/viewvc.cgi/ocaml/version/4.00/ocamldoc/odoc_html.ml?view=markup"><span class="c007">odoc_html.ml</span></a>, </li><li class="li-itemize">for L<sup>A</sup>T<sub>E</sub>X : <a href="http://caml.inria.fr/cgi-bin/viewvc.cgi/ocaml/version/4.00/ocamldoc/odoc_latex.ml?view=markup"><span class="c007">odoc_latex.ml</span></a>, </li><li class="li-itemize">for TeXinfo : <a href="http://caml.inria.fr/cgi-bin/viewvc.cgi/ocaml/version/4.00/ocamldoc/odoc_texi.ml?view=markup"><span class="c007">odoc_texi.ml</span></a>, </li><li class="li-itemize">for man pages : <a href="http://caml.inria.fr/cgi-bin/viewvc.cgi/ocaml/version/4.00/ocamldoc/odoc_man.ml?view=markup"><span class="c007">odoc_man.ml</span></a>, </li><li class="li-itemize">for graphviz (dot) : <a href="http://caml.inria.fr/cgi-bin/viewvc.cgi/ocaml/version/4.00/ocamldoc/odoc_dot.ml?view=markup"><span class="c007">odoc_dot.ml</span></a>. </li></ul> <h3 class="subsection" id="sec326">15.3.2  Handling custom tags</h3> <p> <a id="s:ocamldoc-handling-custom-tags"></a></p><p>Making a custom generator handle custom tags (see <a href="#s%3Aocamldoc-custom-tags">15.2.5</a>) is very simple.</p><h4 class="subsubsection" id="sec327">For HTML</h4> <p> Here is how to develop a HTML generator handling your custom tags.</p><p>The class <span class="c007">Odoc_html.Generator.html</span> inherits from the class <span class="c007">Odoc_html.info</span>, containing a field <span class="c007">tag_functions</span> which is a list pairs composed of a custom tag (e.g. <span class="c007">"foo"</span>) and a function taking a <span class="c007">text</span> and returning HTML code (of type <span class="c007">string</span>). To handle a new tag <span class="c007">bar</span>, extend the current HTML generator and complete the <span class="c007">tag_functions</span> field: </p><pre>module Generator (G : Odoc_html.Html_generator) = struct class html = object(self) inherit G.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 end let _ = Odoc_args.extend_html_generator (module Generator : Odoc_gen.Html_functor);; </pre><p> Another method of the class <span class="c007">Odoc_html.info</span> 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 <span class="c007">stderr</span>.</p> <h4 class="subsubsection" id="sec328">For other generators</h4> <p> You can act the same way for other kinds of generators.</p> <h2 class="section" id="sec329">15.4  Adding command line options</h2> <p> 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 </p><pre> Odoc_args.add_option : string * Arg.spec * string -> unit </pre><p>Note: Existing command line options can be redefined using this function.</p> <h3 class="subsection" id="sec330">15.4.1  Compilation and usage</h3> <p> <a id="s:ocamldoc-compilation-and-usage"></a></p> <h4 class="subsubsection" id="sec331">Defining a custom generator class in one file</h4> <p> Let <span class="c007">custom.ml</span> be the file defining a new generator class. Compilation of <span class="c007">custom.ml</span> can be performed by the following command : </p><pre> ocamlc -I +ocamldoc -c custom.ml </pre><p> The file <span class="c007">custom.cmo</span> is created and can be used this way : </p><pre> ocamldoc -g custom.cmo <span class="c013">other-options source-files</span> </pre><p> It is important not to give the <span class="c007">-html</span> or any other option selecting a built-in generator to <span class="c007">ocamldoc</span>, which would result in using this generator instead of the one you just loaded.</p> <h4 class="subsubsection" id="sec332">Defining a custom generator class in several files</h4> <p> It is possible to define a generator class in several modules, which are defined in several files <span class="c013">file</span><sub>1</sub><span class="c007">.ml</span>[<span class="c007">i</span>], <span class="c013">file</span><sub>2</sub><span class="c007">.ml</span>[<span class="c007">i</span>], ..., <span class="c013">file</span><sub><span class="c013">n</span></sub><span class="c007">.ml</span>[<span class="c007">i</span>]. A <span class="c007">.cma</span> library file must be created, including all these files.</p><p>The following commands create the <span class="c007">custom.cma</span> file from files <span class="c013">file</span><sub>1</sub><span class="c007">.ml</span>[<span class="c007">i</span>], ..., <span class="c013">file</span><sub><span class="c013">n</span></sub><span class="c007">.ml</span>[<span class="c007">i</span>] : </p><pre> ocamlc -I +ocamldoc -c <span class="c013">file</span><sub>1</sub>.ml[i] ocamlc -I +ocamldoc -c <span class="c013">file</span><sub>2</sub>.ml[i] ... ocamlc -I +ocamldoc -c <span class="c013">file</span><sub><span class="c013">n</span></sub>.ml[i] ocamlc -o custom.cma -a <span class="c013">file</span><sub>1</sub>.cmo <span class="c013">file</span><sub>2</sub>.cmo ... <span class="c013">file</span><sub><span class="c013">n</span></sub>.cmo </pre><p> Then, the following command uses <span class="c007">custom.cma</span> as custom generator: </p><pre> ocamldoc -g custom.cma <span class="c013">other-options source-files</span> </pre><p> Again, it is important not to give the <span class="c007">-html</span> or any other option selecting a built-in generator to <span class="c007">ocamldoc</span>, which would result in using this generator instead of the one you just loaded. </p> <hr> <a href="browser.html"><img src="previous_motif.gif" alt="Previous"></a> <a href="index.html"><img src="contents_motif.gif" alt="Up"></a> <a href="debugger.html"><img src="next_motif.gif" alt="Next"></a> </body> </html>