ocamldoc options sourcefiles

-html

デフォルトのHTML形式で文書を生成します。生成されたHTMLページは現在のディレクトリか、もしくは -d オプションで指定したディレクトリに保存します。生成されたページのスタイルは生成された style.css ファイルを修正することで可能です。もしくは -css-style オプションによって自分のスタイルシートを指定できます。

-latex

デフォルトの L^AT_EX 形式で文書を生成します。生成された L^AT_EX ドキュメントは ocamldoc.out という名前のファイルか、 -o オプションで指定した名前のファイルで保存されます。ドキュメントは OCamldoc の配布物に含まれる ocamldoc.sty というスタイルを使います。このファイルは好きな L^AT_EX 文書スタイルファイルに変更できます。

-texi

デフォルトの TeXinfo 形式で文書を生成します。生成された L^AT_EX 文書は ocamldoc.out という名前のファイルか、 -o オプションで指定した名前のファイルで保存されます。

-man

Unixの man ページの集まりとして文書を生成されます。生成されたページは現在のディレクトリか、 -d オプションで指定したディレクトリに保存されます。

-dot

トップレベルモジュールのための依存グラフを生成します。フォーマットは dot によって表示／処理されます。dot ツールは http://www.research.att.com/sw/tools/graphviz/ から利用できます。このグラフのテキスト表現は ocamldoc.out という名前のファイルか、 -o オプションで指定されるファイルに保存されます。表示には dot ocamldoc.out としてください。

-g file.cm[o,a]

カスタムの文書生成のために与えられたファイルを動的ロードします。 15.4.1 を参照してください。このオプションは ocamldoc コマンドではサポートされていますが、そのネイティブコード版である ocamldoc.opt ではサポートされていません。

-d dir

カレントディレクトリではなく、ディレクトリ dir にファイルを生成します。

-dump file

集めた情報をファイル file にダンプします。この情報は、次の ocamldoc 実行時の -load オプションによって読むことができます。

-hide modules

生成された文書から、指定した完全な名前のモジュールを隠します。modules は ',' で区切られ空白を含まない完全なモジュール名のリストです。例: Pervasives,M2.M3。

-inv-merge-ml-mli

マージの際に実装とインタフェースを反転させます。実装ファイルの全てのエレメントは保持され、 -m オプションはインタフェースファイルにあるコメントの断片を実装ファイルにあるコメントと統合することを意味します。

-keep-code

値、メソッド、インスタンス変数については、可能ならばソースコードを保持しておきます。ソースコードは .ml ファイルが与えられれば常に保持していますが、 .mli が与えられた時はデフォルトで捨ててしまいます。このオプションは常にソースコードを保持しておくためのものです。

-load file

file から、 ocamldoc -dump によって生成された情報をロードします。複数の -load オプションも可能です。

-m flags

インタフェースと実装をマージします (詳しくは 15.1.2 を参照)。flags は次の文字の1つ以上が指定可能です:

d

記述をマージ

a

@author をマージ

v

@version をマージ

l

@see をマージ

s

@since をマージ

o

@deprecated をマージ

p

@param をマージ

e

@raise をマージ

r

@return をマージ

A

すべてをマージ

-no-custom-tags

カスタム @-tags を許可しません (15.2.5を参照)。

-no-stop

