Add Javadoc documentation to project (#18)

* Add javadoc comments to files

* Remove some redundant exception throwing comments

* Apply spotless formatter

* Fix javadoc errors

* Re-run spotless formatter

* Add javadoc tag `@implNote`

Author: subhramit

build.gradle

@@ -41,3 +41,6 @@ spotless {
     }
 }
 
+javadoc {
+    options.tags = [ "implNote:a:Implementation Note:" ]
+}

src/main/java/io/github/lambdatest/gradle/AppUploader.java

@@ -5,6 +5,13 @@
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
 
+/**
+ * Handles the asynchronous upload of application files to the LambdaTest platform. This class
+ * manages the upload process and returns the application ID for test execution.
+ *
+ * <p>Uses {@link UploaderUtil#uploadAndGetId(String, String, String)} for the actual file upload
+ * process.
+ */
 public class AppUploader {
 
     private static final Logger logger = LogManager.getLogger(AppUploader.class);
@@ -13,6 +20,13 @@ public class AppUploader {
     private String accessKey;
     private String appFilePath;
 
+    /**
+     * Creates a new AppUploader instance with the specified credentials and file path.
+     *
+     * @param username The LambdaTest account username
+     * @param accessKey The LambdaTest account access key
+     * @param appFilePath The path to the application file to be uploaded
+     */
     public AppUploader(String username, String accessKey, String appFilePath) {
         if (username == null) throw new IllegalArgumentException("Username cannot be null");
         if (accessKey == null) throw new IllegalArgumentException("Access Key cannot be null");
@@ -23,6 +37,13 @@ public AppUploader(String username, String accessKey, String appFilePath) {
         this.appFilePath = appFilePath;
     }
 
+    /**
+     * Uploads the application file asynchronously to LambdaTest.
+     *
+     * @implNote Uses CompletableFuture to perform the upload asynchronously, allowing parallel
+     *     processing of other tasks.
+     * @return A CompletableFuture that resolves to the uploaded application's ID
+     */
     public CompletableFuture<String> uploadAppAsync() {
         return CompletableFuture.supplyAsync(
                 () -> {

src/main/java/io/github/lambdatest/gradle/Constants.java

@@ -1,6 +1,11 @@
 package io.github.lambdatest.gradle;
 
+/**
+ * Constants used throughout the LambdaTest Gradle plugin. This utility class provides centralized
+ * access to API endpoints and other constant values.
+ */
 public class Constants {
+    /** Private constructor to prevent instantiation of this utility class. */
     private Constants() {
         throw new UnsupportedOperationException(
                 "This is a utility class and cannot be instantiated");

src/main/java/io/github/lambdatest/gradle/LambdaTestPlugin.java

@@ -3,8 +3,17 @@
 import org.gradle.api.Plugin;
 import org.gradle.api.Project;
 
+/**
+ * The main plugin class that integrates LambdaTest functionality into the Gradle build system. This
+ * plugin adds the 'runLambdaTest' task to the project's task container.
+ */
 public class LambdaTestPlugin implements Plugin<Project> {
 
+    /**
+     * Applies the plugin to the specified Gradle project, registering the LambdaTest task.
+     *
+     * @param project The Gradle project to which this plugin is being applied
+     */
     @Override
     public void apply(Project project) {
         // Register a new task named "runLambdaTest" and associate it with the LambdaTestTask class

src/main/java/io/github/lambdatest/gradle/LambdaTestTask.java

@@ -11,6 +11,14 @@
 import org.gradle.api.DefaultTask;
 import org.gradle.api.tasks.TaskAction;
 
+/**
+ * Main task class for the LambdaTest Gradle plugin that handles test execution on the LambdaTest
+ * platform. This task manages the upload of applications and test suites, followed by test
+ * execution with specified configurations.
+ *
+ * <p>This task coordinates between {@link AppUploader}, {@link TestSuiteUploader}, and {@link
+ * TestExecutor} to manage the complete test execution lifecycle.
+ */
 public class LambdaTestTask extends DefaultTask {
 
     private static final Logger logger = LogManager.getLogger(LambdaTestTask.class);
@@ -38,6 +46,16 @@ public class LambdaTestTask extends DefaultTask {
     private String testSuiteId;
     private Integer queueTimeout;
 
+    /**
+     * Executes the LambdaTest task, which includes uploading the application and test suite,
+     * followed by test execution on the LambdaTest platform.
+     *
+     * @implNote This method handles the task execution in three main phases: 1. Asynchronous upload
+     *     of the application using {@link AppUploader#uploadAppAsync()} 2. Asynchronous upload of
+     *     the test suite using {@link TestSuiteUploader#uploadTestSuiteAsync()} 3. Test execution
+     *     with {@link TestExecutor#executeTests(Map)}
+     * @throws RuntimeException if any upload or test execution fails
+     */
     @TaskAction
     public void runLambdaTest() {
         logger.info("Starting LambdaTest task...");

src/main/java/io/github/lambdatest/gradle/TestExecutor.java

@@ -9,6 +9,12 @@
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
 
+/**
+ * Manages the execution of tests on the LambdaTest platform. This class handles the test execution
+ * configuration and communication with the LambdaTest API.
+ *
+ * <p>Uses endpoints defined in {@link Constants} for API communication.
+ */
 public class TestExecutor {
     private static final Logger logger = LogManager.getLogger(TestExecutor.class);
 
@@ -19,6 +25,16 @@ public class TestExecutor {
     private List<String> device;
     private Boolean isFlutter;
 
+    /**
+     * Creates a new TestExecutor with the specified configuration.
+     *
+     * @param username The LambdaTest account username
+     * @param accessKey The LambdaTest account access key
+     * @param appId The ID of the uploaded application
+     * @param testSuiteId The ID of the uploaded test suite
+     * @param device List of target devices for test execution
+     * @param isFlutter Boolean indicating if this is a Flutter application
+     */
     public TestExecutor(
             String username,
             String accessKey,
@@ -34,6 +50,15 @@ public TestExecutor(
         this.isFlutter = isFlutter;
     }
 
+    /**
+     * Executes the tests on LambdaTest with the specified parameters.
+     *
+     * @implNote This method constructs the test capabilities and sends them to either {@link
+     *     Constants#BUILD_URL} or {@link Constants#FLUTTER_BUILD_URL} based on whether it's a
+     *     Flutter or standard application.
+     * @param params Map of additional test execution parameters
+     * @throws IOException if there's an error in communication with the LambdaTest API
+     */
     public void executeTests(Map<String, String> params) throws IOException {
         try {
             OkHttpClient client = new OkHttpClient();

src/main/java/io/github/lambdatest/gradle/TestSuiteUploader.java

@@ -5,6 +5,10 @@
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
 
+/**
+ * Handles the asynchronous upload of test suite files to the LambdaTest platform. This class
+ * manages the upload process and returns the test suite ID for test execution.
+ */
 public class TestSuiteUploader {
 
     private static final Logger logger = LogManager.getLogger(TestSuiteUploader.class);
@@ -13,12 +17,26 @@ public class TestSuiteUploader {
     private String accessKey;
     private String testSuiteFilePath;
 
+    /**
+     * Creates a new TestSuiteUploader instance with the specified credentials and file path.
+     *
+     * @param username The LambdaTest account username
+     * @param accessKey The LambdaTest account access key
+     * @param testSuiteFilePath The path to the test suite file to be uploaded
+     */
     public TestSuiteUploader(String username, String accessKey, String testSuiteFilePath) {
         this.username = username;
         this.accessKey = accessKey;
         this.testSuiteFilePath = testSuiteFilePath;
     }
 
+    /**
+     * Uploads the test suite file asynchronously to LambdaTest.
+     *
+     * @implNote Uses CompletableFuture to perform the upload asynchronously, allowing parallel
+     *     processing of other tasks.
+     * @return A CompletableFuture that resolves to the uploaded test suite's ID
+     */
     public CompletableFuture<String> uploadTestSuiteAsync() {
         return CompletableFuture.supplyAsync(
                 () -> {

src/main/java/io/github/lambdatest/gradle/UploaderUtil.java

@@ -12,14 +12,34 @@
 import okhttp3.RequestBody;
 import okhttp3.Response;
 
+/**
+ * Utility class providing common upload functionality for the LambdaTest Gradle plugin. This class
+ * handles the actual file upload process and response parsing.
+ *
+ * <p>This utility is used by both {@link AppUploader} and {@link TestSuiteUploader} to handle file
+ * uploads to the LambdaTest platform.
+ */
 public final class UploaderUtil {
+    /** Private constructor to prevent instantiation of this utility class. */
     private UploaderUtil() {
         throw new UnsupportedOperationException(
                 "This is a utility class and cannot be instantiated");
     }
 
+    /**
+     * Uploads a file to LambdaTest and returns its ID.
+     *
+     * @implNote This method sends the file to {@link Constants#API_URL} and handles the multipart
+     *     form data construction and response parsing.
+     * @param username The LambdaTest account username
+     * @param accessKey The LambdaTest account access key
+     * @param filePath The path to the file to be uploaded
+     * @return The ID of the uploaded file
+     * @throws IOException if there's an error during file upload or response parsing
+     */
     public static String uploadAndGetId(String username, String accessKey, String filePath)
             throws IOException {
+
         OkHttpClient client = new OkHttpClient();
 
         MediaType mediaType = MediaType.parse("application/octet-stream");