7

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.

Mark Canlas
  • 9,385
  • 5
  • 41
  • 63
  • 1
    Take a look at the documentation wherein they specify how to handle importing the docs from external dependencies: http://www.scala-sbt.org/0.13.2/docs/Howto/scaladoc.html (they say `autoAPIMappings := true` and `apiURL := Some(url("http://example.org/api/"))`.) – wheaties May 20 '14 at 17:24
  • Same as Randall's answer. This seems to only hyperlink to the original documentation, but it does not pull scaladoc through at the method level. – Mark Canlas May 20 '14 at 20:46

2 Answers2

7

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.

BenMorel
  • 34,448
  • 50
  • 182
  • 322
Randall Schulz
  • 26,420
  • 4
  • 61
  • 81
  • What should it be? We're not doing anything Java 7-specific here and we have a mix of JVMs in use… – Randall Schulz May 20 '14 at 18:11
  • I try to use the Javadoc for the oldest Java that I want to support so I don't accidentally use new features. – Rex Kerr May 20 '14 at 19:22
  • This seems to only hyperlink classes. It doesn't address documentation at the method level. Or at least I can't get it to work on my machine. – Mark Canlas May 20 '14 at 20:44
  • @MarkCanlas: I'm not entirely clear what you mean by "address documentation at the method level." Are you overriding standard library methods? If so, you can always use `/** @inheritdoc */`. – Randall Schulz May 20 '14 at 23:30
  • We're not on the same page or I'm doing something wrong. I get `The comment for method next contains @inheritdoc, but no parent comment is available to inherit from.`. If you `sbt doc` the code that I wrote above with whatever settings, do you see the Scaladoc for each method inherited from Iterator? – Mark Canlas May 21 '14 at 01:42
  • 1
    I'd take it for what it says. There's no documentation comment to inherit. But it's surely possible that `@inheritdoc` does not traverse a `-external-urls` directive – Randall Schulz May 21 '14 at 04:16
  • @som-snytt: I really did mean what I said: We're not doing anything Java 7-specific and we really do have a mixture of JVM 6 and JVM 7 in our world. There is no Java / JVM 8 anything here. After all it's barely released and offers nothing to a Scala shop… – Randall Schulz May 21 '14 at 15:15
  • Note `-external-urls` is deprecated in 2.10, absent in 2.11. – som-snytt May 21 '14 at 16:03
  • It will do links `[[scala.Function1]]` only. It actually emits the inheritdoc error in the doc output: `I am a scala.Function1. `. – som-snytt May 21 '14 at 16:36
  • Looks like inheritdoc is handled by compiler, not scaladoc operating on artifacts. – som-snytt May 21 '14 at 16:53
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.

aij
  • 5,903
  • 3
  • 37
  • 41