Merge pull request #109 from php-http/document-auth

more verbose documentation on authentication

Author: dbu

src/Authentication.php

@@ -5,18 +5,21 @@
 use Psr\Http\Message\RequestInterface;
 
 /**
- * Authenticate a PSR-7 Request.
+ * Add authentication information to a PSR-7 Request.
  *
  * @author Márk Sági-Kazár <mark.sagikazar@gmail.com>
  */
 interface Authentication
 {
     /**
-     * Authenticates a request.
+     * Alter the request to add the authentication credentials.
      *
-     * @param RequestInterface $request
+     * To do that, the implementation might use pre-stored credentials or do
+     * separate HTTP requests to obtain a valid token.
      *
-     * @return RequestInterface
+     * @param RequestInterface $request The request without authentication information
+     *
+     * @return RequestInterface The request with added authentication information
      */
     public function authenticate(RequestInterface $request);
 }