第 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 "]
版权所有 © 2024 法国国家信息与自动化研究所