Глава 17 Генератор документации (ocamldoc)

• 17.1 Использование
• 17.2 Синтаксис комментариев документации
• 17.3 Пользовательские генераторы
• 17.4 Добавление параметров командной строки

В этой главе описывается OCamldoc, инструмент, который генерирует документацию из специальных комментариев, встроенных в исходные файлы. Комментарии, используемые OCamldoc, имеют вид (**…*) и следуют формату, описанному в разделе 17.2.

OCamldoc может создавать документацию в различных форматах: HTML, L^AT_EX, TeXinfo, страницы руководства Unix и графики зависимостей dot. Кроме того, пользователи могут добавлять свои собственные пользовательские генераторы, как описано в разделе 17.3.

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

17.1 Использование

17.1.1 Вызов

OCamldoc вызывается через команду ocamldoc, следующим образом:

        ocamldoc options sourcefiles

Параметры для выбора формата вывода

Следующие параметры определяют формат сгенерированной документации.

-html

Генерирует документацию в формате HTML по умолчанию. Сгенерированные страницы HTML сохраняются в текущей директории или в директории, указанной параметром -d. Вы можете настроить стиль сгенерированных страниц, отредактировав файл style.css, или предоставив свой собственный стилевой лист с помощью параметра -css-style. Файл style.css не генерируется, если он уже существует или используется параметр -css-style.

-latex

Генерирует документацию в формате L^AT_EX по умолчанию. Сгенерированный документ L^AT_EX сохраняется в файле ocamldoc.out или в файле, указанном параметром -o. Документ использует стилевой файл ocamldoc.sty. Этот файл генерируется при использовании параметра -latex, если он ещё не существует. Вы можете изменить этот файл, чтобы настроить стиль документации L^AT_EX.

-texi

Генерирует документацию в формате TeXinfo по умолчанию. Сгенерированный документ L^AT_EX сохраняется в файле ocamldoc.out или в файле, указанном параметром -o.

-man

Генерирует документацию в виде набора страниц Unix man. Сгенерированные страницы сохраняются в текущей директории или в директории, указанной параметром -d.

-dot

Генерирует граф зависимостей для модулей верхнего уровня в формате, пригодном для отображения и обработки инструментом dot. Инструмент dot доступен на сайте https://graphviz.org/. Текстовое представление графика записывается в файл ocamldoc.out или в файл, указанный параметром -o. Используйте команду dot ocamldoc.out для его отображения.

-g file.cm[o,a,xs]

Динамическая загрузка указанного файла, который определяет пользовательский генератор документации. См. раздел 17.4.1. Этот параметр поддерживается командой ocamldoc (для загрузки файлов .cmo и .cma) и его версией для нативного кода ocamldoc.opt (для загрузки файлов .cmxs). Если указанный файл является простым и не существует в текущей директории, то ocamldoc ищет его в директории пользовательских генераторов по умолчанию и в директориях, указанных с помощью дополнительных параметров -i.

-customdir

Отображает директорию пользовательских генераторов по умолчанию.

-i directory

Добавляет указанную директорию в путь для поиска пользовательских генераторов.

Общие параметры

-d dir

Генерировать файлы в каталоге dir, а не в текущем каталоге.

-dump file

Выгрузить собранную информацию в файл file. Эта информация может быть прочитана с помощью опции -load в последующем вызове ocamldoc.

-hide modules

Скрыть указанные полные имена модулей в сгенерированной документации. modules — список полных имён модулей, разделённых символом ‘,’, без пробелов. Например: Stdlib,M2.M3.

-inv-merge-ml-mli

Изменить порядок приоритета реализации и интерфейсов при объединении. Все элементы в файлах реализации сохраняются, а опция -m указывает, какие части комментариев в файлах интерфейсов объединяются с комментариями в файлах реализации.

-keep-code

Всегда сохранять исходный код для значений, методов и переменных экземпляров, если он доступен.

-load file

Загрузить информацию из файла file, сгенерированного командой ocamldoc -dump. Можно использовать несколько опций -load.

-m flags

Указать параметры объединения между интерфейсами и реализациями. (подробности см. в разделе 17.1.2). flags могут быть одним или несколькими из следующих символов:

d

объединить описание

a

объединить @author

