Add docstring support for types, vals, vars and defs

Author: felixmulder

src/dotty/tools/dotc/parsing/Parsers.scala

@@ -1750,13 +1750,13 @@ object Parsers {
      */
     def defOrDcl(start: Int, mods: Modifiers): Tree = in.token match {
       case VAL =>
-        patDefOrDcl(posMods(start, mods))
+        patDefOrDcl(posMods(start, mods), in.getDocString(start))
       case VAR =>
-        patDefOrDcl(posMods(start, addFlag(mods, Mutable)))
+        patDefOrDcl(posMods(start, addFlag(mods, Mutable)), in.getDocString(start))
       case DEF =>
-        defDefOrDcl(posMods(start, mods))
+        defDefOrDcl(posMods(start, mods), in.getDocString(start))
       case TYPE =>
-        typeDefOrDcl(posMods(start, mods))
+        typeDefOrDcl(posMods(start, mods), in.getDocString(start))
       case _ =>
         tmplDef(start, mods)
     }
@@ -1766,7 +1766,7 @@ object Parsers {
      *  ValDcl ::= Id {`,' Id} `:' Type
      *  VarDcl ::= Id {`,' Id} `:' Type
      */
-    def patDefOrDcl(mods: Modifiers): Tree = {
+    def patDefOrDcl(mods: Modifiers, docstring: Option[String] = None): Tree = {
       val lhs = commaSeparated(pattern2)
       val tpt = typedOpt()
       val rhs =
@@ -1780,8 +1780,10 @@ object Parsers {
           }
         } else EmptyTree
       lhs match {
-        case (id @ Ident(name: TermName)) :: Nil => cpy.ValDef(id)(name, tpt, rhs).withMods(mods)
-        case _ => PatDef(mods, lhs, tpt, rhs)
+        case (id @ Ident(name: TermName)) :: Nil =>
+          cpy.ValDef(id)(name, tpt, rhs).withMods(mods).withComment(docstring)
+        case _ =>
+          PatDef(mods, lhs, tpt, rhs)
       }
     }
 
@@ -1790,7 +1792,7 @@ object Parsers {
      *  DefDcl ::= DefSig `:' Type
      *  DefSig ::= id [DefTypeParamClause] ParamClauses
      */
-    def defDefOrDcl(mods: Modifiers): Tree = atPos(tokenRange) {
+    def defDefOrDcl(mods: Modifiers, docstring: Option[String] = None): Tree = atPos(tokenRange) {
       def scala2ProcedureSyntax(resultTypeStr: String) = {
         val toInsert =
           if (in.token == LBRACE) s"$resultTypeStr ="
@@ -1831,7 +1833,7 @@ object Parsers {
             accept(EQUALS)
             expr()
           }
-        DefDef(name, tparams, vparamss, tpt, rhs).withMods(mods1)
+        DefDef(name, tparams, vparamss, tpt, rhs).withMods(mods1).withComment(docstring)
       }
     }
 
@@ -1865,15 +1867,15 @@ object Parsers {
     /** TypeDef ::= type Id [TypeParamClause] `=' Type
      *  TypeDcl ::= type Id [TypeParamClause] TypeBounds
      */
-    def typeDefOrDcl(mods: Modifiers): Tree = {
+    def typeDefOrDcl(mods: Modifiers, docstring: Option[String] = None): Tree = {
       newLinesOpt()
       atPos(tokenRange) {
         val name = ident().toTypeName
         val tparams = typeParamClauseOpt(ParamOwner.Type)
         in.token match {
           case EQUALS =>
             in.nextToken()
-            TypeDef(name, tparams, typ()).withMods(mods)
+            TypeDef(name, tparams, typ()).withMods(mods).withComment(docstring)
           case SUPERTYPE | SUBTYPE | SEMI | NEWLINE | NEWLINES | COMMA | RBRACE | EOF =>
             TypeDef(name, tparams, typeBounds()).withMods(mods)
           case _ =>

test/test/DottyDocTests.scala

@@ -42,18 +42,22 @@ trait DottyDocTest extends DottyTest { self =>
       assert(false, s"""No docstring found, expected: "$expected"""")
   }
 
-  def run(): Unit = {
+  def run(): Unit = try {
     val c = compiler(assertion)
     c.rootContext(ctx)
     c.newRun.compile(source)
     println(s"${self.getClass.getSimpleName.split("\\$").last} passed")
+  } catch { case e: Throwable =>
+    Console.err.println(s"${self.getClass.getSimpleName.split("\\$").last} failed")
+    throw e
   }
 }
 
 /** Add tests to the `tests` sequence */
 object DottyDocTests extends DottyTest {
   private[this] val tests = Seq(
     NoComment,
+
     SingleClassInPackage,
     MultipleOpenedOnSingleClassInPackage,
     MultipleClassesInPackage,
@@ -67,13 +71,18 @@ object DottyDocTests extends DottyTest {
     ObjectsNestedClass,
     PackageObject,
     MultipleDocStringsBeforeEntity,
-    MultipleDocStringsBeforeAndAfter
+    MultipleDocStringsBeforeAndAfter,
+
+    ValuesWithDocString,
+    VarsWithDocString,
+    DefsWithDocString,
+    TypesWithDocString
   )
 
   def main(args: Array[String]): Unit = {
-    println("------------ Testing DottyDoc  ------------")
+    println(s"-------------- Testing DottyDoc (${tests.length} tests) --------------")
     tests.foreach(_.run)
-    println("--------- DottyDoc tests passed! ----------")
+    println("--------------- DottyDoc tests passed! -------------------")
   }
 }
 
@@ -371,3 +380,127 @@ case object MultipleDocStringsBeforeAndAfter extends DottyDocTest {
   }
 
 }
+
+case object ValuesWithDocString extends DottyDocTest {
+  override val source =
+    """
+    |object Object {
+    |  /** val1 */
+    |  val val1 = 1
+    |
+    |  /** val2 */
+    |  val val2: Int = 2
+    |  /** bogus docstring */
+    |
+    |  /** bogus docstring */
+    |  /** val3 */
+    |  val val3: List[Int] = 1 :: 2 :: 3 :: Nil
+    |}
+    """.stripMargin
+
+  import dotty.tools.dotc.ast.untpd._
+  override def assertion = {
+    case PackageDef(_, Seq(o: ModuleDef)) =>
+      o.impl.body match {
+        case (v1: MemberDef) :: (v2: MemberDef) :: (v3: MemberDef) :: Nil => {
+          checkDocString(v1.rawComment, "/** val1 */")
+          checkDocString(v2.rawComment, "/** val2 */")
+          checkDocString(v3.rawComment, "/** val3 */")
+        }
+        case _ => assert(false, "Incorrect structure inside object")
+      }
+  }
+}
+
+case object VarsWithDocString extends DottyDocTest {
+  override val source =
+    """
+    |object Object {
+    |  /** var1 */
+    |  var var1 = 1
+    |
+    |  /** var2 */
+    |  var var2: Int = 2
+    |  /** bogus docstring */
+    |
+    |  /** bogus docstring */
+    |  /** var3 */
+    |  var var3: List[Int] = 1 :: 2 :: 3 :: Nil
+    |}
+    """.stripMargin
+
+  import dotty.tools.dotc.ast.untpd._
+  override def assertion = {
+    case PackageDef(_, Seq(o: ModuleDef)) =>
+      o.impl.body match {
+        case (v1: MemberDef) :: (v2: MemberDef) :: (v3: MemberDef) :: Nil => {
+          checkDocString(v1.rawComment, "/** var1 */")
+          checkDocString(v2.rawComment, "/** var2 */")
+          checkDocString(v3.rawComment, "/** var3 */")
+        }
+        case _ => assert(false, "Incorrect structure inside object")
+      }
+  }
+}
+
+case object DefsWithDocString extends DottyDocTest {
+  override val source =
+    """
+    |object Object {
+    |  /** def1 */
+    |  def def1 = 1
+    |
+    |  /** def2 */
+    |  def def2: Int = 2
+    |  /** bogus docstring */
+    |
+    |  /** bogus docstring */
+    |  /** def3 */
+    |  def def3: List[Int] = 1 :: 2 :: 3 :: Nil
+    |}
+    """.stripMargin
+
+  import dotty.tools.dotc.ast.untpd._
+  override def assertion = {
+    case PackageDef(_, Seq(o: ModuleDef)) =>
+      o.impl.body match {
+        case (v1: MemberDef) :: (v2: MemberDef) :: (v3: MemberDef) :: Nil => {
+          checkDocString(v1.rawComment, "/** def1 */")
+          checkDocString(v2.rawComment, "/** def2 */")
+          checkDocString(v3.rawComment, "/** def3 */")
+        }
+        case _ => assert(false, "Incorrect structure inside object")
+      }
+  }
+}
+
+case object TypesWithDocString extends DottyDocTest {
+  override val source =
+    """
+    |object Object {
+    |  /** type1 */
+    |  type T1 = Int
+    |
+    |  /** type2 */
+    |  type T2 = String
+    |  /** bogus docstring */
+    |
+    |  /** bogus docstring */
+    |  /** type3 */
+    |  type T3 = T2
+    |}
+    """.stripMargin
+
+  import dotty.tools.dotc.ast.untpd._
+  override def assertion = {
+    case PackageDef(_, Seq(o: ModuleDef)) =>
+      o.impl.body match {
+        case (v1: MemberDef) :: (v2: MemberDef) :: (v3: MemberDef) :: Nil => {
+          checkDocString(v1.rawComment, "/** type1 */")
+          checkDocString(v2.rawComment, "/** type2 */")
+          checkDocString(v3.rawComment, "/** type3 */")
+        }
+        case _ => assert(false, "Incorrect structure inside object")
+      }
+  }
+}