doc(compiler): async函数支持第二个参数：CoroutineScope

Author: ForteScarlet

compiler/suspend-transform-plugin/build.gradle.kts

@@ -1,7 +1,3 @@
-import com.bennyhuo.kotlin.plugin.embeddable.embeddableCompiler
-import com.bennyhuo.kotlin.plugin.embeddable.getOrCreate
-import com.bennyhuo.kotlin.plugin.embeddable.testWithEmbedded
-import embeddable.testWithEmbedded0
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
@@ -19,6 +15,8 @@ plugins {
 dependencies {
     compileOnly(kotlin("stdlib"))
     compileOnly(kotlin("compiler"))
+    compileOnly("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.4")
+
 //    compileOnly(kotlin("compiler-embeddable"))
 
     kapt("com.google.auto.service:auto-service:1.0.1")

compiler/suspend-transform-plugin/src/main/kotlin/love/forte/plugin/suspendtrans/SuspendTransformConfiguration.kt

@@ -51,13 +51,27 @@ open class SuspendTransformConfiguration @JvmOverloads constructor(var enabled:
         var jvmAsyncMarkAnnotation = MarkAnnotation(TO_JVM_ASYNC_ANNOTATION_NAME)
 
         /**
-         * 格式必须为
+         * 格式必须为:
          *
          * ```kotlin
-         * fun <T> <fun-name>(block: suspend () -> T): CompletableFuture<T> {
+         * fun <T> <fun-name>(block: suspend () -> T[, scope: CoroutineScope = ...]): CompletableFuture<T> {
          *     // ...
          * }
          * ```
+         *
+         * 其中，此异步函数可以有第二个参数，此参数格式必须为 [kotlinx.coroutines.CoroutineScope]。
+         * 如果存在此参数，当转化函数所处类型自身实现了 [kotlinx.coroutines.CoroutineScope] 时，将会将其自身作为参数填入，类似于：
+         *
+         * ```kotlin
+         * class Bar : CoroutineScope {
+         *    @JvmAsync
+         *    suspend fun foo(): Foo
+         *
+         *    @Api4J fun fooAsync(): CompletableFuture<Foo> = runInAsync(block = { foo() }, scope = this)
+         * }
+         * ```
+         * 当前类型不属于 [kotlinx.coroutines.CoroutineScope] 类型时不会使用此参数。
+         *
          */
         var jvmAsyncFunctionName: String = JVM_RUN_IN_ASYNC_FUNCTION_NAME