使用Scaladoc 3生成文档为何未显示square函数内容？

云上老周

2026-6-15

Scaladoc 3生成文档失败的问题分析及解决要点

问题重现步骤

创建square.scala文件，内容如下：

/** This is the square function */
def square(d: Double): Double = d * d

直接使用Scaladoc CLI处理.scala文件失败：

scaladoc --version
# Scaladoc version 3.6.2 -- Copyright 2002-2024, LAMP/EPFL

scaladoc square.scala
# scaladoc supports only .tasty and .jar files,
# following files will be ignored: square.scala

编译生成JAR包：

scalac --version
# Scala compiler version 3.6.2 -- Copyright 2002-2024, LAMP/EPFL

scalac square.scala -d square.jar

jar tf square.jar
# META-INF/MANIFEST.MF
# square$package$.class
# square$package.class
# square$package.tasty

执行scaladoc square.jar -d output生成文档后，输出目录包含网页资源，但未显示square函数及其注释。

忽略的基础要点及解决方法

未将函数放在Scaladoc可识别的顶层结构中
Scala 3会自动把文件顶层的函数包装到匿名包的package对象里，但Scaladoc默认不展示匿名包的内容。你需要把函数放到显式包、类或对象中，示例：
```
package mymath

/** This is the square function */
def square(d: Double): Double = d * d
```
或者封装到对象：
```
object MathUtils {
  /** This is the square function */
  def square(d: Double): Double = d * d
}
```
编译时未生成文档元数据
默认编译生成的.tasty文件不包含文档注释信息，需要添加-Ygenerate-doc参数让编译器保留文档元数据，编译命令改为：
```
scalac square.scala -d square.jar -Ygenerate-doc
```
未配置Scaladoc展示匿名包内容（可选）
如果坚持使用顶层函数（匿名包），可以在Scaladoc命令中加-package参数强制展示匿名包的内容：
```
scaladoc square.jar -d output -package
```
但更推荐使用显式包结构，避免依赖这个特殊参数。