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

• 10.18.1 Комментарии плавающие
• 10.18.2 Комментарии к элементам
• 10.18.3 Комментарии к меткам

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

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

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

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

10.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

10.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.

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