Merge pull request #28 from teogor/feature/refresh-unity-assets-task

Refactor UnityAssetSyncTask to RefreshUnityAssetsTask with Updated Naming and Documentation

docs/plugin-usage-guide.md

@@ -2,7 +2,9 @@
 
 ## Overview
 
-The Unity Integration Plugin simplifies the process of integrating Unity projects into your Gradle-based project. It provides two essential tasks: `BuildIl2CppTask` and `UnityAssetSyncTask`. This guide explains how to use these tasks effectively.
+The Unity Integration Plugin simplifies the process of integrating Unity projects into your
+Gradle-based project. It provides two essential tasks: `BuildIl2CppTask`
+and `RefreshUnityAssetsTask`. This guide explains how to use these tasks effectively.
 
 ## Prerequisites
 
@@ -33,7 +35,8 @@ To get started, add the Unity Integration Plugin to your `build.gradle` file:
 
 ### Purpose
 
-The `BuildIl2CppTask` automates the compilation and building of Il2Cpp for Unity integration. It enhances the efficiency of your development workflow by handling complex build processes.
+The `BuildIl2CppTask` automates the compilation and building of Il2Cpp for Unity integration. It
+enhances the efficiency of your development workflow by handling complex build processes.
 
 ### Configuration
 
@@ -81,7 +84,8 @@ To use `BuildIl2CppTask`, follow these steps:
 ./gradlew buildIl2Cpp
 ```
 
-Here's a Kotlin code snippet for your `build.gradle` file that demonstrates the configuration and usage:
+Here's a Kotlin code snippet for your `build.gradle` file that demonstrates the configuration and
+usage:
 
 === "Kotlin"
 
@@ -104,15 +108,16 @@ Here's a Kotlin code snippet for your `build.gradle` file that demonstrates the
     }
     ```
 
-### Using `UnityAssetSyncTask`
+## Using `RefreshUnityAssetsTask`
 
 ### Purpose
 
-The `UnityAssetSyncTask` streamlines the synchronization of Unity exported assets with your project. It prepares the project for Unity integration by copying essential folders.
+The `RefreshUnityAssetsTask` streamlines the synchronization and updating of Unity exported assets
+with your project. It prepares the project for Unity integration by updating essential folders.
 
 ### Configuration
 
-To use `UnityAssetSyncTask`, follow these steps:
+To use `RefreshUnityAssetsTask`, follow these steps:
 
 1. Configure Unity options in your `build.gradle` file (if not already done).
 
@@ -121,31 +126,32 @@ To use `UnityAssetSyncTask`, follow these steps:
 === "Groovy"
 
     ```groovy title="build.gradle"
-    createUnityAssetSyncTask(unityOptions)
+    createRefreshUnityAssetsTask(unityOptions)
     ```
 
 === "Kotlin"
 
     ```kotlin title="build.gradle.kts"
-    createUnityAssetSyncTask(unityOptions)
+    createRefreshUnityAssetsTask(unityOptions)
     ```
 
 3. Execute the task:
 
 ```shell
-./gradlew syncUnityAssets
+./gradlew refreshUnityAssets
 ```
 
