Backport "fix(#16610): warn ignored Scaladoc on multiple enum cases" to LTS (#20983)

Backports #19555 to the LTS branch.

PR submitted by the release tooling.
[skip ci]

Author: WojciechMazur

compiler/src/dotty/tools/dotc/config/ScalaSettings.scala

@@ -165,7 +165,7 @@ private sealed trait WarningSettings:
   val XfatalWarnings: Setting[Boolean] = BooleanSetting("-Werror", "Fail the compilation if there are any warnings.", aliases = List("-Xfatal-warnings"))
   val WvalueDiscard: Setting[Boolean] = BooleanSetting("-Wvalue-discard", "Warn when non-Unit expression results are unused.")
   val WNonUnitStatement = BooleanSetting("-Wnonunit-statement", "Warn when block statements are non-Unit expressions.")
-
+  val WenumCommentDiscard = BooleanSetting("-Wenum-comment-discard", "Warn when a comment ambiguously assigned to multiple enum cases is discarded.")
   val Wunused: Setting[List[ChoiceWithHelp[String]]] = MultiChoiceHelpSetting(
     name = "-Wunused",
     helpArg = "warning",

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

@@ -3902,6 +3902,14 @@ object Parsers {
         if (in.token == COMMA) {
           in.nextToken()
           val ids = commaSeparated(() => termIdent())
+          if ctx.settings.WenumCommentDiscard.value then
+            in.getDocComment(start).foreach: comm =>
+              warning(
+                em"""Ambiguous Scaladoc comment on multiple cases is ignored.
+                     |Remove the comment or make separate cases to add Scaladoc comments to each of them.""",
+                comm.span.start
+              )
+
           PatDef(mods1, id :: ids, TypeTree(), EmptyTree)
         }
         else {

tests/warn/i16610.check

@@ -0,0 +1,5 @@
+-- Warning: tests/warn/i16610.scala:12:2 -------------------------------------------------------------------------------
+12 |  /** // warn
+   |  ^
+   |  Ambiguous Scaladoc comment on multiple cases is ignored.
+   |  Remove the comment or make separate cases to add Scaladoc comments to each of them.

tests/warn/i16610.scala

@@ -0,0 +1,16 @@
+//> using options -Wenum-comment-discard
+/**
+ * Description of enum
+ */
+enum MyEnum {
+
+  /**
+   * Description of case 1
+   */
+  case MyCase1
+
+  /** // warn
+   * Description of case 2 and 3
+   */
+  case MyCase2, MyCase3
+}