如何从 Scala 的标准库继承 Scaladoc？答案

【问题标题】：How do I inherit Scaladoc from Scala's standard library?如何从 Scala 的标准库继承 Scaladoc？
【发布时间】：2014-07-09 01:52:58
【问题描述】：

如果我理解正确，方法的 Scaladoc 应该自动继承它覆盖的父方法的 Scaladoc。这似乎适用于一组本地类，但不是从 Scala 的标准库扩展时（并且可能是任何外部依赖项？）。

class LocalParent {
  /**
   * some documentation
   */
  def foo = ???
}

class DocumentedChild extends LocalParent

class UndocumentedChild extends Iterator[Int] {
   def hasNext = ???
   def next = ???
}

有没有办法继承Scaladoc？还是我做错了什么？

另外，我使用的是sbt doc，所以不是直接使用scaladoc。

【问题讨论】：

查看文档，其中指定了如何处理从外部依赖项导入文档：scala-sbt.org/0.13.2/docs/Howto/scaladoc.html（他们说autoAPIMappings := true 和apiURL := Some(url("http://example.org/api/"))。）
与兰德尔的回答相同。这似乎只是指向原始文档的超链接，但它并没有在方法级别拉动 scaladoc。

标签： scala inheritance documentation sbt

【解决方案1】：

现在要容易得多。只需添加

autoAPIMappings := true

到您的 SBT 设置。（build.sbt 或 project/Build.scala）

使用 SBT 版本 0.13.5 和 Scala 2.11.7 进行测试，但它应该可以一直工作到 2.10.2，根据 SBT documentation

这应该适用于任何指定其文档所在位置的托管依赖项。如果它不适用于某些依赖项，请参阅other options。

【讨论】：

【解决方案2】：

这是我使用的 (SBT 0.13)：

scalacOptions in (Compile, doc) ++=
  Seq("-diagrams",
      "-diagrams-max-classes",
      "20",
      "-external-urls:java=http://docs.oracle.com/javase/6/docs/api/," +
      "scala=http://www.scala-lang.org/api/current/")

附录 1：

为了解决在覆盖方法时子类化标准库类并希望被覆盖方法的文档注释的问题，可以使用继承文档标签对成员进行注释：

/** @inheritdoc */
override def foo(bar: String): Int = bar.length

附录 2：

此功能的更现代形式记录在 this SBT 0.13 documentation page。

【讨论】：

应该是什么？我们在这里没有做任何特定于 Java 7 的事情，而且我们混合使用了各种 JVM……
我尝试将 Javadoc 用于我想要支持的最古老的 Java，以免意外使用新功能。
这似乎只是超链接类。它没有解决方法级别的文档。或者至少我不能让它在我的机器上工作。
@MarkCanlas：我不完全清楚您所说的“方法级别的地址文档”是什么意思。您是否覆盖标准库方法？如果是这样，您可以随时使用/** @inheritdoc */。
我会接受它所说的。没有要继承的文档注释。但是@inheritdoc 肯定有可能不会遍历-external-urls 指令