ocamldoc无法使用@param正确显示参数名称或描述

问题描述

简单地说，让我们说我有以下名为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模块的文档，则会得到以下结果：

可以看出，对于参数信息，它以()作为参数的名称，并且出于某种原因不包括对参数的描述。

我不确定为什么参数名称和描述没有正确显示。

解决方法

如果您输入ComboBox，则显示正确：

问题在于，如果您提供的标签与命名参数不匹配，但无法从let id x = x中提取命名参数，那么ocamldoc将不会显示@param。

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

,

作为ocamldoc的兼职维护者，在没有odoc的情况下仍然有很多理由仍然使用ocamldoc，在编写新文档时更是如此。

Ocamldoc对其param标签的处理实在太复杂了：ocamldoc试图窥视该函数的定义，仅接受与它可以识别的参数匹配的param标签。在这里，它对显式类型注释失败。