Fix @inheritdoc on vals.

The field symbol doesn't override the superclass members;
it's the responsibility of the getter to do that.

I couldn't resist the urge to shoo away a gratuitous
`var` in a related method. Apologies for the bloated diff.

Fixes scala/bug#10621

src/compiler/scala/tools/nsc/ast/DocComments.scala

@@ -70,9 +70,10 @@ trait DocComments { self: Global =>
    *  the doc comment of the overridden version is copied instead.
    */
   def cookedDocComment(sym: Symbol, docStr: String = ""): String = cookedDocComments.getOrElseUpdate(sym, {
-    var ownComment = if (docStr.length == 0) docComments get sym map (_.template) getOrElse ""
-                       else DocComment(docStr).template
-    ownComment = replaceInheritDocToInheritdoc(ownComment)
+    val ownComment = replaceInheritDocToInheritdoc {
+      if (docStr.length == 0) docComments get sym map (_.template) getOrElse ""
+      else DocComment(docStr).template
+    }
 
     superComment(sym) match {
       case None =>
@@ -133,8 +134,12 @@ trait DocComments { self: Global =>
     mapFind(sym :: allInheritedOverriddenSymbols(sym))(docComments get _)
 
   /** The cooked doc comment of an overridden symbol */
-  protected def superComment(sym: Symbol): Option[String] =
-    allInheritedOverriddenSymbols(sym).iterator map (x => cookedDocComment(x)) find (_ != "")
+  protected def superComment(sym: Symbol): Option[String] = {
+    val getter: Symbol = sym.getter
+    allInheritedOverriddenSymbols(getter.orElse(sym)).iterator
+      .map(cookedDocComment(_))
+      .find(_ != "")
+  }
 
   private def mapFind[A, B](xs: Iterable[A])(f: A => Option[B]): Option[B] =
     xs collectFirst scala.Function.unlift(f)

test/scaladoc/resources/t10621.scala

@@ -0,0 +1,49 @@
+package test
+
+trait BaseTrait {
+  /** Some random integer. */
+  def someInt: Int
+
+  /** Another random integer. */
+  val anotherInt: Int
+
+  /** More integers, and mutable! */
+  var yetMoreInt: Int
+
+  /** The last integer. */
+  def theLastInt: Int
+}
+
+class BaseClass extends BaseTrait {
+  /** A doohickey. */
+  def doohickey: AnyRef
+
+  /** A whatzit. */
+  val whatzit: AnyRef
+
+  /** A fiddle. */
+  var fiddle: AnyRef
+
+  /** A surprise. */
+  def surprise: AnyRef
+}
+
+class Test extends BaseClass {
+  /**@inheritdoc */
+  val someInt    : Int = 7
+  /**@inheritdoc */
+  val anotherInt : Int = 77
+  /**@inheritdoc */
+  var yetMoreInt : Int = 777
+  /**@inheritdoc */
+  var theLastInt : Int = 7777
+
+  /**@inheritdoc */
+  val doohickey : AnyRef = new AnyRef
+  /**@inheritdoc */
+  val whatzit   : AnyRef = new AnyRef
+  /**@inheritdoc */
+  var fiddle    : AnyRef = new AnyRef
+  /**@inheritdoc */
+  var surprise  : AnyRef = new AnyRef
+}

test/scaladoc/run/t10621.check

@@ -0,0 +1,25 @@
+Some(Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(Some random integer), Text(.))))))))))
+Some(Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(Some random integer), Text(.))))))))))
+
+Some(Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(Another random integer), Text(.))))))))))
+Some(Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(Another random integer), Text(.))))))))))
+
+Some(Body(List(Paragraph(Chain(List(Summary(Text(More integers, and mutable!))))))))
+Some(Body(List(Paragraph(Chain(List(Summary(Text(More integers, and mutable!))))))))
+
+Some(Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(The last integer), Text(.))))))))))
+Some(Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(The last integer), Text(.))))))))))
+
+Some(Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(A doohickey), Text(.))))))))))
+Some(Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(A doohickey), Text(.))))))))))
+
+Some(Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(A whatzit), Text(.))))))))))
+Some(Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(A whatzit), Text(.))))))))))
+
+Some(Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(A fiddle), Text(.))))))))))
+Some(Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(A fiddle), Text(.))))))))))
+
+Some(Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(A surprise), Text(.))))))))))
+Some(Body(List(Paragraph(Chain(List(Summary(Chain(List(Text(A surprise), Text(.))))))))))
+
+Done.

test/scaladoc/run/t10621.scala

@@ -0,0 +1,31 @@
+import scala.tools.nsc.doc.model._
+import scala.tools.partest.ScaladocModelTest
+import language._
+
+object Test extends ScaladocModelTest {
+  override def resourceFile = "t10621.scala"
+  override def scaladocSettings = ""
+  def testModel(root: Package) = {
+    import access._
+
+    val pkg = root._package("test")
+    val baseTrait    = pkg._trait("BaseTrait")
+    val baseClass    = pkg._class("BaseClass")
+    val test         = pkg._class("Test")
+
+    def printBoth(supr: DocTemplateEntity, name: String) = {
+      println(supr._member(name).comment.map(_.body))
+      println(test._member(name).comment.map(_.body))
+      println()
+    }
+
+    printBoth(baseTrait, "someInt")
+    printBoth(baseTrait, "anotherInt")
+    printBoth(baseTrait, "yetMoreInt")
+    printBoth(baseTrait, "theLastInt")
+    printBoth(baseClass, "doohickey")
+    printBoth(baseClass, "whatzit")
+    printBoth(baseClass, "fiddle")
+    printBoth(baseClass, "surprise")
+  }
+}