From ebf6b250b887849a519ddca5dcce32a85d31ee8e Mon Sep 17 00:00:00 2001
From: Johan de Ruijter <dev@johanderuijter.nl>
Date: Wed, 15 Jul 2015 19:45:30 +0200
Subject: [PATCH] Aligned the DocBlocks Clarified and corrected the
 documentation where needed.

---
 src/JWT.php | 55 ++++++++++++++++++++++++++++++++---------------------
 1 file changed, 33 insertions(+), 22 deletions(-)

diff --git a/src/JWT.php b/src/JWT.php
index d1a108f3..ff7c07d4 100644
--- a/src/JWT.php
+++ b/src/JWT.php
@@ -38,11 +38,13 @@ class JWT
     /**
      * Decodes a JWT string into a PHP object.
      *
-     * @param string      $jwt           The JWT
-     * @param string|Array|null $key     The secret key, or map of keys
-     * @param Array       $allowed_algs  List of supported verification algorithms
+     * @param string            $jwt            The JWT
+     * @param string|array|null $key            The key, or map of keys.
+     *                                          If the algorithm used is asymmetric, this is the public key
+     * @param array             $allowed_algs   List of supported verification algorithms
+     *                                          Supported algorithms are 'HS256', 'HS384', 'HS512' and 'RS256'
      *
-     * @return object      The JWT's payload as a PHP object
+     * @return object The JWT's payload as a PHP object
      *
      * @throws DomainException              Algorithm was not provided
      * @throws UnexpectedValueException     Provided JWT was invalid
@@ -120,13 +122,15 @@ public static function decode($jwt, $key = null, $allowed_algs = array())
     /**
      * Converts and signs a PHP object or array into a JWT string.
      *
-     * @param object|array $payload PHP object or array
-     * @param string       $key     The secret key
-     * @param string       $alg     The signing algorithm. Supported
-     *                              algorithms are 'HS256', 'HS384' and 'HS512'
-     * @param array        $head    An array with header elements to attach
+     * @param object|array  $payload    PHP object or array
+     * @param string        $key        The secret key.
+     *                                  If the algorithm used is asymmetric, this is the private key
+     * @param string        $alg        The signing algorithm.
+     *                                  Supported algorithms are 'HS256', 'HS384', 'HS512' and 'RS256'
+     * @param array         $head       An array with header elements to attach
+     *
+     * @return string A signed JWT
      *
-     * @return string      A signed JWT
      * @uses jsonEncode
      * @uses urlsafeB64Encode
      */
@@ -153,12 +157,13 @@ public static function encode($payload, $key, $alg = 'HS256', $keyId = null, $he
     /**
      * Sign a string with a given key and algorithm.
      *
-     * @param string $msg          The message to sign
-     * @param string|resource $key The secret key
-     * @param string $alg       The signing algorithm. Supported algorithms
-     *                               are 'HS256', 'HS384', 'HS512' and 'RS256'
+     * @param string            $msg    The message to sign
+     * @param string|resource   $key    The secret key
+     * @param string            $alg    The signing algorithm.
+     *                                  Supported algorithms are 'HS256', 'HS384', 'HS512' and 'RS256'
+     *
+     * @return string An encrypted message
      *
-     * @return string          An encrypted message
      * @throws DomainException Unsupported algorithm was specified
      */
     public static function sign($msg, $key, $alg = 'HS256')
@@ -182,13 +187,16 @@ public static function sign($msg, $key, $alg = 'HS256')
     }
 
     /**
-     * Verify a signature with the mesage, key and method. Not all methods
+     * Verify a signature with the message, key and method. Not all methods
      * are symmetric, so we must have a separate verify and sign method.
-     * @param string $msg the original message
-     * @param string $signature
-     * @param string|resource $key for HS*, a string key works. for RS*, must be a resource of an openssl public key
-     * @param string $alg
+     *
+     * @param string            $msg        The original message (header and body)
+     * @param string            $signature  The original signature
+     * @param string|resource   $key        For HS*, a string key works. for RS*, must be a resource of an openssl public key
+     * @param string            $alg        The algorithm
+     *
      * @return bool
+     *
      * @throws DomainException Invalid Algorithm or OpenSSL failure
      */
     private static function verify($msg, $signature, $key, $alg)
@@ -229,7 +237,8 @@ private static function verify($msg, $signature, $key, $alg)
      *
      * @param string $input JSON string
      *
-     * @return object          Object representation of JSON string
+     * @return object Object representation of JSON string
+     *
      * @throws DomainException Provided string was invalid JSON
      */
     public static function jsonDecode($input)
@@ -263,7 +272,8 @@ public static function jsonDecode($input)
      *
      * @param object|array $input A PHP object or array
      *
-     * @return string          JSON representation of the PHP object or array
+     * @return string JSON representation of the PHP object or array
+     *
      * @throws DomainException Provided object could not be encoded to valid JSON
      */
     public static function jsonEncode($input)
@@ -331,6 +341,7 @@ private static function handleJsonError($errno)
      * Get the number of bytes in cryptographic strings.
      *
      * @param string
+     *
      * @return int
      */
     private static function safeStrlen($str)