Document scripting common API, drop unused bits

libraries/scripting/common/src/kotlin/script/experimental/host/BasicScriptingHost.kt

@@ -22,12 +22,21 @@ import kotlinx.coroutines.experimental.CoroutineScope
 import kotlinx.coroutines.experimental.runBlocking
 import kotlin.script.experimental.api.*
 
+/**
+ * The base class for scripting host implementations
+ */
 abstract class BasicScriptingHost(
     val compiler: ScriptCompiler,
     val evaluator: ScriptEvaluator
 ) {
+    /**
+     * The overridable wrapper for executing evaluation in a desired coroutines context
+     */
     open fun <T> runInCoroutineContext(block: suspend CoroutineScope.() -> T): T = runBlocking { block() }
 
+    /**
+     * The default implementation of the evaluation function
+     */
     open fun eval(
         script: SourceCode,
         scriptCompilationConfiguration: ScriptCompilationConfiguration,

libraries/scripting/common/src/kotlin/script/experimental/host/configurationFromTemplate.kt

@@ -19,6 +19,13 @@ private const val SCRIPT_RUNTIME_TEMPLATES_PACKAGE = "kotlin.script.templates.st
 @KotlinScript
 private abstract class DummyScriptTemplate
 
+/**
+ * Creates the compilation configuration from annotated script base class
+ * @param baseClassType the annotated script base class to construct the configuration from
+ * @param hostConfiguration scripting host configuration properties
+ * @param contextClass optional context class to extract classloading strategy from
+ * @param body optional configuration function to add more properties to the compilation configuration
+ */
 fun createCompilationConfigurationFromTemplate(
     baseClassType: KotlinType,
     hostConfiguration: ScriptingHostConfiguration,

libraries/scripting/common/src/kotlin/script/experimental/host/scriptHostUtil.kt

@@ -9,6 +9,7 @@ import java.io.File
 import java.net.URL
 import kotlin.script.experimental.api.*
 
+// helper function
 fun getMergedScriptText(script: SourceCode, configuration: ScriptCompilationConfiguration?): String {
     val originalScriptText = script.text
     val sourceFragments = configuration?.get(ScriptCompilationConfiguration.sourceFragments)
@@ -38,15 +39,27 @@ fun getMergedScriptText(script: SourceCode, configuration: ScriptCompilationConf
     }
 }
 
+/**
+ * The implementation of the SourceCode for a script located in a file
+ */
 open class FileScriptSource(val file: File) : ExternalSourceCode {
     override val externalLocation: URL get() = file.toURI().toURL()
     override val text: String by lazy { file.readText() }
 }
 
+/**
+ * Converts the file into the SourceCode
+ */
 fun File.toScriptSource(): SourceCode = FileScriptSource(this)
 
+/**
+ * The implementation of the ScriptSource for a script in a String
+ */
 open class StringScriptSource(val source: String) : SourceCode {
     override val text: String get() = source
 }
 
+/**
+ * Converts the String into the SourceCode
+ */
 fun String.toScriptSource(): SourceCode = StringScriptSource(this)

libraries/scripting/common/src/kotlin/script/experimental/host/scriptingEnvironment.kt

@@ -12,6 +12,10 @@ import kotlin.script.experimental.util.PropertiesCollection
 
 interface ScriptingHostConfigurationKeys
 
+/**
+ * The container for script evaluation configuration
+ * For usages see actual code examples
+ */
 class ScriptingHostConfiguration(baseScriptingConfigurations: Iterable<ScriptingHostConfiguration>, body: Builder.() -> Unit) :
     PropertiesCollection(Builder(baseScriptingConfigurations).apply(body).data) {
 
@@ -27,27 +31,30 @@ class ScriptingHostConfiguration(baseScriptingConfigurations: Iterable<Scripting
     companion object : ScriptingHostConfigurationKeys
 }
 
-// should contain all dependencies needed for baseClass and compilationConfigurator
+/**
+ * The list of all dependencies required for the script base class and refinement callbacks
+ */
 val ScriptingHostConfigurationKeys.configurationDependencies by PropertiesCollection.key<List<ScriptDependency>>()
 
-// do not use configurationDependencies as script dependencies, so only the dependencies defined by compilationConfigurator will be used
-// (NOTE: in this case they should include the dependencies for the base class anyway, since this class is needed for script
-// compilation and instantiation, but compilationConfigurator could be excluded)
-val ScriptingHostConfigurationKeys.isolatedDependencies by PropertiesCollection.key<Boolean>(false)
-
-// a "class loader" for KotlinTypes
+/**
+ * The pointer to the generic "class loader" for the types used in the script configurations
+ */
 val ScriptingHostConfigurationKeys.getScriptingClass by PropertiesCollection.key<GetScriptingClass>()
 
-
+/**
+ * The interface to the generic "class loader" for the types used in the script configurations
+ */
 interface GetScriptingClass {
     operator fun invoke(classType: KotlinType, contextClass: KClass<*>, hostConfiguration: ScriptingHostConfiguration): KClass<*>
 }
 
+// helper method
 fun ScriptingHostConfiguration.getScriptingClass(type: KotlinType, contextClass: KClass<*>): KClass<*> {
     val getClass = get(ScriptingHostConfiguration.getScriptingClass)
         ?: throw IllegalArgumentException("Expecting 'getScriptingClass' property in the scripting environment: unable to load scripting class $type")
     return getClass(type, contextClass, this)
 }
 
+// helper method
 fun ScriptingHostConfiguration.getScriptingClass(type: KotlinType, context: Any): KClass<*> = getScriptingClass(type, context::class)