Enhance documentation for Transformer class, clarifying usage of transform annotations, nullable scope parameters, and annotation copying behavior.

Author: ForteScarlet

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

@@ -227,71 +227,85 @@ class IncludeAnnotation @InternalSuspendTransformConfigurationApi constructor(
 @Serializable
 class Transformer @InternalSuspendTransformConfigurationApi constructor(
     /**
-     * 函数上的某种标记。
+     * Information about the marker annotation that marks functions to be transformed.
      */
     val markAnnotation: MarkAnnotation,
 
     /**
-     * 用于转化的函数信息。
+     * Information of the transform function.
      *
-     * 这个函数的实际格式必须为
+     * The actual format of this function must be:
      *
      * ```kotlin
-     * fun <T> <fun-name>(block: suspend () -> T[, scope: CoroutineScope = ...]): T {
+     * fun <T> <fun-name>(block: suspend () -> T[, scope: CoroutineScope? = ...]): T {
      *     // ...
      * }
      * ```
      *
-     * 其中，此异步函数可以有第二个参数，此参数格式必须为 [kotlinx.coroutines.CoroutineScope]。
-     * 如果存在此参数，当转化函数所处类型自身实现了 [kotlinx.coroutines.CoroutineScope] 时，将会将其自身作为参数填入，类似于：
+     * Among them, this asynchronous function can have a second parameter, which must be of type [kotlinx.coroutines.CoroutineScope] and is recommended to be nullable.
+     * If this parameter exists, when the type containing the transform function implements [kotlinx.coroutines.CoroutineScope] itself, it will fill in itself as a parameter, similar to:
      *
      * ```kotlin
      * class Bar : CoroutineScope {
-     *    @Xxx
+     *    @Xxx // your custom transform function's mark annotation
      *    suspend fun foo(): Foo
      *
      *    @Api4J fun fooXxx(): CompletableFuture<Foo> = transform(block = { foo() }, scope = this)
      * }
+     * ```
+     *
+     * If the scope parameter is nullable, then the effect is similar to:
+     *
+     * ```kotlin
+     * class Bar {
+     *    @Xxx // your custom transform function's mark annotation
+     *    suspend fun foo(): Foo
+     *
+     *    @Api4J fun fooXxx(): CompletableFuture<Foo> = transform(block = { foo() }, scope = this as? CoroutineScope)
+     * }
+     * ```
+     * Therefore, when nullable it is more inheritance-friendly - when the subclass extends CoroutineScope the parameter can take effect, regardless of whether it overrides this function.
+     *
      */
     val transformFunctionInfo: FunctionInfo,
 
     /**
-     * 转化后的返回值类型, 为null时代表与原函数一致。
+     * The return type after transformation. When null, it represents the same as the original function.
      */
     val transformReturnType: ClassInfo?,
 
     // TODO TypeGeneric for suspend function return type and transform function return type?
 
     /**
-     * 转化后的返回值类型中，是否存在需要与原本返回值类型一致的泛型。
+     * Whether there are generics in the transformed return type that need to be consistent with the original return type.
      */
     val transformReturnTypeGeneric: Boolean,
 
     /**
-     * 函数生成后，需要在原函数上追加的注解信息。
+     * Annotation information that needs to be added to the original function after function generation.
      *
-     * 例如追加个 `@kotlin.jvm.JvmSynthetic` 之类的。
+     * For example, add something like `@kotlin.jvm.JvmSynthetic`.
      */
     val originFunctionIncludeAnnotations: List<IncludeAnnotation>,
 
     /**
-     * 需要在生成出来的函数上追加的注解信息。（不需要指定 `@Generated`）
+     * Annotation information that needs to be added to the generated function. (No need to specify `@Generated`)
      */
     val syntheticFunctionIncludeAnnotations: List<IncludeAnnotation>,
 
     /**
-     * 是否复制源函数上的注解到新的函数上。
-     * 如果生成的是属性类型，则表示是否复制到 `getter` 上。
+     * Whether to copy annotations from the source function to the new function.
+     * If generated as a property type, it indicates whether to copy to the `getter`.
      */
     val copyAnnotationsToSyntheticFunction: Boolean,
 
     /**
-     * 复制原函数上注解时需要排除掉的注解。
+     * Annotations to be excluded when copying annotations from the original function.
      */
     val copyAnnotationExcludes: List<ClassInfo>,
 
     /**
-     * 如果是生成属性的话，是否复制源函数上的注解到新的属性上
+     * If generating a property, whether to copy annotations from the source function to the new property
      *
      * @since 0.9.0
      */