15.1 使用法

15.1 使用法
前のページ	15. ドキュメント生成器（ocamldoc）	次のページ

15.1.1. 起動
15.1.2. Merging of module information
15.1.3. Coding rules

15.1.1 起動

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.
-version: Print the version string and exit.
-warn-error: Treat Ocamldoc warnings as errors.
-hide-warnings: Do not print OCamldoc warnings.
-help or --help: Display a short usage summary and exit.

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

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

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

前のページ	上に戻る	次のページ
15. ドキュメント生成器（ocamldoc）	ホーム	15.2 Syntax of documentation comments