如何为val定义的Scala函数通过Scaladoc生成参数文档？

这个问题确实挺常见的——Scaladoc对def方法的参数处理很友好，但对val定义的函数值（也就是FunctionN类型的实例）默认不会自动解析并显示@param标签的内容。不过有几个办法可以让你的val函数参数文档显示得和def方法一样清晰：

方法1：显式声明函数类型+保留@param标签 #

虽然Scaladoc不会自动提取函数值的参数列表，但只要你显式写出函数的类型签名，同时保留@param和@return标签，生成的文档就会正确展示这些参数说明。示例代码如下：

/** 判断数字是否为偶数
 * @param i 要判断的目标数字
 * @return 若输入为偶数则返回true，否则返回false
 */
val isEvenVal: Int => Boolean = i => i % 2 == 0

生成的Scaladoc会展示@param i的说明，和def方法的参数文档格式一致，只是不会像def那样单独列出参数列表（毕竟这本质上是一个持有函数实例的val），但参数的说明内容会完整呈现。

方法2：用@note补充参数细节（可选） #

如果希望更明确地强调参数信息，可以配合@note标签来补充，不过这属于锦上添花的操作：

/** 判断数字是否为偶数
 * @note 输入参数：
 *       - i: 要判断的整数
 * @return 若输入为偶数则返回true，否则返回false
 */
val isEvenVal = (i: Int) => i % 2 == 0

这种方式适合需要更结构化展示参数的场景，但不如第一种方法贴近def的文档风格。

为什么默认不显示？ #

简单说，def是方法，属于类/对象的成员，Scaladoc会专门解析方法的参数列表；而val定义的函数是函数实例（比如Function1[Int, Boolean]的实例），Scaladoc默认把它当作一个普通的变量，不会去解析它指向的函数的参数。所以我们需要通过显式类型声明+保留标签的方式，引导Scaladoc展示参数信息。

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