[Gradle] Document KotlinJsTargetDsl

Expand kdoc for `passAsArgumentToMainFunction()`, `ExperimentalMainFunctionArgumentsDsl`

^KT-76299

Author: adam-enko

libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/targets/js/dsl/ExperimentalMainFunctionArgumentsDsl.kt

@@ -5,6 +5,20 @@
 
 package org.jetbrains.kotlin.gradle.targets.js.dsl
 
-@RequiresOptIn(level = RequiresOptIn.Level.WARNING)
-@Target(AnnotationTarget.FUNCTION)
+import kotlin.RequiresOptIn.Level.WARNING
+import kotlin.annotation.AnnotationTarget.FUNCTION
+
+/**
+ * API marker for defining the source of arguments for the main function.
+ *
+ * Passing arguments to the main function is Experimental.
+ * It may be dropped or changed at any time.
+ *
+ * See https://kotl.in/kotlin-js-pass-arguments-to-main-function
+ *
+ * @see KotlinJsTargetDsl.passAsArgumentToMainFunction
+ * @see KotlinJsNodeDsl.passProcessArgvToMainFunction
+ */
+@RequiresOptIn(level = WARNING)
+@Target(FUNCTION)
 annotation class ExperimentalMainFunctionArgumentsDsl

libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/targets/js/dsl/KotlinJsTargetDsl.kt

@@ -164,7 +164,20 @@ interface KotlinJsTargetDsl :
     fun useEsModules()
 
     /**
-     * The function accepts [jsExpression] and puts this expression as the "args: Array<String>" argument in place of main-function call
+     * _This option is only relevant for JS targets._
+     * _Do not use in WasmJS targets._
+     *
+     * > Note: Passing arguments to the main function is Experimental.
+     * > It may be dropped or changed at any time.
+     *
+     * Specify a source of arguments for the `main()` function.
+     *
+     * [jsExpression] must be a JavaScript function that returns an array of Strings.
+     * The array will be set as in the application's main argument, `args: Array<String>`, in place of main-function call.
+     *
+     * See https://kotl.in/kotlin-js-pass-arguments-to-main-function
+     *
+     * @see KotlinJsNodeDsl.passProcessArgvToMainFunction
      */
     @ExperimentalMainFunctionArgumentsDsl
     fun passAsArgumentToMainFunction(jsExpression: String)
@@ -244,6 +257,19 @@ interface KotlinJsBrowserDsl : KotlinJsSubTargetDsl {
 interface KotlinJsNodeDsl : KotlinJsSubTargetDsl {
     fun runTask(body: Action<NodeJsExec>)
 
+    /**
+     * _This option is only relevant for JS targets._
+     * _Do not use in WasmJS targets._
+     *
+     * > Note: Passing arguments to the main function is Experimental.
+     * > It may be dropped or changed at any time.
+     *
+     * Enable passing `process.argv` to the main function's `args` parameter.
+     *
+     * See https://kotl.in/kotlin-js-pass-arguments-to-main-function
+     *
+     * @see KotlinJsTargetDsl.passAsArgumentToMainFunction
+     */
     @ExperimentalMainFunctionArgumentsDsl
     fun passProcessArgvToMainFunction()
 }