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

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

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

(Введено в OCaml 4.03)

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

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

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

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

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

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 Комментарии к элементам

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

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 Комментарии к меткам

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

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 "]