Fix #4752: Support multiple @usecase sections

In the documentation, it is possible to have several `@usecase`
sections, which means that each of these section should be displayed as
a separate member in the documentation. So far, Dottydoc was only
considering the first `@usecase` section and was disregarding the
others.

This commit fixes that, and generates a new member for each of the
usecases.

Fixes #4752

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

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

doc-tool/test/UsecaseTest.scala

@@ -235,6 +235,34 @@ abstract class UsecaseBase extends DottyDocTest {
     }
   }
 
+  @Test def multipleUseCases: Unit = {
+    val source = new SourceFile(
+      name = "MultipleUseCases.scala",
+      """
+        |package scala
+        |
+        |trait Test {
+        |  /** A first method
+        |   *  @usecase def foo(x: Int): Int
+        |   *  @usecase def foo(x: Double): Double
+        |   */
+        |   def foo(x: String): Unit
+        |}
+      """.stripMargin
+    )
+
+    val className = "scala.Test"
+
+    check(className :: Nil, source :: Nil) { (ctx, packages) =>
+      packages("scala") match {
+        case PackageImpl(_, _, _, List(trt: Trait), _, _, _, _) =>
+          val List(foo0: Def, foo1: Def) = trt.members
+          assertEquals(TypeReference("Int", NoLink("Int", "scala.Int"), Nil), foo0.returnValue)
+          assertEquals(TypeReference("Double", NoLink("Double", "scala.Double"), Nil), foo1.returnValue)
+      }
+    }
+  }
+
   @Test def checkIterator =
     checkFiles("../scala2-library/src/library/scala/collection/Iterator.scala" :: Nil) { case _ =>
       // success if typer throws no errors! :)