How do I inherit Scaladoc from Scala's standard library?

Question

If I understand correctly, the Scaladoc of a method should automatically inherit the Scaladoc of the parent method it overrides. This seems to hold true for a local set of classes, but not when extending from Scala's standard library (and presumably any external dependency?).

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

class DocumentedChild extends LocalParent

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

Is there a way to inherit the Scaladoc? Or am I doing something wrong?

Also, I'm using sbt doc, so not scaladoc directly.

Answer 1

Here's what I use (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/")

Addendum 1:

To address the issue of subclassing standard library classes while overriding methods and wanting the overridden method's documentation comment, members can be commented with the inherit documentation tag:

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

Addendum 2:

The more modern form of this functionality is documented on this SBT 0.13 documentation page.

Answer 2

It's much easier nowadays. Simply add

autoAPIMappings := true

to your SBT settings. (build.sbt or project/Build.scala)

Tested with SBT version 0.13.5 and Scala 2.11.7, but it should work all the way back to 2.10.2, per the SBT documentation

That should work for any managed dependencies that specify where their documentation lives. If it's not working for some dependencies, see the other options.