More refactorings to comment cooking

Author: Duhemm

compiler/src/dotty/tools/dotc/core/Comments.scala

@@ -3,7 +3,7 @@ package dotc
 package core
 
 import ast.{ untpd, tpd }
-import Decorators._, Symbols._, Contexts._, Flags.EmptyFlags
+import Decorators._, Symbols._, Contexts._
 import util.SourceFile
 import util.Positions._
 import util.CommentParsing._
@@ -33,7 +33,7 @@ object Comments {
     def docstring(sym: Symbol): Option[Comment] = _docstrings.get(sym)
 
     def addDocstring(sym: Symbol, doc: Option[Comment]): Unit =
-      doc.map(d => _docstrings.update(sym, d))
+      doc.foreach(d => _docstrings.update(sym, d))
   }
 
   /**
@@ -112,29 +112,25 @@ object Comments {
     }
   }
 
-  abstract case class UseCase(code: String, codePos: Position) {
-    /** Set by typer */
-    var tpdCode: tpd.DefDef = _
-
-    def untpdCode: untpd.Tree
+  final case class UseCase(code: String, codePos: Position, untpdCode: untpd.Tree, tpdCode: Option[tpd.DefDef]) {
+    def typed(tpdCode: tpd.DefDef): UseCase = copy(tpdCode = Some(tpdCode))
   }
 
   object UseCase {
-    def apply(code: String, codePos: Position)(implicit ctx: Context) =
-      new UseCase(code, codePos) {
-        val untpdCode = {
-          val tree = new Parser(new SourceFile("<usecase>", code)).localDef(codePos.start)
-
-          tree match {
-            case tree: untpd.DefDef =>
-              val newName = ctx.freshNames.newName(tree.name, NameKinds.DocArtifactName)
-              untpd.DefDef(newName, tree.tparams, tree.vparamss, tree.tpt, tree.rhs)
-            case _ =>
-              ctx.error(ProperDefinitionNotFound(), codePos)
-              tree
-          }
+    def apply(code: String, codePos: Position)(implicit ctx: Context): UseCase = {
+      val tree = {
+        val tree = new Parser(new SourceFile("<usecase>", code)).localDef(codePos.start)
+        tree match {
+          case tree: untpd.DefDef =>
+            val newName = ctx.freshNames.newName(tree.name, NameKinds.DocArtifactName)
+            tree.copy(name = newName)
+          case _ =>
+            ctx.error(ProperDefinitionNotFound(), codePos)
+            tree
         }
       }
+      UseCase(code, codePos, tree, None)
+    }
   }
 
   /**

compiler/src/dotty/tools/dotc/typer/Docstrings.scala

@@ -4,7 +4,6 @@ package typer
 
 import core._
 import Contexts._, Symbols._, Decorators._, Comments._
-import util.Positions._
 import ast.tpd
 
 trait Docstrings { self: Typer =>
@@ -21,39 +20,51 @@ trait Docstrings { self: Typer =>
    * @param sym   The symbol for which the comment is being cooked.
    * @param owner The class for which comments are being cooked.
    */
-  def cookComment(sym: Symbol, owner: Symbol)(implicit ctx: Context): Unit = {
-    for {
-      docbase <- ctx.docCtx
-      comment <- docbase.docstring(sym).filter(!_.isExpanded)
-    } {
-      expandParentDocs(sym)
-      docbase.docstring(sym).get.usecases.foreach { usecase =>
-        enterSymbol(createSymbol(usecase.untpdCode))
-        typedStats(usecase.untpdCode :: Nil, owner) match {
-          case List(df: tpd.DefDef) => usecase.tpdCode = df
-          case _ => ctx.error("`@usecase` was not a valid definition", usecase.codePos)
-        }
-      }
+  def cookComment(sym: Symbol, owner: Symbol)(implicit ctx: Context): Option[Comment] = {
+    ctx.docCtx.flatMap { docCtx =>
+      expand(sym, owner)(ctx, docCtx)
     }
   }
 
-  private def expandParentDocs(sym: Symbol)(implicit ctx: Context): Unit =
-    ctx.docCtx.foreach { docCtx =>
-      docCtx.docstring(sym).foreach { cmt =>
-        def expandDoc(owner: Symbol): Unit = if (!cmt.isExpanded) {
-          val tplExp = docCtx.templateExpander
-          tplExp.defineVariables(sym)
-
-          val newCmt = cmt
-            .expand(tplExp.expandedDocComment(sym, owner, _))
+  private def expand(sym: Symbol, owner: Symbol)(implicit ctx: Context, docCtx: ContextDocstrings): Option[Comment] = {
+    docCtx.docstring(sym).flatMap {
+      case cmt if cmt.isExpanded =>
+        Some(cmt)
+      case _ =>
+        expandComment(sym).map { expanded =>
+          val typedUsecases = expanded.usecases.map { usecase =>
+            enterSymbol(createSymbol(usecase.untpdCode))
+            typedStats(usecase.untpdCode :: Nil, owner) match {
+              case List(df: tpd.DefDef) =>
+                usecase.typed(df)
+              case _ =>
+                ctx.error("`@usecase` was not a valid definition", usecase.codePos)
+                usecase
+            }
+          }
 
-          docCtx.addDocstring(sym, Some(newCmt))
+          val commentWithUsecases = expanded.copy(usecases = typedUsecases)
+          docCtx.addDocstring(sym, Some(commentWithUsecases))
+          commentWithUsecases
         }
+    }
+  }
 
-        if (sym ne NoSymbol) {
-          expandParentDocs(sym.owner)
-          expandDoc(sym.owner)
-        }
-      }
+  private def expandComment(sym: Symbol, owner: Symbol, comment: Comment)(implicit ctx: Context, docCtx: ContextDocstrings): Comment = {
+    val tplExp = docCtx.templateExpander
+    tplExp.defineVariables(sym)
+    val newComment = comment.expand(tplExp.expandedDocComment(sym, owner, _))
+    docCtx.addDocstring(sym, Some(newComment))
+    newComment
+  }
+
+  private def expandComment(sym: Symbol)(implicit ctx: Context, docCtx: ContextDocstrings): Option[Comment] = {
+    if (sym eq NoSymbol) None
+    else {
+      for {
+        cmt <- docCtx.docstring(sym) if !cmt.isExpanded
+        _ = expandComment(sym.owner)
+      } yield expandComment(sym, sym.owner, cmt)
     }
+  }
 }

doc-tool/src/dotty/tools/dottydoc/core/UsecasePhase.scala

@@ -29,7 +29,7 @@ class UsecasePhase extends DocMiniPhase {
   override def transformDef(implicit ctx: Context) = { case df: DefImpl =>
     val defdefs =
       ctx.docbase.docstring(df.symbol)
-        .map(_.usecases.map(_.tpdCode))
+        .map(_.usecases.flatMap(_.tpdCode))
         .getOrElse(Nil)
 
     if (defdefs.isEmpty) df :: Nil