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

#ocaml #documentation #documentation-generation #code-documentation #ocamldoc

#ocaml #Документация #генерация документации #код-документация #ocamldoc

Вопрос:

Проще говоря, допустим, у меня есть следующий вызываемый файл 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 модуля, я получаю следующий результат:

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

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

Ответ №1:

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

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

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

Ответ №2:

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

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