Chapter 15 ドキュメント生成 (ocamldoc)

このページは最後に更新されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

この章ではソースファイル内に特別な形式で書かれたコメントからドキュメントを生成するツールである OCamldoc について説明します．OCamldocで使用されるコメントは (** ... *) の形式で書かれます． section 15.2 でこのフォーマットについて説明します．

OCamldoc はHTML，LaTeX，TeXinfo?，Unix man page，dot dependency graph といった，いろいろなフォーマットで出力できます．さらに，ユーザがカスタムしたジェネレータを追加することもできます．これについては section 15.3 で説明します．

この章では，OCaml のソースコードのそれぞれの部分に対して説明します．

• 型宣言(type declaration)
• 値(value)，モジュール(module)
• 例外(exception)
• モジュールの型(module type)
• 型コンストラクタ(type constructor)
• レコードフィールド(record field)
• クラス(class)
• クラスの型(class type)
• クラスメソッド(class method)
• クラスの値(class value)
• class inheritance clause

使用法

起動

OCamldoc は ocamldoc コマンドで以下のように起動します．

        ocamldoc options sourcefiles

出力フォーマットを選択するオプション

以下のオプションによって生成されるドキュメントのフォーマットが決定されます．

• html

  • HTMLでドキュメントを生成します．生成されるHTMLのページはカレントディレクトリか，-dオプションので指定されたディレクトリに置かれます． 生成されたstyle.cssファイルを編集するか， --css-style オプションを使用して指定したユーザ独自のスタイルシートによって，生成されたページのスタイルをカスタマイズすることができます．style.css ファイルは既に存在するときには生成されません．

• latex

  • LaTeX としてドキュメントを生成します．生成される LaTeX ドキュメントは ocamldoc.out か，もしくは -o オプションで指定されたファイル名として保存されます．このドキュメントはスタイルファイル ocamldoc.sty を使用します．このファイルは -latex オプションを使用した時に生成され，もし既に存在していれば生成されません．このファイルを編集してLaTeXドキュメントのスタイルをカスタマイズすることもできます．

• texi

  • TeXinfo? のフォーマットでドキュメントを生成します．生成された LaTeX ドキュメントは ocamldoc.out か -o オプションで指定されたファイル名で保存されます．

• man

  • Unix man page としてドキュメントを生成します．生成されたページはカレントディレクトリか -d オプションで指定されたディレクトリに保存されます．

• dot

  • 表示および処理のしやすい dot による形式でトップレベルモジュールに対する依存グラフを生成します．dot ツールは http://www.research.att.com/sw/tools/graphviz/ から取得できます．グラフのテキストによる表現は ocamldoc.out に出力されるか， -o オプションで指定されたファイルに出力されます．ocamldoc.out を dot ツールに入力してグラフを表示することができます．

• 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. 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 -i options.

• customdir Display the custom generators default directory.

• i directory Add the given directory to the path where to look for custom generators.

General options

