java - 如何使用 sbt 的 GenJavaDoc 插件？

Question

我有一个非常基本的 sbt 项目，除了一个 .java 文件之外的所有 scala 代码，我需要为其生成一个标准的 javadoc 网页。

我正在尝试按照 the plugin's README 上的说明进行操作。我已将“集成到 SBT 构建非常简单”之后的所有代码(定义变量JavaDoc 和 javadocSettings)复制到我的 build.sbt 文件，还添加了以下内容:

resolvers += "Typesafe Releases" at "https://repo.typesafe.com/typesafe/releases/"

autoCompilerPlugins := true

说明说我必须“将[] javadocSettings 添加到项目”。我不知道这意味着什么。这是自述文件中的代码的作用，还是我需要做的单独的事情？如果是这样，怎么办？

无论如何，自述文件继续说道:“可以使用 genjavadoc:doc 生成 JavaDoc。”然而，在 sbt 中我看到:

> genjavadoc:doc
[error] No such setting/task
[error] genjavadoc:doc
[error]               ^
>

我错过了什么？

Answer 1

您需要一个配置，如 README.md 中所述。插件的。您的任务调用不起作用，因为没有 genjavadoc通常在 sbt 中。

您必须按照插件文档中的说明添加它。在你的build.sbt文件添加插件推荐的以下内容(保留您已有的内容):

lazy val JavaDoc = config("genjavadoc") extend Compile

lazy val javadocSettings = inConfig(JavaDoc)(Defaults.configSettings) ++ Seq(
  libraryDependencies += compilerPlugin("com.typesafe.genjavadoc" %% "genjavadoc-plugin" % "0.7" cross CrossVersion.full),
  scalacOptions <+= target map (t => "-P:genjavadoc:out=" + (t / "java")),
  packageDoc in Compile <<= packageDoc in JavaDoc,
  sources in JavaDoc <<= (target, compile in Compile, sources in Compile) map ((t, c, s) =>
      (t / "java" ** "*.java").get ++ s.filter(_.getName.endsWith(".java"))),
  javacOptions in JavaDoc := Seq(),
  artifactName in packageDoc in JavaDoc :=
    ((sv, mod, art) => "" + mod.name + "_" + sv.binary + "-" + mod.revision + "-javadoc.jar")
)

但是要使其正常工作，您需要将配置和设置添加到项目中。最简单的方法是添加您的 build.sbt额外一行:

lazy val root = project.in(file(".")).configs(JavaDoc).settings(javadocSettings: _*)

现在您应该能够使用 genjavadoc:doc 生成 javadoc .

鉴于上述情况，完整的build.sbt可能看起来像这样:

resolvers += "Typesafe Releases" at "https://repo.typesafe.com/typesafe/releases/"

lazy val root = project.in(file(".")).configs(JavaDoc).settings(javadocSettings: _*)

lazy val JavaDoc = config("genjavadoc") extend Compile

lazy val javadocSettings = inConfig(JavaDoc)(Defaults.configSettings) ++ Seq(
  libraryDependencies += compilerPlugin("com.typesafe.genjavadoc" %% "genjavadoc-plugin" % "0.7" cross CrossVersion.full),
  scalacOptions <+= target map (t => "-P:genjavadoc:out=" + (t / "java")),
  packageDoc in Compile <<= packageDoc in JavaDoc,
  sources in JavaDoc <<= (target, compile in Compile, sources in Compile) map ((t, c, s) =>
      (t / "java" ** "*.java").get ++ s.filter(_.getName.endsWith(".java"))),
  javacOptions in JavaDoc := Seq(),
  artifactName in packageDoc in JavaDoc :=
    ((sv, mod, art) => "" + mod.name + "_" + sv.binary + "-" + mod.revision + "-javadoc.jar")
)

PS。小福利，如果您使用比 0.13.2 更新的 sbt，您可以定义 javadocSettings不使用<<=和<+=以及其他类似的运算符，如下所示:

lazy val javadocSettings = inConfig(JavaDoc)(Defaults.configSettings) ++ Seq(
  addCompilerPlugin("com.typesafe.genjavadoc" %% "genjavadoc-plugin" % "0.7" cross CrossVersion.full),
  scalacOptions += s"-P:genjavadoc:out=${target.value}/java",
  packageDoc in Compile := (packageDoc in JavaDoc).value,
  sources in JavaDoc := 
    (target.value / "java" ** "*.java").get ++ (sources in Compile).value.filter(_.getName.endsWith(".java")),
  javacOptions in JavaDoc := Seq(),
  artifactName in packageDoc in JavaDoc :=
    ((sv, mod, art) => "" + mod.name + "_" + sv.binary + "-" + mod.revision + "-javadoc.jar")
)