| | | |
Chapter 15 The documentation generator (ocamldoc)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 (**…*) and follow the format described in section 15.2. OCamldoc can produce documentation in various formats: HTML, LATEX, TeXinfo, Unix man pages, and dot dependency graphs. Moreover, users can add their own custom generators, as explained in section 15.3. In this chapter, we use the word element 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. 15.1 Usage15.1.1 InvocationOCamldoc is invoked via the command ocamldoc, as follows:
ocamldoc options sourcefiles
Options for choosing the output formatThe following options determine the format for the generated documentation.
General options
Type-checking optionsOCamldoc 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.
Options for generating HTML pagesThe following options apply in conjunction with the -html option:
Options for generating LATEX filesThe following options apply in conjunction with the -latex option:
Options for generating TeXinfo filesThe following options apply in conjunction with the -texi option:
Options for generating dot graphsThe following options apply in conjunction with the -dot option:
Options for generating man filesThe following options apply in conjunction with the -man option:
15.1.2 Merging of module informationInformation 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:
15.1.3 Coding rulesThe following rules must be respected in order to avoid name clashes resulting in cross-reference errors:
15.2 Syntax of documentation commentsComments 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. 15.2.1 Placement of documentation commentsOCamldoc 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 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 filesA 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
15.2.2 The Stop special commentThe 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. 15.2.3 Syntax of documentation commentsThe 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. 15.2.4 Text formattingHere is the BNF grammar for the simple markup language used to format text descriptions. text ::= (text_element)+
(** 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
outside of the following text formatting : {ul list}, {ol list}, [string], {[string]}, {v string v}, {% string%}, {!string}, {^ text}, {_ text}. 15.2.5 Documentation tags (@-tags)Predefined tags
The folowing table gives the list of predefined @-tags, with their
syntax and meaning.
Custom tagsYou 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. 15.3 Custom generatorsOCamldoc operates in two steps:
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. 15.3.1 The generator class
A generator class is a class of type Odoc_args.doc_generator.
It has only one method 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. 15.3.2 Handling custom tagsMaking a custom generator handle custom tags (see 15.2.5) is very simple. For HTMLHere 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 generatorsAs 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. 15.4 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 15.4.1 Compilation and usageDefining 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 : 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.
|