• 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/between the (**/**) special comment(s) (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.

• intro file Use content of file as ocamldoc text to use as introduction (HTML, LaTeXand? TeXinfo? only). For HTML, the file is used to create the whole index.html file.

• v Verbose mode. Display progress information.

• warn-error Treat warnings as errors.

• hide-warnings Do not print OCamldoc warnings.

Type-checking options

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 ocamlc and ocamlopt commands.

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

Options for generating HTML pages

The following options apply in conjunction with the -html option:

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

• short-functors Use a short form to display functors: module M : functor (A:Module) -> functor (B:Module2) -> sig .. end is displayed as module M (A:Module) (B:Module2) : sig .. end.

Options for generating LaTeX files

The following options apply in conjunction with the -latex option:

• latex-value-prefix prefix Give a prefix to use for the labels of the values in the generated LaTeX document. The default prefix is the empty string. You can also use the options -latex-type-prefix, -latex-exception-prefix,

• latex-module-prefix, -latex-module-type-prefix, -latex-class-prefix,
• latex-class-type-prefix, -latex-attribute-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, LaTeX will complain about multiply defined labels.

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

• noheader Suppress header in generated documentation.

• notoc Do not generate a table of contents.

• notrailer Suppress trailer in generated documentation.

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

Options for generating TeXinfo? files

The following options apply in conjunction with the -texi option:

• esc8 Escape accented characters in Info files.

• info-entry Specify Info directory entry.

• info-section Specify section of Info directory.

• noheader Suppress header in generated documentation.

• noindex Do not build index for Info files.

• notrailer Suppress trailer in generated documentation.

Options for generating dot graphs

The following options apply in conjunction with the -dot option:

• dot-colors colors Specify the colors to use in the generated dot code. When 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.

Options for generating man files

The following options apply in conjunction with the -man option:

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

Merging of module information

Information on a module can be extracted either from the .mli or .ml file, or both, depending on the files given on the command line. When both .mli and .ml files are given for the same module, information extracted from these files is merged according to the following rules:

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

Coding rules

The following rules must be respected in order to avoid name clashes resulting in cross-reference errors:

• 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 ab and AB will be printed to the same file on case insensitive file systems.

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

Syntax of documentation comments

Comments containing documentation material are called special comments and are written between (** and *). Special comments must start exactly with (**. Comments beginning with ( and more than two * are ignored.

Placement of documentation comments

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 .mli and .ml files are different.

Comments in .mli files

A special comment is associated to an element if it is placed before or after the element.

A special comment before an element is associated to this element if :

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

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.

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. The special comment for a type constructor with another type constructor following must be placed before the '|' character separating the two constructors.

The following sample interface file foo.mli illustrates the placement rules for comments in .mli files.

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

Comments in .ml files

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. The special comment for a type constructor with another type constructor following must be placed before the '|' character separating the two constructors.

The following example of file toto.ml shows where to place comments in a .ml file.

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

The Stop special comment

The special comment (**/**) 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:

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

The -no-stop option to ocamldoc causes the Stop special comments to be ignored.

Syntax of documentation comments

The inside of documentation comments (**...*) consists of free-form text with optional formatting annotations, followed by optional tags giving more specific information about parameters, version, authors, ... The tags are distinguished by a leading @ character. Thus, a documentation comment has the following shape:

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

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 @param tag on a class instance variable is ignored.

At last, (**) is the empty documentation comment.

Text formatting

Here is the BNF grammar for the simple markup language used to format text descriptions.

 text ::= (text_element)+

text_element ::=

| {[0-9]+ text}                 format text as a section     
                                header; the integer          
                                following { indicates the    
                                sectioning level.            
| {[0-9]+:label text}            same, but also associate    
                                the name label to the        
                                current point. This point    
                                can be referenced by its     
                                fully-qualified label in a   
                                {! command, just like any    
                                other element.               
| {b text}                      set text in bold.            
| {i text}                      set text in italic.          
| {e text}                      emphasize text.              
| {C text}                      center text.                 
| {L text}                      left align text.             
| {R text}                      right align text.            
| {ul list}                     build a list.                
| {ol list}                     build an enumerated list.    
| {{:string}text}               put a link to the given      
                                address (given as a string)  
                                on the given text.           
| [string]                      set the given string in      
                                source code style.           
| {[string]}                    set the given string in      
                                preformatted 				source code 
                                style.                       
| {v string v}                  set the given string in      
                                verbatim style.              
| {% string %}                  take the given string as raw 

LaTeX code.

| {!string}                     insert a reference to the    
                                element named string. string 
                                must be a fully qualified    
                                element name, for example    

Foo.Bar.t. The kind of the

                                referenced element can be    
                                forced (useful when various  
                                elements have the same       
                                qualified name) with the     
                                following syntax: {!kind:    

Foo.Bar.t} where kind can be

                                module, modtype, class,      
                                classtype, val, type,        
                                exception, attribute, method 
                                or section.                  
| {!modules: string string ...} insert an index table for    
                                the given module names. Used 
                                in HTML only.                
| {!indexlist}                  insert a table of links to   
                                the various indexes (types,  
                                values, modules, ...). Used  
                                in HTML only.                
| {^ text}                      set text in superscript.     
| {_ text}                      set text in subscript.       
| escaped_string                typeset the given string as  
                                is; special characters ('{', 
                                '}', '[', ']' and '@') must  
                                be	escaped by a '\'          
| blank_line                    force a new line.            

list ::=

   | ({- text})+
   | ({li text})+

A shortcut syntax exists for lists and enumerated lists:

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

The list is ended by the blank line.*)
 is equivalent to: 

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

The same shortcut is available for enumerated lists, using '+' instead of '-'. Note that only one list can be defined by this shortcut in nested lists.

In the description of a value, type, exception, module, module type, class or class type, the first sentence 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

• the first dot followed by a blank, or

• the first blank line outside of the following text formatting : {ul list}, {ol list}, [string], {[string]}, {v string v}, {% string%}, {!string}, {^ text}, {_ text}.

Documentation tags (@-tags)

Predefined tags

The folowing table gives the list of predefined @-tags, with their syntax and meaning.

| |tags for the same element. |

| |the reason for deprecation. |

| |and functors. |

|text |raise the exception Exc. |

| |functions and methods. |

| |given text as comment. |

| |given text as comment. |

| |the given text as comment. |

| |was introduced. |

|string |element. |

Custom tags

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 foo, just put @foo with some text in your comment, as in:

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

To handle custom tags, you need to define a custom generator, as explained in section 15.3.2.

Custom generators

OCamldoc operates in two steps:

1. analysis of the source files; 
2. generation of documentation, through a documentation generator, 	which is

an object of class Odoc_args.class_generator.

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 Odoc_info module, which gives access to all the types and functions representing the elements found in the given modules, with their associated description.

The files you can used to define custom generators are installed in the ocamldoc sub-directory of the OCaml standard library.

The generator class

A generator class is a class of type Odoc_args.doc_generator. It has only one method

 generator : Odoc_info.Module.t_module list -> unit

This method will be called with the list of analysed and possibly merged Odoc_info.t_module structures. Of course the class can have other methods, but the object of this class must be coerced to Odoc_args.doc_generator before being passed to the function

Odoc_args.set_doc_generator : Odoc_args.doc_generator -> unit

 which installs the new documentation generator.

The following example shows how to define and install a new documentation generator. See the odoc_fhtml generator (in the Ocamldoc Hump) for a complete example.

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)

