ocamldoc 未正确显示参数名称或带有@param 的描述

Question

简单地说，假设我有以下名为 test.ml 的 OCaml 文件：

(**
    [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显示是正确的：

问题是，如果您提供的标签与命名参数不匹配，但它无法从 (id : type).[=15 中提取命名参数，ocamldoc 将不会显示 @param =]

这是一个已知的错误，但遗憾的是没有人碰过它，所以...https://github.com/ocaml/ocaml/issues/8804

Answer 2

作为 ocamldoc 的兼职维护者，在 odoc 可用时没有理由继续使用 ocamldoc，在编写新文档时更是如此。

Ocamldoc 对 param 标签的处理过于复杂了：ocamldoc 试图查看函数的定义，并且只接受与它可以识别的参数匹配的 param 标签。在这里，它在显式类型注释上失败。

ocamldoc 未正确显示参数名称或带有@param 的描述

ocamldoc not properly displaying parameter names or description with @param

documentation

ocaml

documentation-generation

code-documentation

ocamldoc