第 12 章 語言擴展

18 文件註解

(OCaml 4.03 引入)

以 ** 開頭的註解會被編譯器特殊處理。它們在解析期間會自動轉換為屬性 (參見 12.12)，以允許工具將其作為文件處理。

此類註解可以採用三種形式：浮動註解、項目註解和標籤註解。任何以 ** 開頭且不符合這些形式的註解都會導致編譯器發出警告 50。

以 ** 開頭的註解也由 ocamldoc 文件產生器使用（參見 19）。編譯器識別的三種註解形式是 ocamldoc 接受的形式的子集（參見 19.2）。

18.1 浮動註解

出現在結構、簽名、類別或類別類型中，且被空白行包圍的註解會轉換為 浮動屬性。例如

type t = T (** 現在是 [t] 的一些定義 *) let mkT = T

將會轉換為

type t = T [@@@ocaml.text " 現在是 [t] 的一些定義 "] let mkT = T

18.2 項目註解

緊接在結構項目、簽名項目、類別項目或類別類型項目之前或之後的註解會轉換為 項目屬性。緊接之前或緊接之後表示它們之間不能有空白行、;; 或其他文件註解。例如

type t = T (** [t] 的描述 *)

或

(** [t] 的描述 *) type t = T

將會轉換為

type t = T [@@ocaml.doc " [t] 的描述 "]

請注意，如果註解緊鄰多個項目，如

type t = T (** 一個模稜兩可的註解 *) type s = S

則它會附加到兩個項目

type t = T [@@ocaml.doc " 一個模稜兩可的註解 "] type s = S [@@ocaml.doc " 一個模稜兩可的註解 "]

並且編譯器會發出警告 50。

18.3 標籤註解

緊接在標記的參數、記錄欄位、變體建構子、物件方法或多型變體建構子之後的註解會轉換為 屬性。緊接之後表示它們之間不能有空白行或其他文件註解。例如

type t1 = lbl:int (** 標記的參數 *) -> unit type t2 = { fld: int; (** 記錄欄位 *) fld2: float; } type t3 = | Cstr of string (** 變體建構子 *) | Cstr2 of string type t4 = < meth: int * int; (** 物件方法 *) > type t5 = [ `PCstr (** 多型變體建構子 *) ]

將會轉換為

type t1 = lbl:(int [@ocaml.doc " 標記的參數 "]) -> unit type t2 = { fld: int [@ocaml.doc " 記錄欄位 "]; fld2: float; } type t3 = | Cstr of string [@ocaml.doc " 變體建構子 "] | Cstr2 of string type t4 = < meth : int * int [@ocaml.doc " 物件方法 "] > type t5 = [ `PCstr [@ocaml.doc " 多型變體建構子 "] ]

請注意，標籤註解優先於項目註解，因此

type t = T of string (** 附加到 T 而非 t *)

將會轉換為

type t = T of string [@ocaml.doc " 附加到 T 而非 t "]

而

type t = T of string (** 附加到 T 而非 t *) (** 附加到 t *)

將會轉換為

type t = T of string [@ocaml.doc " 附加到 T 而非 t "] [@@ocaml.doc " 附加到 t "]

如果類型的最後一個建構子沒有有意義的註解，則可以使用空的註解 ‍(**) 來代替

type t = T of string (**) (** 附加到 t *)

會直接轉換為

type t = T of string [@@ocaml.doc " 附加到 t "]
Copyright © 2024 法國國家資訊與自動化研究院