odoc能否显示函数默认参数？是否有对应命令行选项？

我定义了如下OCaml函数：

let rec eval ?(env : environment = []) (t : term) : value =
  match t with
  | TVar idx -> List.nth env idx
  | TLam body -> VClosure (env, body)
  | TAppl (m, n) ->
    let rator = eval ~env m in
    let rand = eval ~env n in
    (match rator with
     | VClosure (env', body) -> eval ~env:(rand :: env') body
     | VNeutral neutral -> VNeutral (NAppl (neutral, rand)))
;;

使用dune build @doc生成文档时，希望env参数的默认值[]能在文档中显示，但实际生成的文档只显示：

val eval : ?env:environment -> term -> value

解决方案 #

目前odoc没有专门的命令行选项来强制显示默认参数值，但可以通过以下两种方式实现需求：

• 手动添加文档注释：在函数上方添加包含默认参数信息的OCamldoc注释，odoc会提取并展示这些内容：

  (** 计算 term 的值，默认环境为 []
      @param env 计算时使用的环境，默认值为 [] *)
  let rec eval ?(env : environment = []) (t : term) : value =
    (* ... 函数实现 ... *)
  ;;
  

• 显式在签名中定义默认参数：如果项目使用.mli接口文件，需要在签名里完整写出默认参数的定义，而不是简写形式：

  val eval : ?(env:environment = []) -> term -> value
  

  这样odoc生成文档时会直接显示带默认值的签名。

内容的提问来源于stack exchange，提问作者hirrolot