fix(docs): fix Documentation

src/main/scala/api/endpoints/preprocessor/PreprocessorEndpoints.scala

@@ -17,12 +17,16 @@ import core.domain.preprocessor.{MechanismDetails, Reaction, ReactionDetails}
 import core.errors.http.preprocessor.ReactionError
 
 /**
- * Defines the HTTP routes for handling reactions and mechanisms in the preprocessor.
+ * Defines the HTTP routes for handling reactions and mechanisms.
+ *
+ * This class provides endpoints for performing CRUD operations on reactions and retrieving mechanism details. Each
+ * endpoint calls the appropriate service, and returns a response in JSON format.
  *
  * @param reactionService
- *   The service that handles reactions-related operations.
+ *   The service responsible for handling reaction-related operations, such as fetching, creating, and deleting
+ *   reactions.
  * @param mechanismService
- *   The service that handles mechanisms-related operations.
+ *   The service responsible for handling mechanism-related operations, such as fetching mechanism details.
  */
 class PreprocessorEndpoints(
   reactionService:  ReactionService[IO],
@@ -32,10 +36,19 @@ class PreprocessorEndpoints(
   /**
    * HTTP GET route for fetching a reaction by its ID.
    *
+   * Endpoint: `/api/reaction/{id}`
+   *
+   * This route validates the provided ID, fetches the reaction details from the `ReactionService`, and returns the
+   * details in JSON format. If the ID is invalid or the reaction is not found, it returns an appropriate error
+   * response.
+   *
    * @param id
-   *   The ID of the reaction to fetch.
+   *   The string representation of the reaction ID to fetch.
    * @return
-   *   A `ReactionDetails` object in JSON format or an appropriate error response.
+   *   - `200 OK` with the `ReactionDetails` object in JSON format if the reaction is found.
+   *   - `400 Bad Request` if the ID is invalid.
+   *   - `404 Not Found` if no reaction with the given ID exists.
+   *   - `500 Internal Server Error` if an unexpected error occurs.
    */
   private val getReactionRoute: HttpRoutes[IO] = HttpRoutes.of[IO] {
     case GET -> Root / "reaction" / id =>
@@ -54,10 +67,17 @@ class PreprocessorEndpoints(
   /**
    * HTTP POST route for creating a new reaction.
    *
+   * Endpoint: `/api/reaction`
+   *
+   * This route reads a `Reaction` object from the request body, passes it to the `ReactionService` to create a new
+   * reaction, and returns the created reaction details in JSON format.
+   *
    * @param req
    *   The HTTP request containing the `Reaction` object in the body.
    * @return
-   *   The created `Reaction` object in JSON format or an appropriate error response.
+   *   - `201 Created` with the created `Reaction` object in JSON format on success.
+   *   - `400 Bad Request` if the request body is invalid or creation fails.
+   *   - `500 Internal Server Error` if an unexpected error occurs.
    */
   private val postReactionRoute: HttpRoutes[IO] = HttpRoutes.of[IO] {
     case req @ POST -> Root / "reaction" =>
@@ -74,10 +94,17 @@ class PreprocessorEndpoints(
   /**
    * HTTP DELETE route for deleting a reaction by its ID.
    *
+   * Endpoint: `/api/reaction/{id}`
+   *
+   * This route validates the provided ID, deletes the reaction using the `ReactionService`, and returns an appropriate
+   * response. If the ID is invalid or the deletion fails, an error response is returned.
+   *
    * @param id
-   *   The ID of the reaction to delete.
+   *   The string representation of the reaction ID to delete.
    * @return
-   *   HTTP 204 No Content on success, or an appropriate error response.
+   *   - `204 No Content` if the reaction is successfully deleted.
+   *   - `400 Bad Request` if the ID is invalid or deletion fails.
+   *   - `500 Internal Server Error` if an unexpected error occurs.
    */
   private val deleteReactionRoute: HttpRoutes[IO] = HttpRoutes.of[IO] {
     case DELETE -> Root / "reaction" / id =>
@@ -94,10 +121,19 @@ class PreprocessorEndpoints(
   /**
    * HTTP GET route for fetching a mechanism by its ID.
    *
+   * Endpoint: `/api/mechanism/{id}`
+   *
+   * This route validates the provided ID, fetches the mechanism details from the `MechanismService`, and returns the
+   * details in JSON format. If the ID is invalid or the mechanism is not found, it returns an appropriate error
+   * response.
+   *
    * @param id
-   *   The ID of the mechanism to fetch.
+   *   The string representation of the mechanism ID to fetch.
    * @return
-   *   A `MechanismDetails` object in JSON format or an appropriate error response.
+   *   - `200 OK` with the `MechanismDetails` object in JSON format if the mechanism is found.
+   *   - `400 Bad Request` if the ID is invalid.
+   *   - `404 Not Found` if no mechanism with the given ID exists.
+   *   - `500 Internal Server Error` if an unexpected error occurs.
    */
   private val getMechanismRoute: HttpRoutes[IO] = HttpRoutes.of[IO] {
     case GET -> Root / "mechanism" / id =>
@@ -113,8 +149,22 @@ class PreprocessorEndpoints(
       }
   }
 
+  /**
+   * Validates the given string as an integer ID.
+   *
+   * @param id
+   *   The string to validate.
+   * @return
+   *   An `Option[Int]` containing the valid integer ID, or `None` if the validation fails.
+   */
   private def validateId(id: String): Option[Int] = id.toIntOption
 
+  /**
+   * Combines all defined HTTP routes and applies middleware for logging.
+   *
+   * @return
+   *   A single `HttpRoutes[IO]` instance containing all endpoints.
+   */
   val routes: HttpRoutes[IO] = Logger.httpRoutes(logHeaders = false, logBody = true)(
     Router(
       "/api" -> (getReactionRoute <+> postReactionRoute <+> deleteReactionRoute <+> getMechanismRoute)

src/main/scala/app/Main.scala

@@ -31,20 +31,25 @@ import app.units.ServiceResources.{
 object Main extends IOApp {
 
   /**
-   * Runs the application, setting up all required resources.
+   * Configures and manages the lifecycle of all resources and services required for the application.
+   *
+   * This method initialises resources such as the actor system, HTTP clients, distributed cache, services, and server.
+   * It ensures proper resource management by leveraging `Resource` for initialisation and cleanup.
    *
    * @param config
-   *   The configuration loader used to provide application settings.
+   *   The configuration loader that provides application-specific settings, such as HTTP endpoints, client
+   *   configurations, and server properties.
    * @param ec
-   *   The `ExecutionContext` used for asynchronous operations.
+   *   The `ExecutionContext` used to handle asynchronous operations across the application.
    * @param system
-   *   The `ActorSystem` used for managing Akka-based concurrency.
+   *   The `ActorSystem` used for Akka-based concurrency and distributed data.
+   * @param selfUniqueAddress
+   *   The unique address of the current actor system, used for distributed data in a cluster.
    * @param logger
-   *   An implicit logger instance for logging lifecycle events and errors during resource creation and application
-   *   runtime.
+   *   An implicit logger instance for recording lifecycle events, debugging, and error handling.
    * @return
-   *   A `Resource[IO, Unit]` that encapsulates the full lifecycle of the application, ensuring that all resources are
-   *   properly initialised and released.
+   *   A `Resource[IO, Unit]` that encapsulates the application's full lifecycle. This includes initialisation, running
+   *   the server, and ensuring all resources are properly cleaned up when the application terminates.
    */
   private def runApp(
     config: ConfigLoader

src/main/scala/app/units/ServiceResources.scala

@@ -1,5 +1,8 @@
 package app.units
 
+import akka.actor.ActorSystem
+import akka.cluster.ddata.SelfUniqueAddress
+
 import cats.effect.{IO, Resource}
 
 import core.services.cache.CacheService
@@ -10,27 +13,28 @@ import core.services.flow.ReaktoroService
 import org.http4s.client.Client
 import org.http4s.Uri
 import org.typelevel.log4cats.Logger
-import akka.actor.ActorSystem
-import akka.cluster.ddata.SelfUniqueAddress
 
 /**
  * Provides resources for service initialisation and lifecycle management.
+ *
+ * This object contains methods to create managed resources for various application services, ensuring proper
+ * initialisation and cleanup using the `Resource` abstraction.
  */
 object ServiceResources {
 
   /**
    * Creates a managed resource for the `MechanismService`.
    *
    * @param cacheService
-   *   The `CacheService` instance used for caching mechanisms.
+   *   The distributed cache service used for storing and retrieving mechanisms.
    * @param client
-   *   The `Client[IO]` instance used for HTTP requests.
+   *   The HTTP client instance used to make requests to the mechanism service endpoints.
    * @param baseUri
-   *   The base `Uri` for the mechanism service endpoints.
+   *   The base URI for the mechanism service's API endpoints.
    * @param logger
    *   An implicit logger instance for logging lifecycle events and errors during the resource's creation and release.
    * @return
-   *   A `Resource[IO, MechanismService[IO]]` that manages the lifecycle of the `MechanismService` instance.
+   *   A `Resource[IO, MechanismService[IO]]` that ensures the lifecycle of the `MechanismService` is managed correctly.
    */
   def mechanismServiceResource(
     cacheService: DistributedCacheService[IO],
@@ -50,15 +54,15 @@ object ServiceResources {
    * Creates a managed resource for the `ReactionService`.
    *
    * @param cacheService
-   *   The `CacheService` instance used for caching reactions.
+   *   The distributed cache service used for storing and retrieving reactions.
    * @param client
-   *   The `Client[IO]` instance used for HTTP requests.
+   *   The HTTP client instance used to make requests to the reaction service endpoints.
    * @param baseUri
-   *   The base `Uri` for the reaction service endpoints.
+   *   The base URI for the reaction service's API endpoints.
    * @param logger
    *   An implicit logger instance for logging lifecycle events and errors during the resource's creation and release.
    * @return
-   *   A `Resource[IO, ReactionService[IO]]` that manages the lifecycle of the `ReactionService` instance.
+   *   A `Resource[IO, ReactionService[IO]]` that ensures the lifecycle of the `ReactionService` is managed correctly.
    */
   def reactionServiceResource(
     cacheService: DistributedCacheService[IO],
@@ -78,15 +82,15 @@ object ServiceResources {
    * Creates a managed resource for the `ReaktoroService`.
    *
    * @param reactionService
-   *   The `ReactionService` instance used as a dependency for the `ReaktoroService`.
+   *   The reaction service used to provide dependencies for the `ReaktoroService`.
    * @param client
-   *   The `Client[IO]` instance used for HTTP requests.
+   *   The HTTP client instance used to make requests to the Reaktoro service endpoints.
    * @param baseUri
-   *   The base `Uri` for the Reaktoro service endpoints.
+   *   The base URI for the Reaktoro service's API endpoints.
    * @param logger
    *   An implicit logger instance for logging lifecycle events and errors during the resource's creation and release.
    * @return
-   *   A `Resource[IO, ReaktoroService[IO]]` that manages the lifecycle of the `ReaktoroService` instance.
+   *   A `Resource[IO, ReaktoroService[IO]]` that ensures the lifecycle of the `ReaktoroService` is managed correctly.
    */
   def reaktoroServiceResource(
     reactionService: ReactionService[IO],
@@ -108,24 +112,30 @@ object ServiceResources {
    * @param logger
    *   An implicit logger instance for logging lifecycle events and errors during the resource's creation and release.
    * @return
-   *   A `Resource[IO, CacheService[IO]]` that manages the lifecycle of the `CacheService` instance.
+   *   A `Resource[IO, CacheService[IO]]` that ensures the lifecycle of the `CacheService` is managed correctly.
    */
   def cacheServiceResource(
     implicit logger: Logger[IO]
   ): Resource[IO, CacheService[IO]] =
     Resource.make(
-      logger.info("Creating Cache Service") *> IO(new CacheService[IO])
+      logger.info("Creating Cache Service") *>
+        IO(new CacheService[IO])
     )(_ =>
       logger.info("Shutting down Cache Service").handleErrorWith(_ => IO.unit)
     )
 
   /**
    * Creates a managed resource for the `DistributedCacheService`.
    *
+   * @param system
+   *   The `ActorSystem` used for Akka-based concurrency and distributed data.
+   * @param selfUniqueAddress
+   *   The unique address of the current actor system instance, used for distributed data in a cluster.
    * @param logger
    *   An implicit logger instance for logging lifecycle events and errors during the resource's creation and release.
    * @return
-   *   A `Resource[IO, DistributedCacheService[IO]]` that manages the lifecycle of the `CacheService` instance.
+   *   A `Resource[IO, DistributedCacheService[IO]]` that ensures the lifecycle of the `DistributedCacheService` is
+   *   managed correctly.
    */
   def distributedCacheServiceResource(
     system: ActorSystem,
@@ -134,9 +144,10 @@ object ServiceResources {
     implicit logger: Logger[IO]
   ): Resource[IO, DistributedCacheService[IO]] =
     Resource.make(
-      logger.info("Creating Cache Service") *> IO(new DistributedCacheService[IO](system, selfUniqueAddress))
+      logger.info("Creating Distributed Cache Service") *>
+        IO(new DistributedCacheService[IO](system, selfUniqueAddress))
     )(_ =>
-      logger.info("Shutting down Cache Service").handleErrorWith(_ => IO.unit)
+      logger.info("Shutting down Distributed Cache Service").handleErrorWith(_ => IO.unit)
     )
 
 }