Dottydoc: Keep documentation on package objects

The documentation for packages must be set on the package object. When
generating the docsite, dotty doc must then copy the documentation from
the package object node to the package node, so that it is shown in the
index for this package.

In dotty doc, the comments are added to the "doc AST" in the
`DocstringPhase`. Then, the doc for packages are copied from the
matching package objects in the `PackageObjectsPhase`.

This means that `PackageObjectsPhase` must be able to see the changes
done by `DocstringPhase`, and therefor they cannot be in the same
miniphase.

Author: Duhemm

doc-tool/src/dotty/tools/dottydoc/DocCompiler.scala

@@ -30,8 +30,8 @@ class DocCompiler extends Compiler {
     List(new DocImplicitsPhase) ::
     List(new DocASTPhase) ::
     List(DocMiniTransformations(new UsecasePhase,
-                                new DocstringPhase,
-                                new PackageObjectsPhase,
+                                new DocstringPhase)) ::
+    List(DocMiniTransformations(new PackageObjectsPhase,
                                 new LinkReturnTypes,
                                 new LinkParamListTypes,
                                 new LinkImplicitlyAddedTypes,

doc-tool/test/SimpleComments.scala

@@ -25,4 +25,17 @@ class TestSimpleComments extends DottyDocTest {
       assertEquals(traitCmt, "<p>Hello, world!</p>")
     }
   }
+
+  @Test def commentOnPackageObject = {
+    val source =
+      """
+      |/** Hello, world! */
+      |package object foobar { class A }
+      """.stripMargin
+
+    checkSource(source) { packages =>
+      val packageCmt = packages("foobar").comment.get.body
+      assertEquals("<p>Hello, world!</p>", packageCmt)
+    }
+  }
 }