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

​

​

问题是，如果您提供了一个与命名参数不匹配的标记，但是ocamldoc无法从(id : type)中提取命名参数，那么ocamldoc将不会显示@param。

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

Answer 2

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

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