-Here's a Kotlin code snippet for your `build.gradle` file that demonstrates the configuration and usage:
+Here's a Kotlin code snippet for your `build.gradle` file that demonstrates the configuration and
+usage:
 
 === "Kotlin"
 
     ```kotlin title="build.gradle.kts"
-    // Create and set up the UnityAssetSyncTask
-    createUnityAssetSyncTask(unityOptions)
+    // Create and set up the RefreshUnityAssetsTask
+    createRefreshUnityAssetsTask(unityOptions)
 
-    // Execute the UnityAssetSyncTask
-    tasks.named("syncUnityAssets").configure {
+    // Execute the RefreshUnityAssetsTask
+    tasks.named("refreshUnityAssets").configure {
         // Add any additional configuration or dependencies here if needed
         // For example:
         // dependsOn("anotherTask")
@@ -154,11 +160,13 @@ Here's a Kotlin code snippet for your `build.gradle` file that demonstrates the
 
 ## Conclusion
 
-With the Unity Integration Plugin, you can seamlessly integrate Unity projects into your Gradle-based project, enhancing the development process and ensuring consistency. If you encounter any issues or have feature requests, please don't hesitate to contribute or reach out for support.
+With the Unity Integration Plugin, you can seamlessly integrate Unity projects into your
+Gradle-based project, enhancing the development process and ensuring consistency. If you encounter
+any issues or have feature requests, please don't hesitate to contribute or reach out for support.
 
 ## Quick References
 
 1. [Installation](#installation)
 2. [Using `BuildIl2CppTask`](#using-buildil2cpptask)
-3. [Using `UnityAssetSyncTask`](#using-unityassetsynctask)
+3. [Using `RefreshUnityAssetsTask`](#using-refreshunityassetstask)
 4. [Conclusion](#conclusion)

gradle-plugin/api/gradle-plugin.api

@@ -39,17 +39,22 @@ public final class dev/teogor/drifter/plugin/FolderDeletionException : java/lang
 public abstract interface annotation class dev/teogor/drifter/plugin/InternalDrifterApi : java/lang/annotation/Annotation {
 }
 
-public class dev/teogor/drifter/plugin/UnityAssetSyncTask : org/gradle/api/DefaultTask {
+public class dev/teogor/drifter/plugin/RefreshUnityAssetsTask : org/gradle/api/DefaultTask {
+	public static final field Companion Ldev/teogor/drifter/plugin/RefreshUnityAssetsTask$Companion;
+	public static final field TASK_NAME Ljava/lang/String;
 	public fun <init> ()V
-	public final fun importContent ()V
+	public final fun executeTask ()V
 	public final fun setUnityOptions (Ldev/teogor/drifter/plugin/models/UnityOptions;)V
 }
 
-public final class dev/teogor/drifter/plugin/UnityAssetSyncTaskKt {
-	public static final fun createUnityAssetSyncTask (Lorg/gradle/api/Project;Ldev/teogor/drifter/plugin/models/UnityOptions;)V
+public final class dev/teogor/drifter/plugin/RefreshUnityAssetsTask$Companion {
 }
 
-public final class dev/teogor/drifter/plugin/UnityAssetSyncTaskKt$inlined$sam$i$org_gradle_api_Action$0 : org/gradle/api/Action {
+public final class dev/teogor/drifter/plugin/RefreshUnityAssetsTaskKt {
+	public static final fun createRefreshUnityAssetsTask (Lorg/gradle/api/Project;Ldev/teogor/drifter/plugin/models/UnityOptions;)V
+}
+
+public final class dev/teogor/drifter/plugin/RefreshUnityAssetsTaskKt$inlined$sam$i$org_gradle_api_Action$0 : org/gradle/api/Action {
 	public fun <init> (Lkotlin/jvm/functions/Function1;)V
 	public final synthetic fun execute (Ljava/lang/Object;)V
 }

gradle-plugin/src/main/kotlin/dev/teogor/drifter/plugin/BuildIl2CppTask.kt

@@ -225,7 +225,7 @@ fun Project.createBuildIl2CppTask(
   unityOptions: UnityOptions,
 ) {
   tasks.register<BuildIl2CppTask>("buildIl2Cpp") {
-    dependsOn("syncUnityAssets")
+    dependsOn(RefreshUnityAssetsTask.TASK_NAME)
     setUnityOptions(unityOptions)
   }
 }

gradle-plugin/src/main/kotlin/dev/teogor/drifter/plugin/UnityAssetSyncTask.kt → gradle-plugin/src/main/kotlin/dev/teogor/drifter/plugin/RefreshUnityAssetsTask.kt

@@ -23,20 +23,18 @@ import org.gradle.api.tasks.TaskAction
 import org.gradle.api.tasks.TaskExecutionException
 import org.gradle.kotlin.dsl.register
 import java.io.File
-import java.io.IOException
 
 /**
- * A Gradle task for synchronizing Unity exported content with the project's directory.
+ * A Gradle task for refreshing and updating Unity assets and resources in the project's directory.
  *
  * This task performs the following actions:
  * - Deletes specific folders from the target directory.
  * - Copies updated content from the Unity export directory, including symbols, assets,
  *   JNI libraries, and other resources.
  *
- * @see [createUnityAssetSyncTask]
+ * @see [createRefreshUnityAssetsTask]
  */
-open class UnityAssetSyncTask : DefaultTask() {
-
+open class RefreshUnityAssetsTask : DefaultTask() {
   private lateinit var unityOptions: UnityOptions
 
   private val sourceDir: File by lazy {
@@ -50,20 +48,20 @@ open class UnityAssetSyncTask : DefaultTask() {
 
   init {
     group = "dev.teogor.drifter"
-    description = "Synchronizes Unity exported content with the project's directory."
+    description = "Refreshes and updates Unity assets and resources in the project's directory."
   }
 
   /**
-   * Executes the synchronization task.
+   * Executes the asset refresh task.
    *
-   * This method orchestrates the synchronization process by calling individual methods
+   * This method orchestrates the refresh process by calling individual methods
    * for folder deletion and content copying.
    *
    * @throws UnityOptionsNotInitializedException if the UnityOptions is not initialized.
    * @throws TaskExecutionException if an error occurs during the task execution.
    */
   @TaskAction
-  fun importContent() {
+  fun executeTask() {
     try {
       checkInitialized()
       deleteTargetFolders()
@@ -76,7 +74,7 @@ open class UnityAssetSyncTask : DefaultTask() {
   /**
    * Deletes specified folders from the target directory.
    *
-   * @throws IOException if an error occurs during file deletion.
+   * @throws FolderDeletionException if an error occurs during folder deletion.
    */
   private fun deleteTargetFolders() {
     val targetedUnityFolders = listOf(
@@ -98,7 +96,7 @@ open class UnityAssetSyncTask : DefaultTask() {
         }
       }
     } catch (e: Exception) {
-      // Log and rethrow the exception to be handled in the main method
+      // Log and throw a custom exception for folder deletion failure
       logger.error("Failed to delete target folders", e)
       throw FolderDeletionException(
         "Failed to delete one or more target folders. This may be due to permission issues or file system errors.",
@@ -110,7 +108,7 @@ open class UnityAssetSyncTask : DefaultTask() {
   /**
    * Copies updated content from the Unity export directory to the target directory.
    *
-   * @throws IOException if an error occurs during file copying.
+   * @throws ContentCopyException if an error occurs during content copying.
    */
   private fun copyUpdatedContent() {
     val options = unityOptions
@@ -139,7 +137,7 @@ open class UnityAssetSyncTask : DefaultTask() {
         }
       }
     } catch (e: Exception) {
-      // Log and rethrow the exception to be handled in the main method
+      // Log and throw a custom exception for content copy failure
       logger.error("Failed to copy updated content", e)
       throw ContentCopyException(
         "Failed to copy content from the Unity export directory. This may be due to file access issues or I/O errors.",
@@ -151,7 +149,7 @@ open class UnityAssetSyncTask : DefaultTask() {
   /**
    * Sets the UnityOptions for this task.
    *
-   * @param unityOptions The UnityOptions to be used by this task.
+   * @param unityOptions The UnityOptions to be used by the task.
    */
   fun setUnityOptions(unityOptions: UnityOptions) {
     this.unityOptions = unityOptions
@@ -167,12 +165,24 @@ open class UnityAssetSyncTask : DefaultTask() {
       throw UnityOptionsNotInitializedException()
     }
   }
+
+  companion object {
+    /**
+     * The name of the Gradle task for refreshing Unity assets.
+     *
+     * This constant is used to identify the task in Gradle's task registry and can be used
+     * when registering or configuring the task in build scripts or other Gradle-related code.
+     *
+     * @see [createRefreshUnityAssetsTask]
+     */
+    const val TASK_NAME = "refreshUnityAssets"
+  }
 }
 
 /**
  * Exception thrown when attempting to use the task before initializing UnityOptions.
  *
- * @see [UnityAssetSyncTask.checkInitialized]
+ * @see [RefreshUnityAssetsTask.checkInitialized]
  */
 class UnityOptionsNotInitializedException : RuntimeException(
   """
@@ -188,7 +198,7 @@ class UnityOptionsNotInitializedException : RuntimeException(
  * @param message A description of the error that occurred.
  * @param cause The cause of the error, or `null` if the cause is nonexistent or unknown.
  *
- * @see [UnityAssetSyncTask.deleteTargetFolders]
+ * @see [RefreshUnityAssetsTask.deleteTargetFolders]
  */
 class FolderDeletionException(message: String, cause: Throwable? = null) : RuntimeException(
   """
@@ -207,7 +217,7 @@ class FolderDeletionException(message: String, cause: Throwable? = null) : Runti
  * @param message A description of the error that occurred.
  * @param cause The cause of the error, or `null` if the cause is nonexistent or unknown.
  *
- * @see [UnityAssetSyncTask.copyUpdatedContent]
+ * @see [RefreshUnityAssetsTask.copyUpdatedContent]
  */
 class ContentCopyException(message: String, cause: Throwable? = null) : RuntimeException(
   """
@@ -221,16 +231,16 @@ class ContentCopyException(message: String, cause: Throwable? = null) : RuntimeE
 )
 
 /**
- * Creates and registers a [UnityAssetSyncTask] with the given [unityOptions].
+ * Creates and registers a [RefreshUnityAssetsTask] with the given [unityOptions].
  *
  * @param unityOptions The UnityOptions to be used by the task.
  *
- * @see [UnityAssetSyncTask]
+ * @see [RefreshUnityAssetsTask]
  */
-fun Project.createUnityAssetSyncTask(
+fun Project.createRefreshUnityAssetsTask(
   unityOptions: UnityOptions,
 ) {
-  tasks.register<UnityAssetSyncTask>("syncUnityAssets") {
+  tasks.register<RefreshUnityAssetsTask>(RefreshUnityAssetsTask.TASK_NAME) {
     setUnityOptions(unityOptions)
   }
 }

gradle-plugin/src/main/kotlin/dev/teogor/drifter/plugin/UnityOptions.kt

@@ -40,7 +40,7 @@ fun Project.unityOptions(
     unityOptions = unityOptions,
   )
 
-  createUnityAssetSyncTask(
+  createRefreshUnityAssetsTask(
     unityOptions = unityOptions,
   )