Get docstring from overriden symbol if not present on the overriding method

3 files changed, 38 insertions, 22 deletions

diff --git a/dottydoc/jvm/src/dotty/tools/dottydoc/core/DocASTPhase.scala b/dottydoc/jvm/src/dotty/tools/dottydoc/core/DocASTPhase.scala
index 19ed0ce17..40e778059 100644
--- a/dottydoc/jvm/src/dotty/tools/dottydoc/core/DocASTPhase.scala
+++ b/dottydoc/jvm/src/dotty/tools/dottydoc/core/DocASTPhase.scala
@@ -8,7 +8,7 @@ import dotc.CompilationUnit
 import dotc.config.Printers.dottydoc
 import dotc.core.Contexts.Context
 import dotc.core.Phases.Phase
-import dotc.core.Symbols.Symbol
+import dotc.core.Symbols.{ Symbol, NoSymbol }
 
 class DocASTPhase extends Phase {
   import model._
@@ -26,18 +26,18 @@ class DocASTPhase extends Phase {
   private[this] val commentParser = new WikiParser
 
   /** Saves the commentParser function for later evaluation, for when the AST has been filled */
-  def track(symbol: Symbol, ctx: Context)(op: => Entity) = {
+  def track(symbol: Symbol, ctx: Context, parent: Symbol = NoSymbol)(op: => Entity) = {
     val entity = op
 
     if (entity != NonEntity)
-      commentParser += (entity, symbol, ctx)
+      commentParser += (entity, symbol, parent, ctx)
 
     entity
   }
 
   /** Build documentation hierarchy from existing tree */
   def collect(tree: Tree, prev: List[String] = Nil)(implicit ctx: Context): Entity = track(tree.symbol, ctx) {
-    val implicitlyAddedMembers = ctx.docbase.defs(tree.symbol)
+    val implicitConversions = ctx.docbase.defs(tree.symbol)
 
     def collectList(xs: List[Tree], ps: List[String])(implicit ctx: Context): List[Entity] =
       xs.map(collect(_, ps)).filter(_ != NonEntity)
@@ -45,25 +45,24 @@ class DocASTPhase extends Phase {
     def collectEntityMembers(xs: List[Tree], ps: List[String])(implicit ctx: Context) =
       collectList(xs, ps).asInstanceOf[List[Entity with Members]]
 
-    /** TODO: should be a set, not a uniqued list */
     def collectMembers(tree: Tree, ps: List[String] = prev)(implicit ctx: Context): List[Entity] = {
       val defs = (tree match {
         case t: Template => collectList(t.body, ps)
         case _ => Nil
-      }) ++ implicitlyAddedMembers.flatMap(addedFromSymbol)
+      })
 
-      defs
+      defs ++ implicitConversions.flatMap(membersFromSymbol)
     }
 
-    def addedFromSymbol(sym: Symbol): List[Entity] = {
+    def membersFromSymbol(sym: Symbol): List[Entity] = {
       val defs = sym.info.bounds.hi.membersBasedOnFlags(Flags.Method, Flags.Synthetic | Flags.Private).map { meth =>
-        track(meth.symbol, ctx) {
+        track(meth.symbol, ctx, tree.symbol) {
           DefImpl(meth.symbol.name.decode.toString, Nil, path(meth.symbol), returnType(meth.info), typeParams(meth.symbol), paramLists(meth.info))
         }
       }.toList
 
       val vals = sym.info.fields.filterNot(_.symbol.is(Flags.Private | Flags.Synthetic)).map { value =>
-        track(value.symbol, ctx) {
+        track(value.symbol, ctx, tree.symbol) {
           ValImpl(value.symbol.name.decode.toString, Nil, path(value.symbol), returnType(value.info))
         }
       }
diff --git a/dottydoc/jvm/src/dotty/tools/dottydoc/model/comment/CommentExpander.scala b/dottydoc/jvm/src/dotty/tools/dottydoc/model/comment/CommentExpander.scala
index b5f6b903a..32a0d8128 100644
--- a/dottydoc/jvm/src/dotty/tools/dottydoc/model/comment/CommentExpander.scala
+++ b/dottydoc/jvm/src/dotty/tools/dottydoc/model/comment/CommentExpander.scala
@@ -20,9 +20,10 @@ import scala.collection.mutable
 trait CommentExpander {
   import CommentUtils._
 
-  def expand(sym: Symbol)(implicit ctx: Context): String = {
-    defineVariables(sym)
-    expandedDocComment(sym, sym)
+  def expand(sym: Symbol, site: Symbol)(implicit ctx: Context): String = {
+    val parent = if (site != NoSymbol) site else sym
+    defineVariables(parent)
+    expandedDocComment(sym, parent)
   }
 
   /** The cooked doc comment of symbol `sym` after variable expansion, or "" if missing.
@@ -35,9 +36,9 @@ trait CommentExpander {
    */
   def expandedDocComment(sym: Symbol, site: Symbol, docStr: String = "")(implicit ctx: Context): String = {
     // when parsing a top level class or module, use the (module-)class itself to look up variable definitions
-    val site1 = if ((sym.is(Flags.Module) || sym.isClass) && site.is(Flags.Package)) sym
-                else site
-    expandVariables(cookedDocComment(sym, docStr), sym, site1)
+    val parent = if ((sym.is(Flags.Module) || sym.isClass) && site.is(Flags.Package)) sym
+                 else site
+    expandVariables(cookedDocComment(sym, docStr), sym, parent)
   }
 
   private def template(raw: String): String = {
@@ -74,7 +75,6 @@ trait CommentExpander {
    *  If a symbol does not have a doc comment but some overridden version of it does,
    *  the doc comment of the overridden version is copied instead.
    */
-
   def cookedDocComment(sym: Symbol, docStr: String = "")(implicit ctx: Context): String = cookedDocComments.getOrElseUpdate(sym, {
     var ownComment =
       if (docStr.length == 0) ctx.docbase.docstring(sym).map(c => template(c.chrs)).getOrElse("")
diff --git a/dottydoc/jvm/src/dotty/tools/dottydoc/model/parsers.scala b/dottydoc/jvm/src/dotty/tools/dottydoc/model/parsers.scala
index e00fd1324..afd1cf982 100644
--- a/dottydoc/jvm/src/dotty/tools/dottydoc/model/parsers.scala
+++ b/dottydoc/jvm/src/dotty/tools/dottydoc/model/parsers.scala
@@ -22,9 +22,9 @@ object parsers {
      * The idea here is to use this fact to create `Future[Seq[(String, Option[Comment]]]`
      * which can then be awaited near the end of the run - before the pickling.
      */
-    def parseHtml(sym: Symbol, entity: Entity, packages: Map[String, Package])(implicit ctx: Context): (String, Option[Comment]) = {
+    def parseHtml(sym: Symbol, parent: Symbol, entity: Entity, packages: Map[String, Package])(implicit ctx: Context): (String, Option[Comment]) = {
       val cmt = ctx.docbase.docstring(sym).map { d =>
-        val expanded = expand(sym)
+        val expanded = expand(sym, parent)
         val body = parse(entity, packages, clean(expanded), expanded, d.pos)
         val summary = body.summary.map(_.toHtml(entity)).getOrElse("")
          body.toHtml(entity) match {
@@ -37,17 +37,34 @@ object parsers {
     }
 
 
-    def add(entity: Entity, symbol: Symbol, ctx: Context): Unit = {
+    def add(entity: Entity, symbol: Symbol, parent: Symbol, ctx: Context): Unit = {
       val commentParser = { (entity: Entity, packs: Map[String, Package]) =>
-        parseHtml(symbol, entity, packs)(ctx)._2
+        parseHtml(symbol, parent, entity, packs)(ctx)._2
       }
 
+      /** TODO: this if statement searches for doc comments in parent
+       *  definitions if one is not defined for the current symbol.
+       *
+       *  It might be a good idea to factor this out of the WikiParser - since
+       *  it mutates the state of docbase sort of silently.
+       */
+      implicit val implCtx = ctx
+      if (!ctx.docbase.docstring(symbol).isDefined) {
+        val parentCmt =
+          symbol.extendedOverriddenSymbols
+          .find(ctx.docbase.docstring(_).isDefined)
+          .flatMap(p => ctx.docbase.docstring(p))
+
+        ctx.docbase.addDocstring(symbol, parentCmt)
+      }
+
+
       val path = entity.path.mkString(".")
       if (!commentCache.contains(path) || ctx.docbase.docstring(symbol).isDefined)
         commentCache = commentCache + (path -> commentParser)
     }
 
-    def +=(entity: Entity, symbol: Symbol, ctx: Context) = add(entity, symbol, ctx)
+    def +=(entity: Entity, symbol: Symbol, parent: Symbol, ctx: Context) = add(entity, symbol, parent, ctx)
 
     def size: Int = commentCache.size