Improve descriptions of compiler options

compiler/cli/cli-common/src/org/jetbrains/kotlin/cli/common/arguments/CommonCompilerArguments.kt

@@ -43,7 +43,7 @@ abstract class CommonCompilerArguments : CommonToolArguments() {
     @Argument(
         value = "-language-version",
         valueDescription = "<version>",
-        description = "Provide source compatibility with specified language version"
+        description = "Provide source compatibility with the specified version of Kotlin"
     )
     var languageVersion: String? by NullableStringFreezableVar(null)
 
@@ -54,14 +54,14 @@ abstract class CommonCompilerArguments : CommonToolArguments() {
     @Argument(
         value = "-api-version",
         valueDescription = "<version>",
-        description = "Allow to use declarations only from the specified version of bundled libraries"
+        description = "Allow using declarations only from the specified version of bundled libraries"
     )
     var apiVersion: String? by NullableStringFreezableVar(null)
 
     @Argument(
         value = "-kotlin-home",
         valueDescription = "<path>",
-        description = "Path to Kotlin compiler home directory, used for runtime libraries discovery"
+        description = "Path to the home directory of Kotlin compiler used for discovery of runtime libraries"
     )
     var kotlinHome: String? by NullableStringFreezableVar(null)
 
@@ -76,7 +76,7 @@ abstract class CommonCompilerArguments : CommonToolArguments() {
     )
     var progressiveMode by FreezableVar(false)
 
-    @Argument(value = "-script", description = "Evaluate the script file")
+    @Argument(value = "-script", description = "Evaluate the given Kotlin script (*.kts) file")
     var script: Boolean by FreezableVar(false)
 
     @Argument(value = "-P", valueDescription = PLUGIN_OPTION_FORMAT, description = "Pass an option to a plugin")

compiler/cli/cli-common/src/org/jetbrains/kotlin/cli/common/arguments/K2JSCompilerArguments.kt

@@ -25,11 +25,11 @@ class K2JSCompilerArguments : CommonCompilerArguments() {
     }
 
     @GradleOption(DefaultValues.StringNullDefault::class)
-    @Argument(value = "-output", valueDescription = "<path>", description = "Output file path")
+    @Argument(value = "-output", valueDescription = "<filepath>", description = "Destination *.js file for the compilation result")
     var outputFile: String? by NullableStringFreezableVar(null)
 
     @GradleOption(DefaultValues.BooleanTrueDefault::class)
-    @Argument(value = "-no-stdlib", description = "Don't use bundled Kotlin stdlib")
+    @Argument(value = "-no-stdlib", description = "Don't automatically include the default Kotlin/JS stdlib into compilation dependencies")
     var noStdlib: Boolean by FreezableVar(false)
 
     @Argument(
@@ -44,14 +44,14 @@ class K2JSCompilerArguments : CommonCompilerArguments() {
     var sourceMap: Boolean by FreezableVar(false)
 
     @GradleOption(DefaultValues.StringNullDefault::class)
-    @Argument(value = "-source-map-prefix", description = "Prefix for paths in a source map")
+    @Argument(value = "-source-map-prefix", description = "Add the specified prefix to paths in the source map")
     var sourceMapPrefix: String? by NullableStringFreezableVar(null)
 
     @Argument(
             value = "-source-map-base-dirs",
             deprecatedName = "-source-map-source-roots",
             valueDescription = "<path>",
-            description = "Base directories which are used to calculate relative paths to source files in source map"
+            description = "Base directories for calculating relative paths to source files in source map"
     )
     var sourceMapBaseDirs: String? by NullableStringFreezableVar(null)
 
@@ -62,7 +62,7 @@ class K2JSCompilerArguments : CommonCompilerArguments() {
     @GradleOption(DefaultValues.JsSourceMapContentModes::class)
     @Argument(
             value = "-source-map-embed-sources",
-            valueDescription = "{ always, never, inlining }",
+            valueDescription = "{always|never|inlining}",
             description = "Embed source files into source map"
     )
     var sourceMapEmbedSources: String? by NullableStringFreezableVar(null)
@@ -78,26 +78,29 @@ class K2JSCompilerArguments : CommonCompilerArguments() {
     @GradleOption(DefaultValues.JsModuleKinds::class)
     @Argument(
             value = "-module-kind",
-            valueDescription = "{ plain, amd, commonjs, umd }",
+            valueDescription = "{plain|amd|commonjs|umd}",
-            description = "Kind of a module generated by compiler"
+            description = "Kind of the JS module generated by the compiler"
     )
     var moduleKind: String? by NullableStringFreezableVar(K2JsArgumentConstants.MODULE_PLAIN)
 
     @GradleOption(DefaultValues.JsMain::class)
-    @Argument(value = "-main", valueDescription = "{$CALL,$NO_CALL}", description = "Whether a main function should be called")
+    @Argument(
+        value = "-main",
+        valueDescription = "{$CALL|$NO_CALL}",
+        description = "Define whether the `main` function should be called upon execution")
     var main: String? by NullableStringFreezableVar(null)
 
     @Argument(
             value = "-output-prefix",
             valueDescription = "<path>",
-            description = "Path to file which will be added to the beginning of output file"
+            description = "Add the content of the specified file to the beginning of output file"
     )
     var outputPrefix: String? by NullableStringFreezableVar(null)
 
     @Argument(
             value = "-output-postfix",
             valueDescription = "<path>",
-            description = "Path to file which will be added to the end of output file"
+            description = "Add the content of the specified file to the end of output file"
     )
     var outputPostfix: String? by NullableStringFreezableVar(null)
 

compiler/cli/cli-common/src/org/jetbrains/kotlin/cli/common/arguments/K2JVMCompilerArguments.kt

@@ -18,31 +18,35 @@ class K2JVMCompilerArguments : CommonCompilerArguments() {
     @Argument(value = "-d", valueDescription = "<directory|jar>", description = "Destination for generated class files")
     var destination: String? by NullableStringFreezableVar(null)
 
-    @Argument(value = "-classpath", shortName = "-cp", valueDescription = "<path>", description = "Paths where to find user class files")
+    @Argument(
+        value = "-classpath",
+        shortName = "-cp",
+        valueDescription = "<path>",
+        description = "List of directories and JAR/ZIP archives to search for user class files")
     var classpath: String? by NullableStringFreezableVar(null)
 
     @GradleOption(DefaultValues.BooleanFalseDefault::class)
-    @Argument(value = "-include-runtime", description = "Include Kotlin runtime into the resulting .jar")
+    @Argument(value = "-include-runtime", description = "Include Kotlin runtime into the resulting JAR")
     var includeRuntime: Boolean by FreezableVar(false)
 
     @GradleOption(DefaultValues.StringNullDefault::class)
     @Argument(
         value = "-jdk-home",
         valueDescription = "<path>",
-        description = "Path to JDK home directory to include into classpath, if differs from default JAVA_HOME"
+        description = "Include a custom JDK from the specified location into the classpath instead of the default JAVA_HOME"
     )
     var jdkHome: String? by NullableStringFreezableVar(null)
 
     @GradleOption(DefaultValues.BooleanFalseDefault::class)
-    @Argument(value = "-no-jdk", description = "Don't include Java runtime into classpath")
+    @Argument(value = "-no-jdk", description = "Don't automatically include the Java runtime into the classpath")
     var noJdk: Boolean by FreezableVar(false)
 
     @GradleOption(DefaultValues.BooleanTrueDefault::class)
-    @Argument(value = "-no-stdlib", description = "Don't include kotlin-stdlib.jar or kotlin-reflect.jar into classpath")
+    @Argument(value = "-no-stdlib", description = "Don't automatically include the Kotlin/JVM stdlib and Kotlin reflection into the classpath")
     var noStdlib: Boolean by FreezableVar(false)
 
     @GradleOption(DefaultValues.BooleanTrueDefault::class)
-    @Argument(value = "-no-reflect", description = "Don't include kotlin-reflect.jar into classpath")
+    @Argument(value = "-no-reflect", description = "Don't automatically include Kotlin reflection into the classpath")
     var noReflect: Boolean by FreezableVar(false)
 
     @Argument(