(**/**) の特殊なコメントの後にあるエレメントをそのままにします(15.2 を参照のこと)。

-o file

生成した文書を ocamldoc.out のかわりに file に出力します。このオプションは -latex、 -texi、 -dot オプションと併用した時のみ意味があります。

-pp command

プリプロセッサ command にソースを通してから処理します。

-sort

文書生成の前にトップレベルモジュールのリストをソートします。

-stars

各コメント行で、最初のアスタリスク ('*') までの空白文字を削除します。

-t title

生成された文書のタイトルとして title を用います。

-v

冗長モードです。進行状況の情報を表示します。

-warn-error

警告をエラーとして扱います。

-I directory

コンパイルされたインタフェースファイル(.cmi files)を捜すディレクトリのリストに directory を加えます。

-nolabels

型におけるオプショナルなラベルを無視します。

-rectypes

曖昧な再帰型を許します(ocamlc の -rectypes を参照)。

-all-params

関数とメソッドの引数の完全なリストを表示します。

-css-style filename

filename をスタイルシートファイルとして利用します。

-colorize-code

[ ] や \{[ ]\} で囲まれた OCaml のコードの色をつけます。キーワード等々を強調するための色を用います。もしコード断片が文法的に正しくない時には、色は付加されません。

-index-only

インデックスファイルのみを生成します。

-latex-value-prefix prefix

生成された L^AT_EX 文書内の値のラベルとして使うためのプレフィクスを与えます。デフォルトは空の文字列です。同様なオプションとしては、 -latex-type-prefix 、 -latex-exception-prefix 、 -latex-module-prefix 、 -latex-module-type-prefix 、 -latex-class-prefix 、 -latex-class-type-prefix 、 -latex-attribute-prefix 、 -latex-method-prefix が使えます。

これらのオプションは例えば、同じ名前の型や値を持っている時に有用です。もしプレフィクスを与えなければ、 L^AT_EX は多重定義されたラベルについて文句を言うでしょう。

-latextitle n,style

スタイルの数 n と、与えられた L^AT_EX セクション分けコマンド style(すなわちsection や subsection)を関連つけます(L^AT_EX のみ有効)。これは生成されたドキュメントを他の L^AT_EX ドキュメントで与えられたセクションレベルにインクルードする時に有用です。デフォルトは section に対し1、subsection に対し2、 subsubsection に対し3、paragraph に対し4、subparagraph に対し5です。

-noheader

生成された文書のヘッダを抑制します。

-notoc

目次を生成しません (L^AT_EX のみ有効)。

-notrailer

生成された文書のトレーラを抑制します。

-sepfiles

単独の ocamldoc.out ファイルを生成するのではなく、トップレベルモジュールごとにひとつの .tex ファイルを生成します。

-esc8

Infoファイルのアクセントつき文字をエスケープします。

-noindex

Info ファイルに対してインデックスを生成しません。

-dot-colors colors

生成された dot コードのなかで使う色を指定します。モジュール依存性を生成するときには、 ocamldoc はそのモジュールが存在するディレクトリをもとにモジュールごとに異なった色を使います。型依存を生成する時には、ocamldoc は定義されたモジュールをもとに型ごとに異なった色を使います。 colors は ',' で区切られた色の名前のリストです。たとえば、Red,Blue,Green など。色は dot ツールでサポートされている色のみです。

-dot-include-all

コマンドラインや -load オプションで指定されているものだけでなく、 dot 出力における全てのモジュールを出力します。

-dot-reduce

dot コードを出力する前に、グラフの依存関係の遷移を削減します。これはグラフ中に依存関係が非常に多い場合に有効かもしれません。

-dot-types

モジュールの依存関係グラフではなく、型の依存関係グラフを表現した dot コードを出力します。

-man-mini

全てのエレメントではなく、モジュール、モジュール型、クラス、クラス型に関してのみ man ページを生成します。

-man-suffix

生成された man のファイル名にサフィックスを付加します。デフォルトは 'o'です。たとえば List.o のように。

• .mliファイルで宣言されているエレメント (値、型、クラス、etc.) のみが保持されます。言いかえれば、.mli ファイルに記述されていない .ml ファイル内の宣言は文書化されません。
• エレメントの記述や@-タグ内の記述は次のように扱われます。もし同じエレメントに関する記述や同じエレメントの@-タグにおける記述が両方のファイルに存在した場合は、対応する -m フラグをコマンドラインで与えておけば .ml ファイルの記述が .mli ファイル内の記述に連結されます。

• あるモジュールにおいて、同じ名前をもつ2つのモジュール、モジュール型が存在してはいけません。
• あるモジュールにおいて、同じ名前をもつ2つのクラス、クラス型が存在してはいけません。
• あるモジュールにおいて、同じ名前をもつ2つの値、型、例外が存在してはいけません。
• 組として定義された値、 let (x,y,z) = (1,2,3) などは OCamldoc によって保持されません。
• 次のようなモジュール定義を回避してください:

  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
  

  OCamldoc はこの場合、 Bar.x をオープンされた Foo の中の Bar.x ではなく、直前に定義された Foo の x と解釈します。

• スペシャルコメントとそのエレメントの間に空白行や他のスペシャルコメントが存在しない。しかし、スペシャルコメントとエレメントの間に通常のコメントが存在してもよい。
• スペシャルコメントは直前のエレメントと関連付けられない。
• スペシャルコメントはトップレベルモジュールの最初の1つではない。

(** ファイルの最初のスペシャルコメントはモジュール全体と関連付けられる
    コメントとなります。 *)


(** エレメントの間にもスペシャルコメントを配置することができ、 
     OCamldoc のツールによっても処理されますが、いかなるエレメントとも
     関連付けられません。こうしたコメントにある@-タグは無視されます。 *)

(*******************************************************************)
(** 上行のような2つより多いアスタリスクのコメントは無視されます。 *)

(** 関数 f のコメント *)
val f : int -> int -> int
(** 関数 f のコメントの続き。 *)

(** 例外 My_exception のコメント。普通のコメントが間にあります。 *)
(* やあ、僕は単なるコメントだよ :-) *)
exception My_exception of (int -> int) * int

(** 型 weather のコメント  *)
type weather =
| Rain of int (** 構築子 Rain のコメント *)
| Sun (** 構築子 Sun のコメント *) 

(** 型 weather2 のコメント *)
type weather2 =
| Rain of int (** 構築子 Rain のコメント *)
| Sun (** 構築子 Sun のコメント *) 
(** 直前のコメントがすでに型構築子と関連付けられているため、型 
    weather2 のコメントをここで継続することができます。 *)

(** 型 my_record のコメント *)
type my_record = {
    val foo : int ;    (** フィールド foo のコメント *)
    val bar : string ; (** フィールド bar のコメント *)
  }
  (** 型 my_record のコメントの続き *)

(** foo のためのコメント *)
val foo : string
(** このコメントは foo に関連付けられ、 bar には関連付けられません。 *)
val bar : string
(** このコメントは bar に関連付けられます。 *)

(** クラス my_class のコメント *)
class my_class :
  object
    (**  cl からの継承を記述するコメント *)
    inherit cl 

    (** 属性値 tutu のコメント *)
    val mutable tutu : string

    (** 属性値 toto のコメント *)
    val toto : int

    (** このコメントは空白行が間に存在するため、 titi のコメントにはな
        らず、クラス全体へのコメントとなります。 *)

    val titi : string

    (** メソッド toto のコメント *)
    method toto : string

    (** メソッド m のコメント *)
    method m : float -> int
  end

(** クラス型 my_class_type のコメント *)
class type my_class_type = 
  object
    (** 変数 x のコメント *)
    val mutable x : int
    
    (** メソッド m のコメント *)
    method m : int -> int
end
    
(** モジュール Foo のコメント *)
module Foo =
  struct
    (**  x のコメント *)
    val x : int

    (** どのエレメントとも関連付けられないスペシャルコメント *)
  end
    
(** モジュール型 my_module_type のコメント *)
module type my_module_type =
  sig
    (** 値 x のコメント *)
    val x : int

    (** モジュール M のコメント *)
    module M =
      struct
        (** 値 y のコメント *)
        val y : int

        (* ... *)
      end
        
  end

(** ファイルの最初のスペシャルコメントはモジュール全体と関連付けられた
    コメントです。 *)

(** 関数 f のコメント *)
let f x y = x + y

(** このコメントは次の行にエレメントがないため、エレメントに関連付けら
    れません。 *)

(** 例外 My_exception のコメント。普通のコメントがスペシャルコメントと
    例外の間にあります。 *)
(* 単純なコメント *)
exception My_exception of (int -> int) * int

(** 型 weather のコメント  *)
type weather =  
| Rain of int (** 構築子 Rain のコメント *)
| Sun (** 構築子 Sun のコメント *) 

(** 型 my_record のコメント *)
type my_record = {
    val foo : int ;    (** フィールド foo のコメント *)
    val bar : string ; (** フィールド bar のコメント *)
  }

(** クラス my_class のコメント *)  
class my_class =
    object
      (** cl からの継承について記述するコメント *)
      inherit cl 

      (** インスタンス変数 tutu のコメント *)
      val mutable tutu = "tutu"
      (**  toto のコメント *)
      val toto = 1 
      val titi = "titi"
      (** メソッド toto のコメント *)
      method toto = tutu ^ "!"
      (** メソッド m のコメント *)
      method m (f : float) = 1
    end
    
(** クラス型 my_class_type のコメント *)
class type my_class_type = 
  object
    (** インスタンス変数 x のコメント *)
    val mutable x : int
    (** メソッド m のコメント *)
    method m : int -> int
  end

(** モジュール Foo のコメント *)
module Foo =
  struct
    (** x のコメント *)
    val x : int 

    (** モジュール内のスペシャルコメントですが、どんなエレメントとも関
        連付けられません。 *)
  end

(** モジュール型 my_module_type のコメント *)
module type my_module_type =
  sig
    (* 値 x のコメント *)
    val x : int
    (* ... *)
  end

class type foo =
  object
    (** メソッド m のコメント *)
    method m : string
    
    (**/**)

    (** このメソッドは文書には現れません *)
    method bar : int
  end

(** この値は文書には現れます。なぜなら、クラス内のスペシャルコメントの
    無視はその親モジュールには影響を及ぼさないためです。 *)
val foo : string

(**/**)
(** 値 bar は文書には現れません。 *)
val bar : string

(** 型 t も現れません。 *)
type t = string

(** このコメントは次のセクションに記述されたルールに則ったテキストで記
    述されています。記述は最初のエスケープされていない '@' 文字まで続
    きます。
    @author Mr Smith
    @param x パラメータxの記述
*)

(** これが {b リスト}
- 要素 1
- 要素 2
- 要素 3

リストは空白行で終わり。*)

(** これが {b リスト} 
{ul {- 要素 1}
{- 要素 2}
{- 要素 3}}
リストは空白行で終わり。*)

• 最初に空白のあとにピリオドが来るまでか、
• 最初の空白行まで

(** カスタムタグを示すためのコメントですよ。
    @foo ここは [foo] カスタムタグに対する引数部分
*)

1. ソースファイルの解析;
2. 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

    (** bar タグと text から HTML コードを出力する *)
    method html_of_bar t = (* コードを書く *) 
    
    initializer
      tag_functions <- ("bar", self#html_of_bar) :: tag_functions 
  end