v

объединить @version

l

объединить @see

s

объединить @since

b

объединить @before

o

объединить @deprecated

p

объединить @param

e

объединить @raise

r

объединить @return

A

объединить всё

-no-custom-tags

Не разрешать пользовательские теги @ (см. раздел 17.2.5).

-no-stop

Сохранять элементы, расположенные после/между специальными комментариями (**/**) (см. раздел 17.2).

-o file

Выводить сгенерированную документацию в файл file вместо ocamldoc.out. Эта опция имеет смысл только в сочетании с опциями -latex, -texi или -dot.

-pp command

Перенаправлять источники через препроцессор command.

-impl filename

Обрабатывать файл filename как файл реализации, даже если его расширение не .ml.

-intf filename

Обрабатывать файл filename как файл интерфейса, даже если его расширение не .mli.

-text filename

Обрабатывать файл filename как текстовый файл, даже если его расширение не .txt.

-sort

Сортировать список модулей верхнего уровня перед генерацией документации.

-stars

Удалить пробельные символы до первой звёздочки (’*’) в каждой строке комментариев.

-t title

Использовать title в качестве заголовка сгенерированной документации.

-intro file

Использовать содержимое файла file как текст ocamldoc для использования в качестве введения (только HTML, L^AT_EX и TeXinfo). Для HTML файл используется для создания всего файла index.html.

-v

Режим подробных сообщений. Отображать информацию о ходе выполнения.

-version

Вывести строку версии и завершить работу.

-vnum

Вывести короткую версию номера и завершить работу.

-warn-error

Считать предупреждения Ocamldoc как ошибки.

-hide-warnings

Не выводить предупреждения OCamldoc.

-help or --help

Отобразить краткое описание использования и завершить работу.

Параметры проверки типов

OCamldoc вызывает OCaml-проверяльщик типов для получения информации о типах. Следующие параметры влияют на этап проверки типов. Они имеют такое же значение, как для команд ocamlc и ocamlopt.

-I directory

Добавить directory в список каталогов для поиска скомпилированных файлов интерфейсов (.cmi).

-nolabels

Игнорировать необязательные метки в типах.

-rectypes

Разрешить произвольные рекурсивные типы. (См. опцию -rectypes для ocamlc).

Параметры для генерации HTML-страниц

Следующие параметры применяются совместно с параметром -html:

-all-params

Отобразить полный список параметров для функций и методов.

-charset charset

Добавить информацию о кодировке символов charset (по умолчанию iso-8859-1).

-colorize-code

Выделить цветным цветом код OCaml, заключенный в [ ] и {[ ]}, используя цвета для выделения ключевых слов и т. п. Если фрагменты кода не синтаксически корректны, цвет не добавляется.

-css-style filename

Использовать filename в качестве файла таблицы стилей Cascading Style Sheet.

-index-only

Сгенерировать только файлы индексов.

-short-functors

Использовать короткий формат для отображения функторов:

module M : functor (A:Module) -> functor (B:Module2) -> sig .. end

отображается как:

module M (A:Module) (B:Module2) : sig .. end

Параметры для генерации файлов L^AT_EX

Следующие параметры применяются совместно с параметром -latex:

-latex-value-prefix prefix

Указать префикс для меток значений в генерируемом документе L^AT_EX. По умолчанию префикс пустой. Также можно использовать параметры -latex-type-prefix, -latex-exception-prefix, -latex-module-prefix, -latex-module-type-prefix, -latex-class-prefix, -latex-class-type-prefix, -latex-attribute-prefix и -latex-method-prefix.

Эти параметры полезны, например, если у вас есть тип и значение с одинаковым именем. Если не указать префиксы, L^AT_EX выдаст ошибку о многократном определении меток.

-latextitle n,style

Связать номер стиля n с заданной командой структурирования L^AT_EX style, например, section или subsection. (Только для L^AT_EX.) Это полезно при включении генерируемого документа в другой документ L^AT_EX на заданном уровне структурирования. По умолчанию ассоциации: 1 для section, 2 для subsection, 3 для subsubsection, 4 для paragraph и 5 для subparagraph.

-noheader

Запретить заголовок в генерируемой документации.

-notoc

Не генерировать оглавление.

-notrailer

Запретить заключение в генерируемой документации.

-sepfiles

Сгенерировать один файл .tex на модуль верхнего уровня вместо глобального файла ocamldoc.out.

Параметры для генерации файлов TeXinfo

Следующие параметры применяются совместно с параметром -texi:

-esc8

Убежать от символов с диакритическими знаками в файлах Info.

-info-entry

Указать запись в каталоге Info.

-info-section

Указать раздел каталога Info.

-noheader

Запретить заголовок в генерируемой документации.

-noindex

Не создавать индекс для файлов Info.

-notrailer

Запретить заключение в генерируемой документации.

Параметры для генерации графиков dot

Следующие параметры применяются совместно с параметром -dot:

-dot-colors colors

Указать цвета для использования в генерируемом коде dot. При генерации зависимостей модулей ocamldoc использует разные цвета для модулей в зависимости от каталогов, в которых они находятся. При генерации зависимостей типов ocamldoc использует разные цвета для типов в зависимости от модулей, в которых они определены. colors — список имен цветов, разделенных символом ',', например, Красный,Синий,Зелёный. Доступные цвета — те, которые поддерживает инструмент dot.

-dot-include-all

Включать все модули в выходные данные dot, а не только модули, указанные в командной строке или загруженные с помощью параметра -load.

-dot-reduce

Выполнить редукцию транзитивных зависимостей графа зависимостей перед выводом кода dot. Это может быть полезно, если существует множество транзитивных зависимостей, которые перегружают граф.

-dot-types

Выводить код dot, описывающий граф зависимостей типов, а не граф зависимостей модулей.

Параметры для генерации файлов man

Следующие параметры применяются совместно с параметром -man:

-man-mini

Генерировать страницы man только для модулей, типов модулей, классов и типов классов, а не для всех элементов.

-man-suffix suffix

Установить суффикс, используемый для сгенерированных имен файлов man. По умолчанию — ’3o’, как в List.3o.

-man-section section

Установить номер раздела, используемый для сгенерированных имен файлов man. По умолчанию — ’3’.

17.1.2 Объединение информации о модулях

Информация о модуле может быть извлечена из файла .mli или .ml, или из обоих, в зависимости от файлов, заданных в командной строке. Если для одного модуля заданы файлы .mli и .ml, информация, извлечённая из этих файлов, объединяется в соответствии со следующими правилами:

• Только элементы (значения, типы, классы и т. д.) объявленные в файле .mli сохраняются. Другими словами, определения из файла .ml, которые не экспортированы в файл .mli, не документируются.
• Описание элементов и описания в тегах @ обрабатываются следующим образом. Если описание для одного и того же элемента или в том же теге @ того же элемента присутствует в обоих файлах, то описание из файла .ml конкатенируется с описанием в файле .mli, если соответствующий флаг -m указан в командной строке. Если описание присутствует в файле .ml, но отсутствует в файле .mli, то описание из файла .ml сохраняется. В любом случае, вся информация из файла .mli сохраняется.

17.1.3 Правила кодирования

Для избежания конфликтов имён, приводящих к ошибкам перекрестных ссылок, необходимо соблюдать следующие правила:

• В модуле не должно быть двух модулей, двух типов модулей или модуля и типа модуля с одинаковым именем. В генераторе HTML по умолчанию модули ab и AB будут выведены в один и тот же файл на файловой системе, не учитывающей регистр.
• В модуле не должно быть двух классов, двух типов классов или класса и типа класса с одинаковым именем.
• В модуле не должно быть двух значений, двух типов или двух исключений с одинаковым именем.
• Значения, определённые в кортежах, как в let (x,y,z) = (1,2,3), не сохраняются OCamldoc.
• Избегайте следующей конструкции:

  open Foo (* which has a module Bar with a value x *)
  module Foo =
    struct
      module Bar =
        struct
          let x = 1
        end
    end
    let dummy = Bar.x

  В этом случае OCamldoc сопоставит Bar.x со значением x модуля Foo, определённого выше, вместо Bar.x, определённого в открытом модуле Foo.

17.2 Синтаксис комментариев документации

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

17.2.1 Размещение комментариев документации

OCamlDoc может связывать комментарии с некоторыми элементами языка, встречающимися в исходных файлах. Связывание осуществляется в соответствии с расположением комментариев относительно элементов языка. Расположения комментариев в файлах .mli и .ml различны.

Комментарии в файлах .mli

Специальный комментарий связывается с элементом, если он расположен перед или после элемента.
Специальный комментарий перед элементом связывается с этим элементом, если:

• Между специальным комментарием и элементом нет пустых строк или других специальных комментариев. Однако обычный комментарий может быть между специальным комментарием и элементом.
• Специальный комментарий ещё не связан с предыдущим элементом.
• Специальный комментарий не является первым в модуле верхнего уровня.

Специальный комментарий после элемента связывается с этим элементом, если между ними нет пустых строк или комментариев.

Существуют два исключения: для конструкторов и полей записей в определениях типов соответствующий комментарий может быть размещён только после определения конструктора или поля, без пустых строк или других комментариев между ними. Специальный комментарий для конструктора с другим конструктором, следующим за ним, должен быть помещён перед символом ’|’, разделяющим два конструктора.

Следующий пример интерфейсного файла foo.mli иллюстрирует правила размещения комментариев в файлах .mli.

(** The first special comment of the file is the comment associated
    with the whole module.*)


(** Special comments can be placed between elements and are kept
    by the OCamldoc tool, but are not associated to any element.
    @-tags in these comments are ignored.*)

(*******************************************************************)
(** Comments like the one above, with more than two asterisks,
    are ignored. *)

(** The comment for function f. *)
val f : int -> int -> int
(** The continuation of the comment for function f. *)

(** Comment for exception My_exception, even with a simple comment
    between the special comment and the exception.*)
(* Hello, I'm a simple comment :-) *)
exception My_exception of (int -> int) * int

(** Comment for type weather  *)
type weather =
| Rain of int (** The comment for constructor Rain *)
| Sun (** The comment for constructor Sun *)

(** Comment for type weather2  *)
type weather2 =
| Rain of int (** The comment for constructor Rain *)
| Sun (** The comment for constructor Sun *)
(** I can continue the comment for type weather2 here
  because there is already a comment associated to the last constructor.*)

(** The comment for type my_record *)
type my_record = {
    foo : int ;    (** Comment for field foo *)
    bar : string ; (** Comment for field bar *)
  }
  (** Continuation of comment for type my_record *)

(** Comment for foo *)
val foo : string
(** This comment is associated to foo and not to bar. *)
val bar : string
(** This comment is associated to bar. *)

(** The comment for class my_class *)
class my_class :
  object
    (** A comment to describe inheritance from cl *)
    inherit cl

    (** The comment for attribute tutu *)
    val mutable tutu : string

    (** The comment for attribute toto. *)
    val toto : int

    (** This comment is not attached to titi since
        there is a blank line before titi, but is kept
        as a comment in the class. *)

    val titi : string

    (** Comment for method toto *)
    method toto : string

    (** Comment for method m *)
    method m : float -> int
  end

(** The comment for the class type my_class_type *)
class type my_class_type =
  object
    (** The comment for variable x. *)
    val mutable x : int

    (** The comment for method m. *)
    method m : int -> int
end

(** The comment for module Foo *)
module Foo :
  sig
    (** The comment for x *)
    val x : int

    (** A special comment that is kept but not associated to any element *)
  end

(** The comment for module type my_module_type. *)
module type my_module_type =
  sig
    (** The comment for value x. *)
    val x : int

    (** The comment for module M. *)
    module M :
      sig
        (** The comment for value y. *)
        val y : int

        (* ... *)
      end

  end

Комментарии в файлах .ml

Специальный комментарий связывается с элементом, если он расположен перед элементом, и между комментарием и элементом нет пустых строк. В то же время между специальным комментарием и элементом может быть обычный комментарий. Существуют два исключения: для конструкторов и полей записей в определениях типов, комментарий должен быть расположен после определения конструктора или поля, без пустой строки между ними. Специальный комментарий для конструктора, за которым следует другой конструктор, должен быть помещен перед символом ’|’, разделяющим два конструктора.

Следующий пример файла toto.ml показывает, где размещать комментарии в файле .ml.

(** The first special comment of the file is the comment associated
    to the whole module. *)

(** The comment for function f *)
let f x y = x + y

(** This comment is not attached to any element since there is another
    special comment just before the next element. *)

(** Comment for exception My_exception, even with a simple comment
    between the special comment and the exception.*)
(* A simple comment. *)
exception My_exception of (int -> int) * int

(** Comment for type weather  *)
type weather =
| Rain of int (** The comment for constructor Rain *)
| Sun (** The comment for constructor Sun *)

(** The comment for type my_record *)
type my_record = {
    foo : int ;    (** Comment for field foo *)
    bar : string ; (** Comment for field bar *)
  }

(** The comment for class my_class *)
class my_class =
    object
      (** A comment to describe inheritance from cl *)
      inherit cl

      (** The comment for the instance variable tutu *)
      val mutable tutu = "tutu"
      (** The comment for toto *)
      val toto = 1
      val titi = "titi"
      (** Comment for method toto *)
      method toto = tutu ^ "!"
      (** Comment for method m *)
      method m (f : float) = 1
    end

(** The comment for class type my_class_type *)
class type my_class_type =
  object
    (** The comment for the instance variable x. *)
    val mutable x : int
    (** The comment for method m. *)
    method m : int -> int
  end

(** The comment for module Foo *)
module Foo =
  struct
    (** The comment for x *)
    let x = 0
    (** A special comment in the class, but not associated to any element. *)
  end

(** The comment for module type my_module_type. *)
module type my_module_type =
  sig
    (* Comment for value x. *)
    val x : int
    (* ... *)
  end

17.2.2 Специальный комментарий Stop

Специальный комментарий (**/**) сообщает OCamldoc об игнорировании элементов, расположенных после этого комментария, вплоть до конца текущего класса, типа класса, модуля или типа модуля, или до следующего комментария stop. Например:

