ocamldoc options sourcefiles

-html

Generate documentation in HTML default format. The generated HTML pages are stored in the current directory, or in the directory specified with the -d option. You can customize the style of the generated pages by editing the generated style.css file, or by providing your own style sheet using option -css-style.

-latex

Generate documentation in L^AT_EX default format. The generated L^AT_EX document is saved in file ocamldoc.out, or in the file specified with the -o option. The document uses the style file ocamldoc.sty included in the OCamldoc distribution. You can change this file to customize the style of your L^AT_EX documentation.

-texi

Generate documentation in TeXinfo default format. The generated L^AT_EX document is saved in file ocamldoc.out, or in the file specified with the -o option.

-man

Generate documentation as a set of Unix man pages. The generated pages are stored in the current directory, or in the directory specified with the -d option.

-dot

Generate a dependency graph for the toplevel modules, in a format suitable for displaying and processing by dot. The dot tool is available from http://www.research.att.com/sw/tools/graphviz/. The textual representation of the graph is written to the file ocamldoc.out, or to the file specified with the -o option. Use dot ocamldoc.out to display it.

-g file.cm[o,a]

Dynamically load the given file, which defines a custom documentation generator. See section 15.4.1. This option is supported by the ocamldoc command, but not by its native-code version ocamldoc.opt.

-d dir

Generate files in directory dir, rather than in the current directory.

-dump file

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

-hide modules

Hide the given complete module names in the generated documentation modules is a list of complete module names are separated by ',', without blanks. For instance: Pervasives,M2.M3.

-inv-merge-ml-mli

Inverse implementations and interfaces when merging. All elements in implementation files are kept, and the -m option indicates which parts of the comments in interface files are merged with the comments in implementation files.

-keep-code

Always keep the source code for values, methods and instance variables, when available. The source code is always kept when a .ml file is given, but is by default discarded when a .mli is given. This option allows to always keep the source code.

-load file

Load information from file, which has been produced by ocamldoc -dump. Several -load options can be given.

-m flags

Specify merge options between interfaces and implementations. (see section 15.1.2 for details). flags can be one or several of the following characters:

d

merge description

a

merge @author

v

merge @version

l

merge @see

s

merge @since

o

merge @deprecated

p

merge @param

e

merge @raise

r

merge @return

A

merge everything

-no-custom-tags

Do not allow custom @-tags (see section 15.2.5).

-no-stop

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

-o file

Output the generated documentation to file instead of ocamldoc.out. This option is meaningful only in conjunction with the -latex, -texi, or -dot options.

-pp command

Pipe sources through preprocessor command.

-sort

Sort the list of top-level modules before generating the documentation.

-stars

Remove blank characters until the first asterisk ('*') in each line of comments.

-t title

Use title as the title for the generated documentation.

-v

Verbose mode. Display progress information.

-warn-error

Treat warnings as errors.

-I directory

Add directory to the list of directories search for compiled interface files (.cmi files).

-nolabels

Ignore non-optional labels in types.

-rectypes

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

-all-params

Display the complete list of parameters for functions and methods.

-css-style filename

Use filename as the Cascading Style Sheet file.

-colorize-code

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

-index-only

Generate only index files.

-latex-value-prefix prefix

Give a prefix to use for the labels of the values in the generated L^AT_EX document. The default prefix is the empty string. You can also use the options -latex-type-prefix, -latex-exception-prefix, -latex-module-prefix, -latex-module-type-prefix, -latex-class-prefix, -latex-class-type-prefix, -latex-attribute-prefix and -latex-method-prefix.

These options are useful when you have, for example, a type and a value with the same name. If you do not specify prefixes, L^AT_EX will complain about multiply defined labels.

-latextitle n,style

Associate style number n to the given L^AT_EX sectioning command style, e.g. section or subsection. (L^AT_EX only.) This is useful when including the generated document in another L^AT_EX document, at a given sectioning level. The default association is 1 for section, 2 for subsection, 3 for subsubsection, 4 for paragraph and 5 for subparagraph.

-noheader

Suppress header in generated documentation.

-notoc

Do not generate a table of contents (L^AT_EX only).

-notrailer

Suppress trailer in generated documentation.

-sepfiles

Generate one .tex file per toplevel module, instead of the global ocamldoc.out file.

-esc8

Escape accented characters in Info files.

-noindex

Do not build index for Info files.

-dot-colors colors

Specify the colors to use in the generated dot code. When generating module dependencies, ocamldoc uses different colors for modules, depending on the directories in which they reside. When generating types dependencies, ocamldoc uses different colors for types, depending on the modules in which they are defined. colors is a list of color names separated by ',', as in Red,Blue,Green. The available colors are the ones supported by the dot tool.

-dot-include-all

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

-dot-reduce

Perform a transitive reduction of the dependency graph before outputting the dot code. This can be useful if there are a lot of transitive dependencies that clutter the graph.

-dot-types

Output dot code describing the type dependency graph instead of the module dependency graph.

-man-mini

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

-man-suffix

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

• Only elements (values, types, classes, ...) declared in the .mli file are kept. In other terms, definitions from the .ml file that are not exported in the .mli file are not documented.
• 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 .ml file is concatenated to the one in the .mli file, if the corresponding -m flag is given on the command line. If a description is present in the .ml file and not in the .mli file, the .ml description is kept. In either case, all the information given in the .mli file is kept.

• In a module, there must not be two modules, two module types or a module and a module type with the same name.
• In a module, there must not be two classes, two class types or a class and a class type with the same name.
• In a module, there must not be two values, two types, or two exceptions with the same name.
• Values defined in tuple, as in let (x,y,z) = (1,2,3) are not kept by OCamldoc.
• Avoid the following construction:

  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
  

  In this case, OCamldoc will associate Bar.x to the x of module Foo defined just above, instead of to the Bar.x defined in the opened module Foo.

• 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.
• The special comment is not already associated to the previous element.
• The special comment is not the first one of a toplevel module.

(** 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

(** 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

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

(** 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
*)

(** Here is a {b list}
- item 1
- item 2
- item 3

The list is ended by the blank line.*)

(** Here is a {b list} 
{ul {- item 1}
{- item 2}
{- item 3}}
The list is ended by the blank line.*)

• the first dot followed by a blank, or
• the first blank line

(** My comment to show you a custom tag.
@foo this is the text argument to the [foo] custom tag.
*)

1. analysis of the source files;
2. generation of documentation, through a documentation generator, which is an object of class Odoc_args.class_generator.

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)

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