Enhance help message for language flag (#20247)

Fix #20083: Enhance help message for language features by displaying all available choises and notes

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

@@ -53,7 +53,7 @@ trait CliCommand:
   end distill
 
   /** Creates a help message for a subset of options based on cond */
-  protected def availableOptionsMsg(p: Setting[?] => Boolean)(using settings: ConcreteSettings)(using SettingsState): String =
+  protected def availableOptionsMsg(p: Setting[?] => Boolean, showArgFileMsg: Boolean = true)(using settings: ConcreteSettings)(using SettingsState): String =
     // result is (Option Name, descrption\ndefault: value\nchoices: x, y, z
     def help(s: Setting[?]): (String, String) =
       // For now, skip the default values that do not make sense for the end user, such as 'false' for the version command.
@@ -68,7 +68,10 @@ trait CliCommand:
     val ss = settings.allSettings.filter(p).toList.sortBy(_.name)
     val formatter = Columnator("", "", maxField = 30)
     val fresh = ContextBase().initialCtx.fresh.setSettings(summon[SettingsState])
-    formatter(List(ss.map(help) :+ ("@<file>", "A text file containing compiler arguments (options and source files).")))(using fresh)
+    var msg = ss.map(help)
+    if showArgFileMsg then
+      msg = msg :+ ("@<file>", "A text file containing compiler arguments (options and source files).")
+    formatter(List(msg))(using fresh)
   end availableOptionsMsg
 
   protected def shortUsage: String = s"Usage: $cmdName <options> <source files>"

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

@@ -9,7 +9,7 @@ abstract class CompilerCommand extends CliCommand:
 
   final def helpMsg(using settings: ConcreteSettings)(using SettingsState, Context): String =
     settings.allSettings.find(isHelping) match
-      case Some(s) => s.description
+      case Some(s) => availableOptionsMsg(_ == s, showArgFileMsg = false)
       case _ =>
         if (settings.help.value) usageMessage
         else if (settings.Vhelp.value) vusageMessage

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

@@ -11,6 +11,7 @@ import SourceVersion.*
 import reporting.Message
 import NameKinds.QualifiedName
 import Annotations.ExperimentalAnnotation
+import Settings.Setting.ChoiceWithHelp
 
 object Feature:
 
@@ -42,6 +43,35 @@ object Feature:
       .map(sym => experimental(sym.name))
       .filterNot(_ == captureChecking) // TODO is this correct?
 
+  val values = List(
+    (nme.help, "Display all available features"),
+    (nme.noAutoTupling, "Disable automatic tupling"),
+    (nme.dynamics, "Allow direct or indirect subclasses of scala.Dynamic"),
+    (nme.unsafeNulls, "Enable unsafe nulls for explicit nulls"),
+    (nme.postfixOps, "Allow postfix operators (not recommended)"),
+    (nme.strictEquality, "Enable strict equality (disable canEqualAny)"),
+    (nme.implicitConversions, "Allow implicit conversions without warnings"),
+    (nme.adhocExtensions, "Allow ad-hoc extension methods"),
+    (namedTypeArguments, "Allow named type arguments"),
+    (genericNumberLiterals, "Allow generic number literals"),
+    (scala2macros, "Allow Scala 2 macros"),
+    (dependent, "Allow dependent method types"),
+    (erasedDefinitions, "Allow erased definitions"),
+    (symbolLiterals, "Allow symbol literals"),
+    (fewerBraces, "Enable support for using indentation for arguments"),
+    (saferExceptions, "Enable safer exceptions"),
+    (clauseInterleaving, "Enable clause interleaving"),
+    (pureFunctions, "Enable pure functions for capture checking"),
+    (captureChecking, "Enable experimental capture checking"),
+    (into, "Allow into modifier on parameter types"),
+    (namedTuples, "Allow named tuples"),
+    (modularity, "Enable experimental modularity features"),
+    (betterMatchTypeExtractors, "Enable better match type extractors")
+  )
+
+  private def enabledLanguageFeaturesBySetting(using Context): List[String] =
+    ctx.settings.language.value.asInstanceOf
+
   /** Is `feature` enabled by by a command-line setting? The enabling setting is
    *
    *       -language:<prefix>feature
@@ -50,7 +80,7 @@ object Feature:
    *  but subtracting the prefix `scala.language.` at the front.
    */
   def enabledBySetting(feature: TermName)(using Context): Boolean =
-    ctx.base.settings.language.value.contains(feature.toString)
+    enabledLanguageFeaturesBySetting.contains(feature.toString)
 
   /** Is `feature` enabled by by an import? This is the case if the feature
    *  is imported by a named import

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

@@ -114,7 +114,7 @@ trait CommonScalaSettings:
   val explainTypes: Setting[Boolean] = BooleanSetting(RootSetting, "explain-types", "Explain type errors in more detail (deprecated, use -explain instead).", aliases = List("--explain-types", "-explaintypes"))
   val explainCyclic: Setting[Boolean] = BooleanSetting(RootSetting, "explain-cyclic", "Explain cyclic reference errors in more detail.", aliases = List("--explain-cyclic"))
   val unchecked: Setting[Boolean] = BooleanSetting(RootSetting, "unchecked", "Enable additional warnings where generated code depends on assumptions.", initialValue = true, aliases = List("--unchecked"))
-  val language: Setting[List[String]] = MultiStringSetting(RootSetting, "language", "feature", "Enable one or more language features.", aliases = List("--language"))
+  val language: Setting[List[ChoiceWithHelp[String]]] = MultiChoiceHelpSetting(RootSetting, "language", "feature", "Enable one or more language features.", choices = ScalaSettingsProperties.supportedLanguageFeatures, default = Nil, aliases = List("--language"))
   val experimental: Setting[Boolean] = BooleanSetting(RootSetting, "experimental", "Annotate all top-level definitions with @experimental. This enables the use of experimental features anywhere in the project.")
 
   /* Coverage settings */
@@ -492,3 +492,4 @@ private sealed trait YSettings:
   @deprecated(message = "Scheduled for removal.", since = "3.5.0")
   val YoutputOnlyTasty: Setting[Boolean] = BooleanSetting(ForkSetting, "Youtput-only-tasty", "Used to only generate the TASTy file without the classfiles", deprecation = Deprecation.removed())
 end YSettings
+

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

@@ -1,6 +1,7 @@
 package dotty.tools.dotc
 package config
 
+import Settings.Setting.ChoiceWithHelp
 import dotty.tools.backend.jvm.BackendUtils.classfileVersionMap
 import dotty.tools.io.{AbstractFile, Directory, JDK9Reflectors, PlainDirectory, NoAbstractFile}
 import scala.language.unsafeNulls
@@ -26,6 +27,9 @@ object ScalaSettingsProperties:
   def supportedSourceVersions: List[String] =
     SourceVersion.values.toList.map(_.toString)
 
+  def supportedLanguageFeatures: List[ChoiceWithHelp[String]] =
+    Feature.values.map((n, d) => ChoiceWithHelp(n.toString, d))
+
   def defaultClasspath: String = sys.env.getOrElse("CLASSPATH", ".")
 
   def defaultPageWidth: Int = {

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

@@ -380,7 +380,7 @@ object Settings:
     def ChoiceSetting(category: SettingCategory, name: String, helpArg: String, descr: String, choices: List[String], default: String, aliases: List[String] = Nil, legacyArgs: Boolean = false, deprecation: Option[Deprecation] = None): Setting[String] =
       publish(Setting(category, prependName(name), descr, default, helpArg, Some(choices), aliases = aliases, legacyArgs = legacyArgs, deprecation = deprecation))
 
-    def MultiChoiceSetting(category: SettingCategory, name: String, helpArg: String, descr: String, choices: List[String], default: List[String], aliases: List[String] = Nil, deprecation: Option[Deprecation] = None): Setting[List[String]] =
+    def MultiChoiceSetting(category: SettingCategory, name: String, helpArg: String, descr: String, choices: List[String], default: List[String] = Nil, aliases: List[String] = Nil, deprecation: Option[Deprecation] = None): Setting[List[String]] =
       publish(Setting(category, prependName(name), descr, default, helpArg, Some(choices), aliases = aliases, deprecation = deprecation))
 
     def MultiChoiceHelpSetting(category: SettingCategory, name: String, helpArg: String, descr: String, choices: List[ChoiceWithHelp[String]], default: List[ChoiceWithHelp[String]], aliases: List[String] = Nil, deprecation: Option[Deprecation] = None): Setting[List[ChoiceWithHelp[String]]] =

compiler/src/dotty/tools/dotc/core/StdNames.scala

@@ -509,6 +509,7 @@ object StdNames {
     val _hashCode_ : N          = "_hashCode"
     val hash_ : N               = "hash"
     val head: N                 = "head"
+    val help: N                 = "help"
     val higherKinds: N          = "higherKinds"
     val idx: N                  = "idx"
     val identity: N             = "identity"

compiler/test/dotty/tools/DottyTest.scala

@@ -40,7 +40,7 @@ trait DottyTest extends ContextEscapeDetection {
   protected def initializeCtx(fc: FreshContext): Unit = {
     fc.setSetting(fc.settings.encoding, "UTF8")
     fc.setSetting(fc.settings.classpath, TestConfiguration.basicClasspath)
-    fc.setSetting(fc.settings.language, List("experimental.erasedDefinitions"))
+    fc.setSetting(fc.settings.language, List("experimental.erasedDefinitions").asInstanceOf)
     fc.setProperty(ContextDoc, new ContextDocstrings)
   }
 

compiler/test/dotty/tools/dotc/CompilationTests.scala

@@ -143,7 +143,7 @@ class CompilationTests {
         "tests/neg-custom-args/toplevel-samesource/S.scala",
         "tests/neg-custom-args/toplevel-samesource/nested/S.scala"),
         defaultOptions),
-      compileFile("tests/neg/i7575.scala", defaultOptions.withoutLanguageFeatures.and("-language:_")),
+      compileFile("tests/neg/i7575.scala", defaultOptions.withoutLanguageFeatures),
     ).checkExpectedErrors()
   }