fix(#16610): warn ignored Scaladoc on multiple enum cases (#19555)

close #16610 

Before this commit, the compiler ignored Scaladoc comment on multiple
enum cases without warning.

This is partly expected because the case to which the doc is attached is
ambiguous, but we should at least warn users that the comment is ignored
by compiler due to ambiguity and they should take an action if they want
the doc to be displayed.

Author: i10416

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

@@ -168,6 +168,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 WimplausiblePatterns = BooleanSetting("-Wimplausible-patterns", "Warn if comparison with a pattern value looks like it might always fail.")
   val WunstableInlineAccessors = BooleanSetting("-WunstableInlineAccessors", "Warn an inline methods has references to non-stable binary APIs.")
   val Wunused: Setting[List[ChoiceWithHelp[String]]] = MultiChoiceHelpSetting(

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

@@ -3997,6 +3997,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
+}