From 10d1d3c3183fb83e17b1629dcf5e634e6c56c089 Mon Sep 17 00:00:00 2001
From: brabli <67018167+Brabli@users.noreply.github.com>
Date: Mon, 5 Aug 2024 14:50:26 +0100
Subject: [PATCH] Update docblocks

---
 src/Interface/Entity/GeocodeInterface.php |  7 +++++++
 src/Service/Geocoder.php                  | 13 ++++++++++---
 src/Trait/Entity/GeocodeTrait.php         |  5 -----
 3 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/src/Interface/Entity/GeocodeInterface.php b/src/Interface/Entity/GeocodeInterface.php
index a94d4fa..d6f2429 100644
--- a/src/Interface/Entity/GeocodeInterface.php
+++ b/src/Interface/Entity/GeocodeInterface.php
@@ -4,6 +4,9 @@ declare(strict_types=1);
 
 namespace Pcm\GeocodeBundle\Interface\Entity;
 
+/**
+ * Defines latitude and longitude getters and setters
+ */
 interface GeocodeInterface
 {
     public function getLatitude(): ?float;
@@ -14,5 +17,9 @@ interface GeocodeInterface
 
     public function setLongitude(float $lon): self;
 
+    /**
+     * @return bool True if both latitude and longitude is set
+     */
     public function isGeocoded(): bool;
 }
+
diff --git a/src/Service/Geocoder.php b/src/Service/Geocoder.php
index 37b306c..b363d29 100644
--- a/src/Service/Geocoder.php
+++ b/src/Service/Geocoder.php
@@ -10,6 +10,9 @@ use Pcm\GeocodeBundle\Model\GeoCoordinates;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
 use Symfony\Contracts\HttpClient\ResponseInterface;
 
+/**
+ * Find the geo-coordinates of a postcode
+ */
 final class Geocoder
 {
     private const string API_URL = "https://nominatim.openstreetmap.org/search";
@@ -17,12 +20,16 @@ final class Geocoder
     public function __construct(private HttpClientInterface $client) {}
 
     /**
-     * Convert a postcode into latitude and longitude. Returns null if conversion failed.
+     * Find and return the geo-coordinates of a postcode
      *
      * @param string $postcode
-     * @return null|GeoCoordinates
+     *
+     * @return GeoCoordinates
+     *
+     * @throws NoResultsFoundException when no results were found for the provided postcode
+     * @throws ApiErrorException when the API response contains an error
      */
-    public function geocodePostcode(string $postcode): ?GeoCoordinates
+    public function geocodePostcode(string $postcode): GeoCoordinates
     {
         $client = $this->createClient();
         $response = $this->makeApiRequest($client, $postcode);
diff --git a/src/Trait/Entity/GeocodeTrait.php b/src/Trait/Entity/GeocodeTrait.php
index 1548b5b..6457805 100644
--- a/src/Trait/Entity/GeocodeTrait.php
+++ b/src/Trait/Entity/GeocodeTrait.php
@@ -43,11 +43,6 @@ trait GeocodeTrait
         return $this;
     }
 
-    /**
-     * Returns true if both latitude and longitude have been set
-     *
-     * @return bool
-     */
     public function isGeocoded(): bool
     {
         return null !== $this->getLatitude() && null !== $this->getLongitude();