Add some comments to the script definitions

Author: ligee

jvm/basic/jvm-maven-deps/script/src/main/kotlin/org/jetbrains/kotlin/script/examples/jvm/resolve/maven/scriptDef.kt

@@ -14,36 +14,57 @@ import kotlin.script.experimental.jvm.JvmDependency
 import kotlin.script.experimental.jvm.dependenciesFromCurrentContext
 import kotlin.script.experimental.jvm.jvm
 
+// The KotlinScript annotation marks a class that can serve as a reference to the script definition for
+// `createJvmCompilationConfigurationFromTemplate` call as well as for the discovery mechanism
+// The marked class also become the base class for defined script type (unless redefined in the configuration)
 @KotlinScript(
+    // file name extension by which this script type is recognized by mechanisms built into scripting compiler plugin
+    // and IDE support, it is recommendend to use double extension with the last one being "kts", so some non-specific
+    // scripting support could be used, e.g. in IDE, if the specific support is not installed.
     fileExtension = "scriptwithdeps.kts",
+    // the class or object that defines script compilation configuration for this type of scripts
     compilationConfiguration = ScriptWithMavenDepsConfiguration::class
 )
+// the class is used as the script base class, therefore it should be open or abstract
 abstract class ScriptWithMavenDeps
 
 object ScriptWithMavenDepsConfiguration : ScriptCompilationConfiguration(
     {
+        // adds implicit import statements (in this case `implort kotlin.script.experimental.dependencies.DependsOn`, etc.)
+        // to each script on compilation
         defaultImports(DependsOn::class, Repository::class)
+
         jvm {
+            // the dependenciesFromCurrentContext helper function extracts the classpath from current thread classloader
+            // and take jars with mentioned names to the compilation classpath via `dependencies` key.
+            // to add the whole classpath for the classloader without check for jar presense, use
+            // `dependenciesFromCurrentContext(wholeClasspath = true)`
             dependenciesFromCurrentContext(
                 "script", // script library jar name
                 "kotlin-scripting-dependencies" // DependsOn annotation is taken from this jar
             )
         }
+        // section that callbacks during compilation
         refineConfiguration {
+            // the callback called than any of the listed file-level annotations are encountered in the compiled script
+            // the processing is defined by the `handler`, that may return refined configuration depending on the annotations
             onAnnotations(DependsOn::class, Repository::class, handler = ::configureMavenDepsOnAnnotations)
         }
     }
 )
 
 private val resolver = CompoundDependenciesResolver(FileSystemDependenciesResolver(), MavenDependenciesResolver())
 
+// The handler that is called during script compilation in order to reconfigure compilation on the fly
 fun configureMavenDepsOnAnnotations(context: ScriptConfigurationRefinementContext): ResultWithDiagnostics<ScriptCompilationConfiguration> {
     val annotations = context.collectedData?.get(ScriptCollectedData.collectedAnnotations)?.takeIf { it.isNotEmpty() }
-            ?: return context.compilationConfiguration.asSuccess()
+            ?: return context.compilationConfiguration.asSuccess() // If no action is performed, the original configuration should be returned
     return runBlocking {
+        // resolving maven artifacts using annotation arguments
         resolver.resolveFromScriptSourceAnnotations(annotations)
     }.onSuccess {
         context.compilationConfiguration.with {
+            // updating the original configurations with the newly resolved artifacts as compilation dependencies
             dependencies.append(JvmDependency(it))
         }.asSuccess()
     }

jvm/basic/jvm-simple-script/script/src/main/kotlin/org/jetbrains/kotlin/script/examples/jvm/simple/scriptDef.kt

@@ -7,5 +7,14 @@ package org.jetbrains.kotlin.script.examples.jvm.simple
 
 import kotlin.script.experimental.annotations.KotlinScript
 
-@KotlinScript(fileExtension = "simplescript.kts")
+// The KotlinScript annotation marks a class that can serve as a reference to the script definition for
+// `createJvmCompilationConfigurationFromTemplate` call as well as for the discovery mechanism
+// The marked class also become the base class for defined script type (unless redefined in the configuration)
+@KotlinScript(
+    // file name extension by which this script type is recognized by mechanisms built into scripting compiler plugin
+    // and IDE support, it is recommendend to use double extension with the last one being "kts", so some non-specific
+    // scripting support could be used, e.g. in IDE, if the specific support is not installed.
+    fileExtension = "simplescript.kts"
+)
+// the class is used as the script base class, therefore it should be open or abstract
 abstract class SimpleScript

jvm/simple-main-kts/simple-main-kts/src/main/kotlin/org/jetbrains/kotlin/script/examples/simpleMainKts/scriptDef.kt

@@ -25,11 +25,22 @@ import kotlin.script.experimental.jvm.*
 import kotlin.script.experimental.jvmhost.CompiledScriptJarsCache
 
 @Suppress("unused")
+// The KotlinScript annotation marks a class that can serve as a reference to the script definition for
+// `createJvmCompilationConfigurationFromTemplate` call as well as for the discovery mechanism
+// The marked class also become the base class for defined script type (unless redefined in the configuration)
 @KotlinScript(
+    // file name extension by which this script type is recognized by mechanisms built into scripting compiler plugin
+    // and IDE support, it is recommendend to use double extension with the last one being "kts", so some non-specific
+    // scripting support could be used, e.g. in IDE, if the specific support is not installed.
     fileExtension = "smain.kts",
+    // the class or object that defines script compilation configuration for this type of scripts
     compilationConfiguration = SimpleMainKtsScriptDefinition::class,
+    // the class or object that defines script evaluation configuration for this type of scripts
     evaluationConfiguration = MainKtsEvaluationConfiguration::class
 )
+// the class is used as the script base class, therefore it should be open or abstract. Also the constructor parameters
+// of the base class are copied to the script constructor, so with this definition the script will require `args` to be
+// passed to the constructor, and `args` could be used in the script as a defined variable.
 abstract class SimpleMainKtsScript(val args: Array<String>)
 
 const val COMPILED_SCRIPTS_CACHE_DIR_ENV_VAR = "KOTLIN_SIMPLE_MAIN_KTS_COMPILED_SCRIPTS_CACHE_DIR"