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

• 12.18.1 Комментарии плавающие
• 12.18.2 Комментарии к элементам
• 12.18.3 Комментарии к меткам

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

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

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

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

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

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

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