From 94dd0bccbb68618bc668c6005316d6930ae26069 Mon Sep 17 00:00:00 2001 From: Felix Mulder Date: Tue, 2 Aug 2016 16:00:20 +0200 Subject: Get docstring from overriden symbol if not present on the overriding method --- .../dotty/tools/dottydoc/core/DocASTPhase.scala | 19 ++++++++------- .../dottydoc/model/comment/CommentExpander.scala | 14 +++++------ .../src/dotty/tools/dottydoc/model/parsers.scala | 27 ++++++++++++++++++---- 3 files changed, 38 insertions(+), 22 deletions(-) (limited to 'dottydoc') 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 -- cgit v1.2.3