Improve docs

Author: donatj

docs/docs.md

@@ -212,6 +212,10 @@ Response constructor.
 
 ## Class: \donatj\MockWebServer\ResponseStack
 
+ResponseStack is used to store multiple responses for a request issued by the server in order.
+
+When the stack is empty, the server will return a customizable response defaulting to a 404.
+
 ### Method: ResponseStack->__construct
 
 ```php
@@ -230,6 +234,8 @@ Accepts a variable number of RequestInterface objects
 function getPastEndResponse()
 ```
 
+Gets the response returned when the stack is exhausted.
+
 #### Returns:
 
 - ***\donatj\MockWebServer\ResponseInterface***
@@ -242,12 +248,16 @@ function getPastEndResponse()
 function setPastEndResponse(\donatj\MockWebServer\ResponseInterface $pastEndResponse)
 ```
 
+Set the response to return when the stack is exhausted.
+
 #### Parameters:
 
 - ***\donatj\MockWebServer\ResponseInterface*** `$pastEndResponse`
 
 ## Class: \donatj\MockWebServer\ResponseByMethod
 
+ResponseByMethod is used to vary the response to a request by the called HTTP Method.
+
 ```php
 <?php
 namespace donatj\MockWebServer;
@@ -274,7 +284,7 @@ MethodResponse constructor.
 
 #### Parameters:
 
-- ***\donatj\MockWebServer\ResponseInterface[]*** `$responses` - An array of responses keyed by their method.
+- ***\donatj\MockWebServer\ResponseInterface[]*** `$responses` - A map of responses keyed by their method.
 - ***\donatj\MockWebServer\ResponseInterface*** | ***null*** `$defaultResponse` - The fallthrough response to return if a response for a given
 method is not found. If this is not defined the server will return an HTTP 501 error.
 
@@ -297,6 +307,8 @@ Set the Response for the Given Method
 
 DelayedResponse wraps a response, causing it when called to be delayed by a specified number of microseconds.
 
+This is useful for simulating slow responses and testing timeouts.
+
 ### Method: DelayedResponse->__construct
 
 ```php

src/DelayedResponse.php

@@ -4,6 +4,8 @@
 
 /**
  * DelayedResponse wraps a response, causing it when called to be delayed by a specified number of microseconds.
+ *
+ * This is useful for simulating slow responses and testing timeouts.
  */
 class DelayedResponse implements InitializingResponseInterface, MultiResponseInterface {
 

src/InitializingResponseInterface.php

@@ -2,6 +2,9 @@
 
 namespace donatj\MockWebServer;
 
+/**
+ * InitializingResponseInterface is used to initialize a response before headers are sent.
+ */
 interface InitializingResponseInterface extends ResponseInterface {
 
 	/**

src/MultiResponseInterface.php

@@ -2,9 +2,14 @@
 
 namespace donatj\MockWebServer;
 
+/**
+ * MultiResponseInterface is used to vary the response to a request.
+ */
 interface MultiResponseInterface extends ResponseInterface {
 
 	/**
+	 * Called after each request is sent
+	 *
 	 * @internal
 	 * @return bool
 	 */

src/ResponseByMethod.php

@@ -2,6 +2,9 @@
 
 namespace donatj\MockWebServer;
 
+/**
+ * ResponseByMethod is used to vary the response to a request by the called HTTP Method.
+ */
 class ResponseByMethod implements ResponseInterface {
 
 	const METHOD_GET     = 'GET';
@@ -22,7 +25,7 @@ class ResponseByMethod implements ResponseInterface {
 	/**
 	 * MethodResponse constructor.
 	 *
-	 * @param ResponseInterface[]    $responses An array of responses keyed by their method.
+	 * @param ResponseInterface[]    $responses A map of responses keyed by their method.
 	 * @param ResponseInterface|null $defaultResponse The fallthrough response to return if a response for a given
 	 * method is not found. If this is not defined the server will return an HTTP 501 error.
 	 */

src/ResponseStack.php

@@ -4,6 +4,11 @@
 
 use donatj\MockWebServer\Exceptions\RuntimeException;
 
+/**
+ * ResponseStack is used to store multiple responses for a request issued by the server in order.
+ *
+ * When the stack is empty, the server will return a customizable response defaulting to a 404.
+ */
 class ResponseStack implements MultiResponseInterface {
 
 	private $ref;
@@ -92,13 +97,17 @@ public function getStatus( RequestInfo $request ) {
 	}
 
 	/**
+	 * Gets the response returned when the stack is exhausted.
+	 *
 	 * @return \donatj\MockWebServer\ResponseInterface
 	 */
 	public function getPastEndResponse() {
 		return $this->pastEndResponse;
 	}
 
 	/**
+	 * Set the response to return when the stack is exhausted.
+	 *
 	 * @param \donatj\MockWebServer\ResponseInterface $pastEndResponse
 	 */
 	public function setPastEndResponse( ResponseInterface $pastEndResponse ) {