ocamldoc неправильно отображает имена или описание параметров с помощью @param

Question

Проще говоря, допустим, у меня есть следующий файл OCaml с именем test.ml:

       (**
    [Test] is a sample module for showing the problem I am having with @ tags with OCamlDoc
*)

(**
    [id] is the identity function. For any argument [x], [id x] is [x].
    @param x The argument, which will be returned
    @return The argument [x]
*)
let id (x: 'a): 'a = x

Если я запустил команду ocamldoc -html -all-params -colorize-code test.ml получить документацию для Test модуль, я получаю следующий результат:

Как видно, для информации о параметрах он помещает () как имя параметра и по какой-то причине не включает описание параметра.

Я не уверен, почему имя и описание параметра не отображаются должным образом.

Answer 1

Если вы напишете let id x = x отображение правильное:

Проблема в том, что ocamldoc не отображает @param если вы предоставляете тег, который не соответствует именованному аргументу, но не может извлечь именованный аргумент из (id : type).

Это известная ошибка, но, к сожалению, ее никто не трогал, поэтому... https://github.com/ocaml/ocaml/issues/8804

Answer 2

Как сопровождающий ocamldoc, работающий неполный рабочий день, очень мало причин продолжать использовать ocamldoc, когда odoc доступен, тем более при написании новой документации.

Обработка тега param в Ocamldoc слишком сложна для собственного блага: ocamldoc пытается просмотреть определение функции и принимает только тег param, который соответствует аргументу, который он может распознать. Здесь он не работает при явном аннотации типа.