From d94a8172541b116a0e808e960d247f596e387f39 Mon Sep 17 00:00:00 2001
From: Maria Martinez <maria.martinez@gov.bc.ca>
Date: Tue, 3 Dec 2024 11:55:53 -0800
Subject: [PATCH] Added more javadocs

---
 .../controller/client/ClientController.java   | 49 +++++++++++++++++--
 1 file changed, 46 insertions(+), 3 deletions(-)

diff --git a/backend/src/main/java/ca/bc/gov/app/controller/client/ClientController.java b/backend/src/main/java/ca/bc/gov/app/controller/client/ClientController.java
index 84d6bb406..bdb6d3f20 100644
--- a/backend/src/main/java/ca/bc/gov/app/controller/client/ClientController.java
+++ b/backend/src/main/java/ca/bc/gov/app/controller/client/ClientController.java
@@ -36,6 +36,17 @@ public class ClientController {
   private final ClientService clientService;
   private final ClientLegacyService clientLegacyService;
 
+  /**
+   * Retrieves the details of a client based on the provided incorporation number.
+   *
+   * <p>This endpoint is used to fetch client details by their incorporation number. The request is
+   * authenticated using a JWT, and additional information (such as user ID, business ID, and
+   * provider) is extracted from the token to authorize the request.
+   *
+   * @param clientNumber the incorporation number of the client whose details are being requested
+   * @param principal the JWT authentication token containing user and business information
+   * @return a {@link Mono} emitting the {@link ClientDetailsDto} containing the client's details
+   */
   @GetMapping("/{clientNumber}")
   public Mono<ClientDetailsDto> getClientDetailsByIncorporationNumber(
       @PathVariable String clientNumber,
@@ -81,6 +92,18 @@ public Mono<ForestClientDetailsDto> getClientDetailsByClientNumber(
             JwtPrincipalUtil.getGroups(principal));
   }
   
+  /**
+   * Performs a full-text search for clients based on the provided keyword, with pagination support.
+   *
+   * <p>This endpoint allows searching for clients by a keyword. The results are paginated, and the 
+   * total count of matching records is included in the response headers.
+   *
+   * @param page the page number to retrieve (default is 0)
+   * @param size the number of records per page (default is 10)
+   * @param keyword the keyword to search for (default is an empty string, which returns all records)
+   * @param serverResponse the HTTP response to include the total count of records in the headers
+   * @return a {@link Flux} emitting {@link ClientListDto} objects containing the search results
+   */
   @GetMapping("/search")
   public Flux<ClientListDto> fullSearch(
       @RequestParam(required = false, defaultValue = "0") int page,
@@ -124,24 +147,44 @@ public Flux<ClientLookUpDto> findByClientName(@PathVariable String name) {
         .map(client -> client.withName(WordUtils.capitalize(client.name())));
   }
 
+  /**
+   * Finds a client based on their registration number.
+   *
+   * <p>This endpoint retrieves client information by searching for a registration number. If no 
+   * client is found, an error is returned.
+   *
+   * @param registrationNumber the registration number of the client to look up
+   * @return a {@link Mono} emitting the {@link ClientLookUpDto} if found, or an error if no data exists
+   */
   @GetMapping(value = "/incorporation/{registrationNumber}")
   public Mono<ClientLookUpDto> findByRegistrationNumber(
       @PathVariable String registrationNumber) {
     log.info("Requesting a client with registration number {} from the client service.",
-        registrationNumber);
+             registrationNumber);
     return clientService
         .findByClientNameOrIncorporation(registrationNumber)
         .next()
         .switchIfEmpty(Mono.error(new NoClientDataFound(registrationNumber)));
   }
 
+  /**
+   * Searches for an individual client by user ID and last name.
+   *
+   * <p>This endpoint fetches an individual client using their user ID and last name. The request is 
+   * validated against existing records in the system.
+   *
+   * @param userId the unique identifier of the individual to search for
+   * @param lastName the last name of the individual to search for
+   * @return a {@link Mono} indicating completion, or an error if the individual is not found
+   */
   @GetMapping(value = "/individual/{userId}")
   public Mono<Void> findByIndividual(
       @PathVariable String userId,
       @RequestParam String lastName
   ) {
-    log.info("Receiving request to search individual with id {} and last name {}", userId,
-        lastName);
+    log.info("Receiving request to search individual with id {} and last name {}", 
+             userId,
+             lastName);
     return clientService.findByIndividual(userId, lastName);
   }