Add comments + some cosmetic changes

src/AbstractService.php

@@ -66,24 +66,30 @@ protected function delete(string $endpoint, array $options = [], ApiKey $apiKey
         );
     }
 
-    protected function jsonDecode(string $json, $assoc = true, $depth = 512, $options = 0)
+    /**
+     * Does the same as json_decode(), but with proper error handling
+     * @see \json_decode()
+     */
+    protected function jsonDecode(string $json, bool $assoc = true, int $depth = 512, int $options = 0)
     {
         if ($json === '' || $json === null) {
             return null;
         }
 
         $data = \json_decode($json, $assoc, $depth, $options);
 
-        if (JSON_ERROR_NONE !== json_last_error()) {
-            $last = json_last_error();
-            $message = 'Unable to parse JSON data: '.json_last_error_msg();
-            throw new JsonDecodingError($message, $last);
+        $lastJsonError = json_last_error();
+        if (JSON_ERROR_NONE !== $lastJsonError) {
+            throw new JsonDecodingError(
+                'Unable to parse JSON data: '.json_last_error_msg(),
+                $lastJsonError
+            );
         }
 
         return $data;
     }
 
-    private function addAuth(array $options, ?ApiKey $apiKey):array
+    private function addAuth(array $options, ?ApiKey $apiKey): array
     {
         if ($apiKey) {
             $options['headers']['Authorization'] = 'token '.$apiKey->getKey();

tests/AbstractServiceTest.php

@@ -19,13 +19,14 @@ class AbstractServiceTest extends TestCase
 {
     public function testInvalidJsonProcessing()
     {
+        // Create a Guzzle client which will send back just one mocked response with malformed JSON.
         $mock = new MockHandler([
             new Response(200, [], '{"malformedJSON":[]]}'),
         ]);
-
         $handler = HandlerStack::create($mock);
         $client = new Client(['handler' => $handler]);
 
+        // We want a proper exception, not a fatal error nor a silent fail.
         $this->expectException(JsonDecodingError::class);
         (new TestService($client))->getTest();
     }

tests/TestService.php

@@ -10,6 +10,9 @@
 
 use Wizaplace\AbstractService;
 
+/**
+ * Dummy service, here to test generic features not tied to any specific service
+ */
 class TestService extends AbstractService
 {
     public function getTest()