Note: The new class can inherit from Odoc_html.html, Odoc_latex.latex, Odoc_man.man, Odoc_texi.texi or Odoc_dot.dot, and redefine only some methods to benefit from the existing methods.

Handling custom tags

Making a custom generator handle custom tags (see 15.2.5) is very simple.

For HTML

Here is how to develop a HTML generator handling your custom tags.

The class Odoc_html.html inherits from the class Odoc_html.info, containing a field tag_functions which is a list pairs composed of a custom tag (e.g. 'foo') and a function taking a text and returning HTML code (of type string). To handle a new tag bar, create a HTML generator class from the existing one and complete the tag_functions field:

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

Another method of the class Odoc_html.info 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 stderr.

For other generators

As for the HTML custom generator, you can define a new LaTeX(resp. man) generator by inheriting from the class Odoc_latex.latex (resp. Odoc_man.man) and adding your own tag handler to the field tag_functions.

Adding command line options

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

Odoc_args.add_option : string * Arg.spec * string -> unit

Note: Existing command line options can be redefined using this function.

Compilation and usage

Defining a custom generator class in one file

Let custom.ml be the file defining a new generator class. Compilation of custom.ml can be performed by the following command :

 ocamlc -I +ocamldoc -c custom.ml

The file custom.cmo is created and can be used this way :

 ocamldoc -g custom.cmo other-options source-files

It is important not to give the -html or any other option selecting a built in generator to ocamldoc, which would result in using this generator instead of the one you just loaded.

Defining a custom generator class in several files

It is possible to define a generator class in several modules, which are defined in several files file1.ml[i], file2.ml[i], ..., fileN.ml[i]. A .cma library file must be created, including all these files.

The following commands create the custom.cma file from files file1.ml[i], ..., fileN.ml[i] :

 ocamlc -I +ocamldoc -c file1.ml[i]
 ocamlc -I +ocamldoc -c file2.ml[i]
 ...
 ocamlc -I +ocamldoc -c fileN.ml[i]
 ocamlc -o custom.cma -a file1.cmo file2.cmo ... fileN.cmo

Then, the following command uses custom.cma as custom generator:

 ocamldoc -g custom.cma other-options source-files

Again, it is important not to give the -html or any other option selecting a built in generator to ocamldoc, which would result in using this generator instead of the one you just loaded.