class type foo =
  object
    (** comment for method m *)
    method m : string

    (**/**)

    (** This method won't appear in the documentation *)
    method bar : int
  end

(** This value appears in the documentation, since the Stop special comment
    in the class does not affect the parent module of the class.*)
val foo : string

(**/**)
(** The value bar does not appear in the documentation.*)
val bar : string
(**/**)

(** The type t appears since in the documentation since the previous stop comment
toggled off the "no documentation mode". *)
type t = string

Опция -no-stop для ocamldoc приводит к игнорированию специальных комментариев Stop.

17.2.3 Синтаксис комментариев документации

Внутри комментариев документации (**…*) содержится текстовая информация произвольной формы с необязательными аннотациями форматирования, а также необязательными тегами, предоставляющими более подробную информацию о параметрах, версии, авторах и т. д. Теги различаются символом @ в начале. Таким образом, комментарий документации имеет следующий вид:

(** The comment begins with a description, which is text formatted
   according to the rules described in the next section.
   The description continues until the first non-escaped '@' character.
   @author Mr Smith
   @param x description for parameter x
*)

Некоторые элементы поддерживают только подмножество всех тегов @. Теги, не относящиеся к документируемому элементу, просто игнорируются. Например, все теги игнорируются при документировании конструкторов типов, полей записей и положений наследования классов. Аналогично, тег @param для переменной экземпляра класса игнорируется.

Наконец, (**) — это пустой комментарий документации.

17.2.4 Форматирование текста

Вот грамматика БНФ для простого языка разметки, используемого для форматирования текстовых описаний.

17.2.4.1 Форматирование списков

Существует сокращённый синтаксис для списков и нумерованных списков:

(** Here is a {b list}
- item 1
- item 2
- item 3

The list is ended by the blank line.*)

эквивалентно:

(** Here is a {b list}
{ul {- item 1}
{- item 2}
{- item 3}}
The list is ended by the blank line.*)

Тот же ярлык доступен для нумерованных списков, используя ’+’ вместо ’-’. Обратите внимание, что только один список может быть определен этим ярлыком во вложенных списках.

17.2.4.2 Форматирование перекрестных ссылок

Перекрестные ссылки — это полностью квалифицированные имена элементов, как в примере {!Foo.Bar.t}. Это неоднозначная ссылка, так как она может обозначать имя типа, имя значения, имя класса и т. д. Можно сделать явным намеченный синтаксический класс, используя {!type:Foo.Bar.t} для обозначения типа и {!val:Foo.Bar.t} — значения с тем же именем.

Список возможных синтаксических классов:

В случае с конструкторами вариантов или записей, имя конструктора или поля должно предваряться именем соответствующего типа — чтобы избежать неоднозначности нескольких типов с одинаковыми именами конструкторов. Например, конструктор Node типа tree будет ссылаться как {!tree.Node} или {!const:tree.Node}, или возможно {!Mod1.Mod2.tree.Node} извне модуля.

17.2.4.3 Первое предложение

В описании значения, типа, исключения, модуля, типа модуля, класса или типа класса иногда используется первое предложение в индексах или когда требуется только часть описания. Первое предложение состоит из первых символов описания до

• первой точки, за которой следует пробел, или
• первой пустой строки

вне следующих форматов текста: {ul list } , {ol list } , [ string ] , {[ string ]} , {v string v} , {% string %} , {! string } , {^ text } , {_ text } .

17.2.4.4 Форматирование, специфичное для целевой платформы

Содержимое внутри {%foo: ... %} специфично для целевой платформы и будет интерпретировано только бэкендом foo, а другими будет проигнорировано. Бэкэнды дистрибутива — latex, html, texi и man. Если целевая платформа не указана (синтаксис {% ... %}), по умолчанию используется latex. Пользовательские генераторы могут поддерживать собственный префикс целевой платформы.

17.2.4.5 Поддерживаемые HTML-теги

HTML-теги <b>..</b>, <code>..</code>, <i>..</i>, <ul>..</ul>, <ol>..</ol>, <li>..</li>, <center>..</center> и <h[0-9]>..</h[0-9]> могут быть использованы вместо соответственно {b ..} , [..] , {i ..} , {ul ..} , {ol ..} , {li ..} , {C ..} и {[0-9] ..}.

17.2.5 Теги документации (@-теги)

Предопределенные теги

В следующей таблице представлен список предопределенных @-тегов, их синтаксис и значение.

Пользовательские теги

Вы можете использовать пользовательские теги в комментариях документации, но они не будут иметь эффекта, если используемый генератор их не обрабатывает. Чтобы использовать пользовательский тег, например foo, просто напишите @foo с некоторым текстом в вашем комментарии, как в:

(** My comment to show you a custom tag.
@foo this is the text argument to the [foo] custom tag.
*)

Для обработки пользовательских тегов вам необходимо определить пользовательский генератор, как описано в разделе 17.3.2.

17.3 Пользовательские генераторы

OCamldoc работает в два этапа:

1. анализ исходных файлов;
2. генерация документации с помощью генератора документации, который является объектом класса Odoc_args.class_generator.

Пользователи могут предоставить собственный генератор документации для использования на втором этапе вместо стандартных генераторов. Все информация, полученная на этапе анализа, доступна через модуль Odoc_info, который предоставляет доступ ко всем типам и функциям, представляющим найденные элементы в заданных модулях, с их соответствующим описанием.

Файлы, которые можно использовать для определения пользовательских генераторов, установлены в подкаталоге ocamldoc стандартной библиотеки OCaml.

17.3.1 Модули генератора

Тип модуля генератора зависит от вида генерируемой документации. Вот список типов модулей генератора с именем класса генератора в модуле:

• для HTML : Odoc_html.Html_generator (класс html),
• для L^AT_EX : Odoc_latex.Latex_generator (класс latex),
• для TeXinfo : Odoc_texi.Texi_generator (класс texi),
• для страниц man : Odoc_man.Man_generator (класс man),
• для graphviz (dot) : Odoc_dot.Dot_generator (класс dot),
• для других типов : Odoc_gen.Base (класс generator).

То есть, для определения нового генератора необходимо реализовать модуль с ожидаемой сигнатурой и с заданным классом генератора, предоставив метод generate в качестве точки входа для генерации документации для заданного списка модулей :

        method generate : Odoc_info.Module.t_module list -> unit

Этот метод будет вызван со списком проанализированных и, возможно, объединённых структур Odoc_info.t_module.

Рекомендуется наследоваться от текущего генератора того же типа, что и тот, который вы хотите определить. Это позволяет загружать различные пользовательские генераторы для объединения улучшений, приносимых каждым из них.

Это делается с помощью модулей первого класса (см. главу 10.5).

Самый простой способ определить пользовательский генератор — следовать этому примеру, расширяя текущий генератор HTML. Нам не нужно знать, является ли это исходным генератором HTML, определённым в ocamldoc, или он уже был расширен ранее загруженным пользовательским генератором :

module Generator (G : Odoc_html.Html_generator) =
struct
  class html =
    object(self)
      inherit G.html as html
      (* ... *)

      method generate module_list =
        (* ... *)
        ()

      (* ... *)
  end
end;;

let _ = Odoc_args.extend_html_generator (module Generator : Odoc_gen.Html_functor);;

Чтобы узнать, какие методы переопределить и/или какие методы доступны, обратитесь к различным базовым реализациям в зависимости от типа генератора, который вы расширяете :

• для HTML : odoc_html.ml,
• для L^AT_EX : odoc_latex.ml,
• для TeXinfo : odoc_texi.ml,
• для страниц man : odoc_man.ml,
• для graphviz (dot) : odoc_dot.ml.

17.3.2 Обработка пользовательских тегов

Создание пользовательского генератора, обрабатывающего пользовательские теги (см. 17.2.5), очень просто.

Для HTML

Вот как разработать генератор HTML, обрабатывающий пользовательские теги.

Класс Odoc_html.Generator.html наследуется от класса Odoc_html.info, содержащего поле tag_functions, которое представляет собой список пар, состоящих из пользовательского тега (например, "foo") и функции, принимающей text и возвращающей HTML-код (типа string). Для обработки нового тега bar расширьте текущий генератор HTML и дополните поле tag_functions:

module Generator (G : Odoc_html.Html_generator) =
struct
  class html =
    object(self)
      inherit G.html

      (** Return HTML code for the given text of a bar tag. *)
      method html_of_bar t = (* your code here *)

      initializer
        tag_functions <- ("bar", self#html_of_bar) :: tag_functions
  end
end
let _ = Odoc_args.extend_html_generator (module Generator : Odoc_gen.Html_functor);;

Другой метод класса Odoc_html.info будет искать функцию, связанную с пользовательским тегом, и применять её к тексту, переданному тегу. Если функция, связанная с пользовательским тегом, не найдена, метод выведет сообщение об ошибке в stderr.

Для других генераторов

Вы можете действовать аналогично для других типов генераторов.

17.4 Добавление параметров командной строки

Анализ командной строки выполняется после загрузки модуля, содержащего генератор документации, что позволяет добавлять параметры командной строки в список существующих. Добавление параметра выполняется с помощью функции

        Odoc_args.add_option : string * Arg.spec * string -> unit

Примечание: существующие параметры командной строки могут быть переопределены с помощью этой функции.

17.4.1 Компиляция и использование

Определение пользовательского класса генератора в одном файле

Пусть custom.ml — файл, определяющий новый класс генератора. Компиляция custom.ml может быть выполнена с помощью следующей команды :

        ocamlc -I +ocamldoc -c custom.ml

Файл custom.cmo создаётся и может использоваться следующим образом :

        ocamldoc -g custom.cmo other-options source-files

Параметры, выбирающие встроенный генератор для ocamldoc, такие как -html, не имеют эффекта, если пользовательский генератор того же типа предоставляется с помощью -g. Если типы не совпадают, используется выбранный встроенный генератор, а пользовательский игнорируется.

Определение пользовательского класса генератора в нескольких файлах

Можно определить класс генератора в нескольких модулях, которые определены в нескольких файлах file₁.ml[i], file₂.ml[i], ..., file_n.ml[i]. Необходимо создать файл библиотеки .cma, включающий все эти файлы.

Следующие команды создают файл custom.cma из файлов file₁.ml[i], ..., file_n.ml[i] :

ocamlc -I +ocamldoc -c file1.ml[i]
ocamlc -I +ocamldoc -c file2.ml[i]
...
ocamlc -I +ocamldoc -c filen.ml[i]
ocamlc -o custom.cma -a file1.cmo file2.cmo ... filen.cmo

Затем следующая команда использует custom.cma в качестве пользовательского генератора :

        ocamldoc -g custom.cma other-options source-files