docs: Add javadoc to Controller

src/main/java/io/github/js0ny/ilp_coursework/controller/ApiController.java

@@ -13,22 +13,44 @@ import io.github.js0ny.ilp_coursework.data.RegionCheckRequestDto;
 import io.github.js0ny.ilp_coursework.data.RegionDto;
 import io.github.js0ny.ilp_coursework.service.GpsCalculationService;
 
+/**
+ * Main REST Controller for the ILP Coursework 1 application.
+ * <p>
+ * This class handles all incoming HTTP requests for the API under {@code /api/v1} path.
+ * This is responsible for mapping requests to the appropriate service method and returning the results as responses.
+ * The business logic is delegated to {@link GpsCalculationService}
+ */
 @RestController
 @RequestMapping("/api/v1")
 public class ApiController {
 
-    private final String myUid = "s2522255";
     private final GpsCalculationService gpsService;
 
+    /**
+     * Constructor of the {@code ApiController} with the business logic dependency {@code GpsCalculationService}
+     *
+     * @param gpsService The service component that contains all business logic, injected by Spring's DI.
+     */
     public ApiController(GpsCalculationService gpsService) {
         this.gpsService = gpsService;
     }
 
+    /**
+     * Handles GET requests to retrieve the student's Unique ID
+     *
+     * @return A string representing the student ID starting with s
+     */
     @GetMapping("/uid")
     public String getUid() {
-        return myUid;
+        return "s2522255";
     }
 
+    /**
+     * Handles POST requests to get the distance between two positions
+     *
+     * @param request A {@link DistanceRequestDto} containing the two coordinates
+     * @return A {@code double} representing the calculated distance
+     */
     @PostMapping("/distanceTo")
     public double getDistance(@RequestBody DistanceRequestDto request) {
 
@@ -37,6 +59,12 @@ public class ApiController {
         return gpsService.calculateDistance(position1, position2);
     }
 
+    /**
+     * Handles POST requests to check if the two coordinates are close to each other
+     *
+     * @param request A {@link DistanceRequestDto} containing the two coordinates
+     * @return {@code true} if the distance is less than the predefined threshold, {@code false} otherwise
+     */
     @PostMapping("/isCloseTo")
     public boolean getIsCloseTo(@RequestBody DistanceRequestDto request) {
         LngLatDto position1 = request.position1();
@@ -44,6 +72,12 @@ public class ApiController {
         return gpsService.isCloseTo(position1, position2);
     }
 
+    /**
+     * Handles POST requests to get the next position after an angle of movement
+     *
+     * @param request A {@link MovementRequestDto} containing the start coordinate and angle of the movement.
+     * @return A {@link LngLatDto} representing the destination
+     */
     @PostMapping("/nextPosition")
     public LngLatDto getNextPosition(@RequestBody MovementRequestDto request) {
         LngLatDto start = request.start();
@@ -51,6 +85,12 @@ public class ApiController {
         return gpsService.nextPosition(start, angle);
     }
 
+    /**
+     * Handles POST requests to check if a point is inside a given region
+     *
+     * @param request A {@link RegionCheckRequestDto} containing the coordinate and the region
+     * @return {@code true} if the coordinate is inside the region, {@code false} otherwise
+     */
     @PostMapping("/isInRegion")
     public boolean getIsInRegion(@RequestBody RegionCheckRequestDto request) {
         LngLatDto position = request.position();