Глава 12 Расширения языка

18 Комментарии документации

• 18.1 Плавающие комментарии
• 18.2 Комментарии элементов
• 18.3 Комментарии меток

(Добавлено в OCaml 4.03)

Комментарии, начинающиеся с **, обрабатываются компилятором особым образом. Во время синтаксического анализа они автоматически преобразуются в атрибуты (см. 12.12), чтобы инструменты могли обрабатывать их как документацию.

Такие комментарии могут принимать три формы: плавающие комментарии, комментарии элементов и комментарии меток. Любой комментарий, начинающийся с ** и не соответствующий ни одной из этих форм, приведёт к тому, что компилятор выдаст предупреждение 50.

Комментарии, начинающиеся с **, также используются генератором документации ocamldoc (см. 19). Три формы комментариев, распознаваемые компилятором, являются подмножеством форм, принимаемых ocamldoc (см. 19.2).

18.1 Плавающие комментарии

Комментарии, окружённые пустыми строками и расположенные внутри структур, сигнатур, классов или типов классов, преобразуются в floating-attribute. Например:

type t = T

(** Now some definitions for [t] *)

let mkT = T

будет преобразован в:

type t = T

[@@@ocaml.text " Now some definitions for [t] "]

let mkT = T

18.2 Комментарии элементов

Комментарии, расположенные непосредственно перед или непосредственно после элемента структуры, элемента сигнатуры, элемента класса или элемента типа класса, преобразуются в item-attribute. Непосредственно перед или непосредственно после означает, что между ними не должно быть пустых строк, ;; или других комментариев документации. Например:

type t = T
(** A description of [t] *)

или

(** A description of [t] *)
type t = T

будет преобразован в:

type t = T
[@@ocaml.doc " A description of [t] "]

Обратите внимание: если комментарий расположен непосредственно рядом с несколькими элементами, как в примере:

type t = T
(** An ambiguous comment *)
type s = S

то он будет связан с обоими элементами:

type t = T
[@@ocaml.doc " An ambiguous comment "]
type s = S
[@@ocaml.doc " An ambiguous comment "]

и компилятор выдаст предупреждение 50.

18.3 Комментарии меток

Комментарии, расположенные непосредственно после аргумента с меткой, поля записи, конструктора варианта, метода объекта или конструктора полиморфного варианта, преобразуются в attribute. Непосредственно после означает, что между ними не должно быть пустых строк или других комментариев документации. Например:

type t1 = lbl:int (** Labelled argument *) -> unit

type t2 = {
  fld: int; (** Record field *)
  fld2: float;
}

type t3 =
  | Cstr of string (** Variant constructor *)
  | Cstr2 of string

type t4 = < meth: int * int; (** Object method *) >

type t5 = [
  `PCstr (** Polymorphic variant constructor *)
]

будет преобразован в:

type t1 = lbl:(int [@ocaml.doc " Labelled argument "]) -> unit

type t2 = {
  fld: int [@ocaml.doc " Record field "];
  fld2: float;
}

type t3 =
  | Cstr of string [@ocaml.doc " Variant constructor "]
  | Cstr2 of string

type t4 = < meth : int * int [@ocaml.doc " Object method "] >

type t5 = [
  `PCstr [@ocaml.doc " Polymorphic variant constructor "]
]

Обратите внимание, что комментарии меток имеют приоритет над комментариями элементов, поэтому:

type t = T of string
(** Attaches to T not t *)

будет преобразован в:

type t =  T of string [@ocaml.doc " Attaches to T not t "]

тогда как:

type t = T of string
(** Attaches to T not t *)
(** Attaches to t *)

будет преобразован в:

type t =  T of string [@ocaml.doc " Attaches to T not t "]
[@@ocaml.doc " Attaches to t "]

Если у последнего конструктора типа нет содержательного комментария, вместо него можно использовать пустой комментарий (**):

type t = T of string
(**)
(** Attaches to t *)

он будет преобразован непосредственно в

type t =  T of string
[@@ocaml.doc " Attaches to t "]