Adding javadocs, re-implemented find country by localised name (nativ…

…e name)

Fix #3

library/src/main/java/com/tomaytotomato/LocationService.java

@@ -121,12 +121,12 @@ public Optional<Country> findCountryByName(String countryName) {
   }
 
   @Override
-  public Optional<Country> findCountryByNativeName(String nativeName) {
-    if (Objects.isNull(nativeName) || nativeName.isEmpty()) {
+  public Optional<Country> findCountryByLocalisedName(String localisedName) {
+    if (Objects.isNull(localisedName) || localisedName.isEmpty()) {
       throw new IllegalArgumentException("Country Native Name cannot be null or empty");
     }
-    nativeName = textNormaliser.normalise(nativeName);
-    return Optional.ofNullable(countryNativeNameToCountry.get(nativeName));
+    localisedName = textNormaliser.normalise(localisedName);
+    return Optional.ofNullable(countryNativeNameToCountry.get(localisedName));
   }
 
   @Override

library/src/main/java/com/tomaytotomato/usecase/FindCity.java

@@ -4,11 +4,31 @@
 import java.util.List;
 import java.util.Optional;
 
+/**
+ * Interface for finding cities based on various criteria.
+ */
 public interface FindCity {
 
+  /**
+   * Find a city by its unique identifier (ID).
+   *
+   * @param id the unique identifier of the city
+   * @return an Optional containing the City if found, otherwise an empty Optional
+   */
   Optional<City> findCityById(Integer id);
 
+  /**
+   * Retrieve a list of all cities available in the data source.
+   *
+   * @return a List of all City objects
+   */
   List<City> findAllCities();
 
+  /**
+   * Retrieve a list of all cities that match the specified city name.
+   *
+   * @param cityName the name of the city
+   * @return a List of City objects that match the specified city name
+   */
   List<City> findAllCitiesByCityName(String cityName);
 }

library/src/main/java/com/tomaytotomato/usecase/FindCountry.java

@@ -4,20 +4,76 @@
 import java.util.List;
 import java.util.Optional;
 
+/**
+ * Interface for finding countries based on various criteria.
+ */
 public interface FindCountry {
 
+  /**
+   * Find a country by its unique identifier (ID), which represents a specific country.
+   * e.g. Afghanistan - 1, Belgium - 22
+   *
+   * @param id the unique identifier of the country
+   * @return an Optional containing the Country if found, otherwise an empty Optional
+   */
   Optional<Country> findCountryById(Integer id);
 
+  /**
+   * Find a country by its official name.
+   *
+   * @param countryName the official name of the country
+   * @return an Optional containing the Country if found, otherwise an empty Optional
+   */
   Optional<Country> findCountryByName(String countryName);
 
-  Optional<Country> findCountryByNativeName(String nativeName);
+  /**
+   * Finds a country by its localized or native name.
+   * <p>
+   * This method searches for a country using its localized name, which may vary
+   * depending on the language or region. For example, the country of Belgium
+   * may be referred to as:
+   * <ul>
+   *   <li>"Belgien" (German)</li>
+   *   <li>"Belgique" (French)</li>
+   *   <li>"Belgium" (English)</li>
+   * </ul>
+   * </p>
+   *
+   * @param localisedName the localized or native name of the country
+   * @return an Optional containing the Country if found, otherwise an empty Optional
+   */
+  Optional<Country> findCountryByLocalisedName(String localisedName);
 
+
+  /**
+   * Retrieve a list of all countries available in the data source.
+   *
+   * @return a List of all Country objects
+   */
   List<Country> findAllCountries();
 
+  /**
+   * Find a country by its ISO 3166-1 alpha-2 code, a two-letter country code.
+   *
+   * @param iso2Code the ISO 3166-1 alpha-2 code of the country
+   * @return an Optional containing the Country if found, otherwise an empty Optional
+   */
   Optional<Country> findCountryByISO2Code(String iso2Code);
 
+  /**
+   * Find a country by its ISO 3166-1 alpha-3 code, a three-letter country code.
+   *
+   * @param iso3Code the ISO 3166-1 alpha-3 code of the country
+   * @return an Optional containing the Country if found, otherwise an empty Optional
+   */
   Optional<Country> findCountryByISO3Code(String iso3Code);
 
+  /**
+   * Retrieve a list of all countries that have a state with the specified name.
+   *
+   * @param stateName the name of the state
+   * @return a List of Country objects that contain the specified state name
+   */
   List<Country> findAllCountriesByStateName(String stateName);
 
 }

library/src/main/java/com/tomaytotomato/usecase/FindState.java

@@ -4,12 +4,33 @@
 import java.util.List;
 import java.util.Optional;
 
+/**
+ * Interface for finding states based on various criteria.
+ */
 public interface FindState {
 
+  /**
+   * Find a state by its unique identifier (ID).
+   *
+   * @param id the unique identifier of the state
+   * @return an Optional containing the State if found, otherwise an empty Optional
+   */
   Optional<State> findStateById(Integer id);
 
+  /**
+   * Retrieve a list of all states that match the specified state name.
+   *
+   * @param name the name of the state
+   * @return a List of State objects that match the specified state name
+   */
   List<State> findAllStatesByStateName(String name);
 
+  /**
+   * Retrieve a list of all states that match the specified state code.
+   *
+   * @param stateCode the code of the state
+   * @return a List of State objects that match the specified state code
+   */
   List<State> findAllStatesByStateCode(String stateCode);
 
 }

library/src/main/java/com/tomaytotomato/usecase/SearchLocation.java

@@ -3,14 +3,34 @@
 import com.tomaytotomato.model.Location;
 import java.util.List;
 
+/**
+ * Interface for searching locations based on a free-text input.
+ */
 public interface SearchLocation {
 
   /**
-   * Searches for locations based off a text input e.g. - "Canada, Alberta" - "Santa Clara, CA, USA"
-   * - "Glasgow, GB" - "Glasgow, Scotland" - "San Francisco"
+   * Searches for locations based on a free-text input.
+   * <p>
+   * This method accepts input strings that can be formatted in various ways, such as:
+   * <ul>
+   *   <li>"Canada, Alberta"</li>
+   *   <li>"Santa Clara, CA, USA"</li>
+   *   <li>"Glasgow, GB"</li>
+   *   <li>"Glasgow, Scotland"</li>
+   *   <li>"San Francisco"</li>
+   * </ul>
+   * The input can be formatted or unformatted, for example:
+   * <ul>
+   *   <li>"uk, glasgow"</li>
+   *   <li>"glasgow UNITED KINGDOM"</li>
+   *   <li>"USA san Francisco"</li>
+   *   <li>"san Francisco United States"</li>
+   * </ul>
+   * The method normalizes and tokenizes the input to find matching locations.
+   * </p>
    *
-   * @param text free text input
-   * @return list of locations that match text input
+   * @param text the free-text input used to search for locations
+   * @return a List of Location objects that match the input text
    */
   List<Location> search(String text);
 

library/src/test/java/com/tomaytotomato/usecase/FindCountryTest.java

@@ -110,28 +110,30 @@ void findCountryByName_WhenCountryNameExists_ThenReturnCountry(String countryNam
   }
 
 
-  @DisplayName("Find Country By Native Name, when country name is null or blank, then throw exception")
+  @DisplayName("Find Country By Localised Name, when country name is null or blank, then throw exception")
   @Test
   void findCountryByNativeName_WhenNameIsNull_ThenThrowException() {
-    assertThatThrownBy(() -> locationService.findCountryByNativeName(null))
+    assertThatThrownBy(() -> locationService.findCountryByLocalisedName(null))
         .isInstanceOf(IllegalArgumentException.class)
-        .hasMessage("Country Native Name cannot be null or empty");
+        .hasMessage("Country Localised Name cannot be null or empty");
   }
 
 
-  @DisplayName("Find Country By Native Name, when native name exists then return country")
+  @DisplayName("Find Country By Localised Name, when name exists then return country")
   @ParameterizedTest
   @CsvSource({
       "United Kingdom, United Kingdom",
       "Cote D'Ivoire, Ivory Coast",
       "Deutschland, Germany",
       "Nederland, Netherlands",
-
+      "Belgique, Belgium",
+      "Belgio, Belgium",
+      "벨기에, Belgium"
   })
-  void findCountryByNativeName_WhenNativeNameExists_ThenReturnCountry(String nativeName, String expectedCountryName) {
+  void findCountryByNativeName_WhenNativeNameExists_ThenReturnCountry(String localisedName, String expectedCountryName) {
 
     // When
-    var result = locationService.findCountryByNativeName(nativeName);
+    var result = locationService.findCountryByLocalisedName(localisedName);
 
     // Then
     assertThat(result).isNotEmpty().get().extracting("name").isEqualTo(expectedCountryName);