From 76ee4121c2a795cbf6bbfe4fbc3065182c4110a0 Mon Sep 17 00:00:00 2001 From: i10416 Date: Sun, 28 Jan 2024 22:07:24 +0900 Subject: [PATCH 1/2] fix(#16610): warn Scaladoc on multiple cases 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. --- .../src/dotty/tools/dotc/parsing/Parsers.scala | 7 +++++++ tests/warn/i16610.check | 5 +++++ tests/warn/i16610.scala | 15 +++++++++++++++ 3 files changed, 27 insertions(+) create mode 100644 tests/warn/i16610.check create mode 100644 tests/warn/i16610.scala diff --git a/compiler/src/dotty/tools/dotc/parsing/Parsers.scala b/compiler/src/dotty/tools/dotc/parsing/Parsers.scala index 18294a28b4a1..f5cb3f0a895b 100644 --- a/compiler/src/dotty/tools/dotc/parsing/Parsers.scala +++ b/compiler/src/dotty/tools/dotc/parsing/Parsers.scala @@ -3955,6 +3955,13 @@ object Parsers { if (in.token == COMMA) { in.nextToken() val ids = commaSeparated(() => termIdent()) + 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..119ec5ab487a --- /dev/null +++ b/tests/warn/i16610.check @@ -0,0 +1,5 @@ +-- Warning: tests/warn/i16610.scala:11:2 ------------------------------------------------------------------------------- +11 | /** // 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..54a8de4c3e86 --- /dev/null +++ b/tests/warn/i16610.scala @@ -0,0 +1,15 @@ +/** + * 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 From aeccd2c87db1a4d7524ddc1b3922d8649fb40fb0 Mon Sep 17 00:00:00 2001 From: i10416 Date: Sun, 10 Mar 2024 15:28:38 +0900 Subject: [PATCH 2/2] enhance(lint): warn ambiguous enum comments only when option is provided > to add new warning without flag we need to wait for 3.5.0. See https://github.com/scala/scala3/pull/19555#issuecomment-1963882107 --- .../src/dotty/tools/dotc/config/ScalaSettings.scala | 1 + compiler/src/dotty/tools/dotc/parsing/Parsers.scala | 13 +++++++------ tests/warn/i16610.check | 4 ++-- tests/warn/i16610.scala | 1 + 4 files changed, 11 insertions(+), 8 deletions(-) diff --git a/compiler/src/dotty/tools/dotc/config/ScalaSettings.scala b/compiler/src/dotty/tools/dotc/config/ScalaSettings.scala index 07efc18a772b..1129d6bbe0e3 100644 --- a/compiler/src/dotty/tools/dotc/config/ScalaSettings.scala +++ b/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( diff --git a/compiler/src/dotty/tools/dotc/parsing/Parsers.scala b/compiler/src/dotty/tools/dotc/parsing/Parsers.scala index 24d5bcca40d0..4880c7704f0e 100644 --- a/compiler/src/dotty/tools/dotc/parsing/Parsers.scala +++ b/compiler/src/dotty/tools/dotc/parsing/Parsers.scala @@ -3997,12 +3997,13 @@ object Parsers { if (in.token == COMMA) { in.nextToken() val ids = commaSeparated(() => termIdent()) - 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 - ) + 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) } diff --git a/tests/warn/i16610.check b/tests/warn/i16610.check index 119ec5ab487a..4eb69b5c551a 100644 --- a/tests/warn/i16610.check +++ b/tests/warn/i16610.check @@ -1,5 +1,5 @@ --- Warning: tests/warn/i16610.scala:11:2 ------------------------------------------------------------------------------- -11 | /** // warn +-- 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 index 54a8de4c3e86..7657d23b7fd2 100644 --- a/tests/warn/i16610.scala +++ b/tests/warn/i16610.scala @@ -1,3 +1,4 @@ +//> using options -Wenum-comment-discard /** * Description of enum */