Add script documentation for kotlin-shell and kotlinx-html

Author: imbananko

build.gradle.kts

@@ -12,3 +12,10 @@ allprojects {
     }
 }
 
+dependencies {
+    // adding these dependencies here just to have it locally available after gradle project import
+    // can be useful when running performance tests for .main.kts scripts
+    implementation("org.jetbrains.kotlinx:kotlinx-html-jvm:0.8.0")
+    implementation("eu.jrie.jetbrains:kotlin-shell-core:0.2.1")
+}
+

jvm/main-kts/scripts/kotlin-shell.main.kts

@@ -1,5 +1,26 @@
 #!/usr/bin/env kotlin
 
+/**
+ * A command-line utility script that provides directory listing and word counting functionality.
+ *
+ * Usage:
+ * - Without arguments: Lists files in the current directory (equivalent to `ls -l`)
+ * - With file argument: Performs word count analysis (similar to `wc` command)
+ *      Shows both custom implementation and system `wc` command results
+ *
+ * Example usage:
+ * ```
+ * ./kotlin-shell.main.kts           # Lists directory contents
+ * ./kotlin-shell.main.kts file.txt  # Counts lines, words, and characters in file.txt
+ * ```
+ *
+ * Dependencies:
+ * - kotlin-shell-core:0.2.1
+ *
+ * @param args - command line arguments. If provided, the first argument should be a file path
+ */
+
+
 @file:DependsOn("eu.jrie.jetbrains:kotlin-shell-core:0.2.1")
 @file:CompilerOptions("-Xopt-in=kotlin.RequiresOptIn")
 @file:OptIn(kotlinx.coroutines.ExperimentalCoroutinesApi::class)

jvm/main-kts/scripts/kotlinx-html.main.kts

@@ -1,5 +1,17 @@
 #!/usr/bin/env kotlin
 
+/**
+ * A demonstration script showing HTML generation using kotlinx.html DSL.
+ * This script creates and prints a simple HTML document with a "Hello, World!" heading.
+ *
+ * Usage:
+ * - Run the script to generate HTML output
+ * - No command line arguments needed
+ *
+ * Dependencies:
+ * - kotlinx-html-jvm:0.8.0
+ */
+
 @file:DependsOn("org.jetbrains.kotlinx:kotlinx-html-jvm:0.8.0")
 
 import kotlinx.html.*
@@ -12,4 +24,3 @@ print(createHTML().html {
         h1 { +"Hello, $addressee!" }
     }
 })
-