Ensures internal API documentation is complete

- Adds return type hints where needed.
- Adds docblocks and/or `@param`/`@return` annotations where needed.

Author: weierophinney

src/CommonProblemDetailsException.php

@@ -87,6 +87,11 @@ public function toArray() : array
         return $problem;
     }
 
+    /**
+     * Allow serialization via json_encode().
+     *
+     * @return array
+     */
     public function jsonSerialize()
     {
         return $this->toArray();

src/ConfigProvider.php

@@ -3,19 +3,14 @@
 namespace ProblemDetails;
 
 /**
- * The configuration provider for the ProblemDetails module
+ * Configuration provider for the package.
  *
  * @see https://docs.zendframework.com/zend-component-installer/
  */
 class ConfigProvider
 {
     /**
-     * Returns the configuration array
-     *
-     * To add a bit of a structure, each section is defined in a separate
-     * method which returns an array with its configuration.
-     *
-     * @return array
+     * Returns the configuration array.
      */
     public function __invoke() : array
     {
@@ -25,9 +20,7 @@ public function __invoke() : array
     }
 
     /**
-     * Returns the container dependencies
-     *
-     * @return array
+     * Returns the container dependencies.
      */
     public function getDependencies() : array
     {

src/ProblemDetailsException.php

@@ -5,7 +5,7 @@
 use JsonSerializable;
 
 /**
- * Define an exception type for generating Problem Details.
+ * Defines an exception type for generating Problem Details.
  */
 interface ProblemDetailsException extends JsonSerializable
 {

src/ProblemDetailsMiddleware.php

@@ -29,7 +29,7 @@ public function __construct(ProblemDetailsResponseFactory $responseFactory = nul
     /**
      * {@inheritDoc}
      */
-    public function process(ServerRequestInterface $request, DelegateInterface $delegate) : ResponseInterface
+    public function process(ServerRequestInterface $request, DelegateInterface $delegate)
     {
         // If we cannot provide a representation, act as a no-op.
         if (! $this->canActAsErrorHandler($request)) {
@@ -52,12 +52,14 @@ public function process(ServerRequestInterface $request, DelegateInterface $dele
         return $response;
     }
 
+    /**
+     * Can the middleware act as an error handler?
+     *
+     * Returns a boolean false if negotiation fails.
+     */
     private function canActAsErrorHandler(ServerRequestInterface $request) : bool
     {
         $accept = $request->getHeaderLine('Accept') ?: '*/*';
-        if (empty($accept)) {
-            return false;
-        }
 
         return null !== (new Negotiator())
             ->getBest($accept, ProblemDetailsResponseFactory::NEGOTIATION_PRIORITIES);

test/ConfigProviderTest.php

@@ -11,7 +11,7 @@
 
 class ConfigProviderTest extends TestCase
 {
-    public function testReturnsExpectedDependencies()
+    public function testReturnsExpectedDependencies() : void
     {
         $provider = new ConfigProvider();
         $config = $provider();

test/ProblemDetailsAssertionsTrait.php

@@ -7,7 +7,7 @@
 
 trait ProblemDetailsAssertionsTrait
 {
-    public function assertProblemDetails(array $expected, array $details)
+    public function assertProblemDetails(array $expected, array $details) : void
     {
         foreach ($expected as $key => $value) {
             $this->assertArrayHasKey(
@@ -25,7 +25,7 @@ public function assertProblemDetails(array $expected, array $details)
         }
     }
 
-    public function assertExceptionDetails(Throwable $e, array $details)
+    public function assertExceptionDetails(Throwable $e, array $details) : void
     {
         $this->assertArrayHasKey('class', $details);
         $this->assertSame(get_class($e), $details['class']);

test/ProblemDetailsExceptionTest.php

@@ -16,7 +16,7 @@ class ProblemDetailsExceptionTest extends TestCase
         'foo' => 'bar',
     ];
 
-    protected function setUp()
+    protected function setUp() : void
     {
         $this->exception = new class (
             $this->status,
@@ -38,7 +38,7 @@ public function __construct(int $status, string $detail, string $title, string $
         };
     }
 
-    public function testCanPullDetailsIndividually()
+    public function testCanPullDetailsIndividually() : void
     {
         $this->assertEquals($this->status, $this->exception->getStatus());
         $this->assertEquals($this->detail, $this->exception->getDetail());
@@ -47,7 +47,7 @@ public function testCanPullDetailsIndividually()
         $this->assertEquals($this->additional, $this->exception->getAdditionalData());
     }
 
-    public function testCanCastDetailsToArray()
+    public function testCanCastDetailsToArray() : void
     {
         $this->assertEquals([
             'status' => $this->status,
@@ -58,7 +58,7 @@ public function testCanCastDetailsToArray()
         ], $this->exception->toArray());
     }
 
-    public function testIsJsonSerializable()
+    public function testIsJsonSerializable() : void
     {
         $problem = json_decode(json_encode($this->exception), true);
 

test/ProblemDetailsMiddlewareFactoryTest.php

@@ -10,13 +10,13 @@
 
 class ProblemDetailsMiddlewareFactoryTest extends TestCase
 {
-    protected function setUp()
+    protected function setUp() : void
     {
         $this->container = $this->prophesize(ContainerInterface::class);
         $this->factory = new ProblemDetailsMiddlewareFactory();
     }
 
-    public function testCreatesMiddlewareWithoutResponseFactoryIfServiceDoesNotExist()
+    public function testCreatesMiddlewareWithoutResponseFactoryIfServiceDoesNotExist() : void
     {
         $this->container->has(ProblemDetailsResponseFactory::class)->willReturn(false);
         $this->container->get(ProblemDetailsResponseFactory::class)->shouldNotBeCalled();
@@ -31,7 +31,7 @@ public function testCreatesMiddlewareWithoutResponseFactoryIfServiceDoesNotExist
         );
     }
 
-    public function testCreatesMiddlewareUsingResponseFactoryService()
+    public function testCreatesMiddlewareUsingResponseFactoryService() : void
     {
         $responseFactory = $this->prophesize(ProblemDetailsResponseFactory::class)->reveal();
         $this->container->has(ProblemDetailsResponseFactory::class)->willReturn(true);

test/ProblemDetailsMiddlewareTest.php

@@ -16,14 +16,14 @@ class ProblemDetailsMiddlewareTest extends TestCase
 {
     use ProblemDetailsAssertionsTrait;
 
-    protected function setUp()
+    protected function setUp() : void
     {
         $this->request = $this->prophesize(ServerRequestInterface::class);
         $this->responseFactory = $this->prophesize(ProblemDetailsResponseFactory::class);
         $this->middleware = new ProblemDetailsMiddleware($this->responseFactory->reveal());
     }
 
-    public function acceptHeaders()
+    public function acceptHeaders() : array
     {
         return [
             'empty'                    => [''],
@@ -34,7 +34,7 @@ public function acceptHeaders()
         ];
     }
 
-    public function testSuccessfulDelegationReturnsDelegateResponse()
+    public function testSuccessfulDelegationReturnsDelegateResponse() : void
     {
         $response = $this->prophesize(ResponseInterface::class);
         $delegate = $this->prophesize(DelegateInterface::class);
@@ -52,7 +52,7 @@ public function testSuccessfulDelegationReturnsDelegateResponse()
     /**
      * @dataProvider acceptHeaders
      */
-    public function testDelegateNotReturningResponseResultsInProblemDetails(string $accept)
+    public function testDelegateNotReturningResponseResultsInProblemDetails(string $accept) : void
     {
         $this->request->getHeaderLine('Accept')->willReturn($accept);
 
@@ -74,7 +74,7 @@ public function testDelegateNotReturningResponseResultsInProblemDetails(string $
     /**
      * @dataProvider acceptHeaders
      */
-    public function testThrowableRaisedByDelegateResultsInProblemDetails(string $accept)
+    public function testThrowableRaisedByDelegateResultsInProblemDetails(string $accept) : void
     {
         $this->request->getHeaderLine('Accept')->willReturn($accept);
 
@@ -98,7 +98,7 @@ public function testThrowableRaisedByDelegateResultsInProblemDetails(string $acc
     /**
      * @dataProvider acceptHeaders
      */
-    public function testMiddlewareRegistersErrorHandlerToConvertErrorsToProblemDetails(string $accept)
+    public function testMiddlewareRegistersErrorHandlerToConvertErrorsToProblemDetails(string $accept) : void
     {
         $this->request->getHeaderLine('Accept')->willReturn($accept);
 
@@ -124,7 +124,7 @@ public function testMiddlewareRegistersErrorHandlerToConvertErrorsToProblemDetai
         $this->assertSame($expected, $result);
     }
 
-    public function testRethrowsCaughtExceptionIfUnableToNegotiateAcceptHeader()
+    public function testRethrowsCaughtExceptionIfUnableToNegotiateAcceptHeader() : void
     {
         $this->request->getHeaderLine('Accept')->willReturn('text/html');
         $exception = new TestAsset\RuntimeException('Thrown!', 507);

test/ProblemDetailsResponseFactoryFactoryTest.php

@@ -12,12 +12,12 @@
 
 class ProblemDetailsResponseFactoryFactoryTest extends TestCase
 {
-    protected function setUp()
+    protected function setUp() : void
     {
         $this->container = $this->prophesize(ContainerInterface::class);
     }
 
-    public function testLackOfOptionalServicesResultsInFactoryUsingDefaults()
+    public function testLackOfOptionalServicesResultsInFactoryUsingDefaults() : void
     {
         $this->container->has('config')->willReturn(false);
         $this->container->has(ResponseInterface::class)->willReturn(false);
@@ -38,7 +38,7 @@ public function testLackOfOptionalServicesResultsInFactoryUsingDefaults()
         $this->assertAttributeInstanceOf(Closure::class, 'bodyFactory', $factory);
     }
 
-    public function testUsesDebugSettingFromConfigWhenPresent()
+    public function testUsesDebugSettingFromConfigWhenPresent() : void
     {
         $this->container->has('config')->willReturn(true);
         $this->container->get('config')->willReturn(['debug' => true]);
@@ -53,7 +53,7 @@ public function testUsesDebugSettingFromConfigWhenPresent()
         $this->assertAttributeSame(ProblemDetailsResponseFactory::INCLUDE_THROWABLE_DETAILS, 'isDebug', $factory);
     }
 
-    public function testUsesJsonFlagsSettingFromConfigWhenPresent()
+    public function testUsesJsonFlagsSettingFromConfigWhenPresent() : void
     {
         $this->container->has('config')->willReturn(true);
         $this->container->get('config')->willReturn(['problem-details' => ['json_flags' => JSON_PRETTY_PRINT]]);
@@ -68,7 +68,7 @@ public function testUsesJsonFlagsSettingFromConfigWhenPresent()
         $this->assertAttributeSame(JSON_PRETTY_PRINT, 'jsonFlags', $factory);
     }
 
-    public function testUsesResponseServiceFromContainerWhenPresent()
+    public function testUsesResponseServiceFromContainerWhenPresent() : void
     {
         $response = $this->prophesize(ResponseInterface::class)->reveal();
 
@@ -84,7 +84,7 @@ public function testUsesResponseServiceFromContainerWhenPresent()
         $this->assertAttributeSame($response, 'response', $factory);
     }
 
-    public function testUsesStreamFactoryServiceFromContainerWhenPresent()
+    public function testUsesStreamFactoryServiceFromContainerWhenPresent() : void
     {
         // @codingStandardsIgnoreStart
         $streamFactory = function () { };