doc: add javadoc to *dto.java

src/main/java/io/github/js0ny/ilp_coursework/data/DistanceRequestDto.java

@@ -1,4 +1,13 @@
 package io.github.js0ny.ilp_coursework.data;
 
+/**
+ * Represents the data transfer object for a distance operation request.
+ * <p>
+ * This record encapsulates the data for several endpoints that involves two {@code LngLatDto}
+ * and serves as the data contract for those API operation
+ *
+ * @param position1 Nested object of {@link LngLatDto}
+ * @param position2 Nested object of {@link LngLatDto}
+ */
 public record DistanceRequestDto(LngLatDto position1, LngLatDto position2) {
 }

src/main/java/io/github/js0ny/ilp_coursework/data/LngLatDto.java

@@ -1,5 +1,11 @@
 package io.github.js0ny.ilp_coursework.data;
 
+/**
+ * Represents the data transfer object for a point or coordinate
+ * that defines by a longitude and latitude
+ *
+ * @param lng longitude of the coordinate/point
+ * @param lat latitude of the coordinate/point
+ */
 public record LngLatDto(double lng, double lat) {
-
 }

src/main/java/io/github/js0ny/ilp_coursework/data/MovementRequestDto.java

@@ -2,7 +2,14 @@ package io.github.js0ny.ilp_coursework.data;
 
 /**
  * Represents the data transfer object for a movement action request.
- * Used for endpoint: `/api/v1/nextPosition`
+ * <p>
+ * This record encapsulates the data for endpoint /api/v1/nextPosition and serves as the data contract for
+ * this API operation
+ *
+ * @param start The starting coordinate of the movement
+ * @param angle The angle to movement in degree. This corresponds to compass directions.
+ *              For example: 0 for East, 90 for North
+ * @see io.github.js0ny.ilp_coursework.controller.ApiController#getNextPosition(MovementRequestDto)
  */
 public record MovementRequestDto(LngLatDto start, double angle) {
 }

src/main/java/io/github/js0ny/ilp_coursework/data/RegionCheckRequestDto.java

@@ -1,5 +1,16 @@
 package io.github.js0ny.ilp_coursework.data;
 
+/**
+ * Represents the data transfer object for a region check request.
+ * <p>
+ * This record encapsulates the data for endpoint /api/v1/isInRegion and serves as the data contract for
+ * this API operation
+ * <p>
+ *
+ * @param position The coordinate to be checked
+ * @param region   The region for the check.
+ *                 This is a nested object represented by {@link RegionDto}
+ * @see io.github.js0ny.ilp_coursework.controller.ApiController#getIsInRegion(RegionCheckRequestDto)
+ */
 public record RegionCheckRequestDto(LngLatDto position, RegionDto region) {
-
 }

src/main/java/io/github/js0ny/ilp_coursework/data/RegionDto.java

@@ -3,16 +3,40 @@ package io.github.js0ny.ilp_coursework.data;
 import java.util.List;
 import java.util.Objects;
 
+/**
+ * Represents the data transfer object for a region definition
+ * <p>
+ * This record encapsulates the data for calculating if a coordinate is inside the region
+ * <p>
+ * A built-in method <code>isClosedTo</code> is defined to check this DTO is valid or not in the mean of closing polygon
+ *
+ * @param name     The human-readable name for the region
+ * @param vertices list of coordinates that forms a polygon as a region.
+ *                 <p>
+ *                 In order to define a valid region, the last element of the list should be the same as the first, or
+ *                 known as closed
+ * @see RegionCheckRequestDto
+ * @see io.github.js0ny.ilp_coursework.service.GpsCalculationService#checkIsInRegion(LngLatDto, RegionDto)
+ */
 public record RegionDto(String name, List<LngLatDto> vertices) {
+    /**
+     * Magic number 4: For a polygon, 3 edges is required.
+     * <p>
+     * In this dto, edges + 1 vertices is required.
+     */
+    private static final int MINIMUM_VERTICES = 4;
 
+    /**
+     * Method to check if the region has a valid polygon by checking if the <code>vertices</code> forms a closed polygon
+     *
+     * @return {@code true} if the <code>vertices</code> are able to form a polygon and form a closed polygon
+     */
     public boolean isClosed() {
-        // Magic number 4: For a polygon, 3 edges is required.
-        // In this dto, edges + 1 vertices is required.
-        if (vertices == null || vertices.size() < 4) {
+        if (vertices == null || vertices.size() < MINIMUM_VERTICES) {
             return false;
         }
-        LngLatDto first = vertices.get(0);
-        LngLatDto last = vertices.get(vertices.size() - 1);
+        LngLatDto first = vertices.getFirst();
+        LngLatDto last = vertices.getLast();
         return Objects.equals(last, first);
     }
 

src/main/java/io/github/js0ny/ilp_coursework/exception/GlobalExceptionHandler.java

@@ -25,10 +25,4 @@ public class GlobalExceptionHandler {
         return Map.of("status", "400", "error", errorMessage);
     }
 
-    // @ExceptionHandler(NullPointerException.class)
-    // @ResponseStatus(HttpStatus.BAD_REQUEST)
-    // public Map<String, String> handleNullPointerException(NullPointerException
-    // ex) {
-    // return Map.of("error", "Invalid JSON request body.");
-    // }
 }