ocaml - 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显示是正确的：

问题是，@param如果您提供的标签与命名参数不匹配，但无法从(id : type).

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

Answer 2

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

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