From 98120654f8e8abf2b56c6298e62beb87a1a58f44 Mon Sep 17 00:00:00 2001
From: Wojciech Mazur <wmazur@virtuslab.com>
Date: Wed, 3 Jul 2024 00:54:06 +0200
Subject: [PATCH] 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.
[Cherry-picked 11a6f0a9e853a9b0cca14bcb02d9d93f0f9ae57b][modified]
---
 .../dotty/tools/dotc/config/ScalaSettings.scala  |  2 +-
 .../src/dotty/tools/dotc/parsing/Parsers.scala   |  8 ++++++++
 tests/warn/i16610.check                          |  5 +++++
 tests/warn/i16610.scala                          | 16 ++++++++++++++++
 4 files changed, 30 insertions(+), 1 deletion(-)
 create mode 100644 tests/warn/i16610.check
 create mode 100644 tests/warn/i16610.scala

diff --git a/compiler/src/dotty/tools/dotc/config/ScalaSettings.scala b/compiler/src/dotty/tools/dotc/config/ScalaSettings.scala
index 5b72f614f8df..e58cff7eb130 100644
--- a/compiler/src/dotty/tools/dotc/config/ScalaSettings.scala
+++ b/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",
diff --git a/compiler/src/dotty/tools/dotc/parsing/Parsers.scala b/compiler/src/dotty/tools/dotc/parsing/Parsers.scala
index 9cdb0750bb94..8eb5ce8aee8d 100644
--- a/compiler/src/dotty/tools/dotc/parsing/Parsers.scala
+++ b/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 {
diff --git a/tests/warn/i16610.check b/tests/warn/i16610.check
new file mode 100644
index 000000000000..4eb69b5c551a
--- /dev/null
+++ b/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.
diff --git a/tests/warn/i16610.scala b/tests/warn/i16610.scala
new file mode 100644
index 000000000000..7657d23b7fd2
--- /dev/null
+++ b/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
+}
\ No newline at end of file