revisions to rrran's PHPDoc changes

phpseclib/Crypt/Common/AsymmetricKey.php

@@ -180,7 +180,7 @@ abstract class AsymmetricKey
     /**
      * Tests engine validity
      *
-     * @returns boolean
+     * @return boolean
      * @access public
      * @param int $val
      */

phpseclib/Crypt/Common/Keys/OpenSSH.php

@@ -103,7 +103,7 @@ abstract class OpenSSH
      * Returns the comment for the key
      *
      * @access public
-     * @param $key
+     * @param string $key
      * @return mixed
      */
     public static function getComment($key)

phpseclib/Crypt/Common/Keys/PKCS8.php

@@ -28,7 +28,6 @@
 namespace phpseclib\Crypt\Common\Keys;
 
 use ParagonIE\ConstantTime\Base64;
-use phpseclib\Crypt\Common\SymmetricKey;
 use phpseclib\Crypt\DES;
 use phpseclib\Crypt\RC2;
 use phpseclib\Crypt\RC4;
@@ -139,7 +138,7 @@ abstract class PKCS8 extends PKCS
 
     /**
      * Returns a SymmetricKey object based on a PBES1 $algo
-     * @returns SymmetricKey
+     * @return \phpseclib\Crypt\Common\SymmetricKey
      * @access public
      * @param string $algo
      */
@@ -189,7 +188,7 @@ abstract class PKCS8 extends PKCS
     /**
      * Returns a hash based on a PBES1 $algo
      *
-     * @returns string
+     * @return string
      * @access public
      * @param string $algo
      */
@@ -205,7 +204,7 @@ abstract class PKCS8 extends PKCS
     /**
      * Returns a KDF baesd on a PBES1 $algo
      *
-     * @returns string
+     * @return string
      * @access public
      * @param string $algo
      */
@@ -227,7 +226,7 @@ abstract class PKCS8 extends PKCS
     /**
      * Returns a SymmetricKey object baesd on a PBES2 $algo
      *
-     * @returns SymmetricKey
+     * @return SymmetricKey
      * @access public
      * @param string $algo
      */

phpseclib/Crypt/DSA.php

@@ -213,10 +213,10 @@ class DSA extends AsymmetricKey
      * Loads a public or private key
      *
      * Returns true on success and false on failure (ie. an incorrect password was provided or the key was malformed)
-     * @return boolean
+     * @return bool
      * @access public
      * @param string $key
-     * @param int|boolean $type optional
+     * @param int|bool $type optional
      */
     public function load($key, $type = false)
     {
@@ -460,7 +460,7 @@ class DSA extends AsymmetricKey
      * @see self::verify()
      * @access public
      * @param string $message
-     * @param $signature
+     * @param string $signature
      * @param string $format optional
      * @return mixed
      */

phpseclib/Crypt/DSA/Signature/PKCS.php

@@ -35,7 +35,7 @@ abstract class PKCS
      * Loads a signature
      *
      * @access public
-     * @param $sig
+     * @param string $sig
      * @return array|bool
      */
     public static function load($sig)

phpseclib/Crypt/Hash.php

@@ -333,7 +333,7 @@ class Hash
      * Pure-PHP implementation of SHA512
      * @access private
      * @param string $m
-     * @param $hash
+     * @param array $hash
      * @return string
      */
     private static function sha512($m, $hash)

phpseclib/Crypt/RC4.php

@@ -255,7 +255,7 @@ class RC4 extends StreamCipher
 
     /**
      * Encrypts a block
-     * @return null
+     *
      * @access private
      * @param string $in
      */
@@ -266,7 +266,7 @@ class RC4 extends StreamCipher
 
     /**
      * Decrypts a block
-     * @return null
+     *
      * @access private
      * @param string $in
      */

phpseclib/Crypt/RSA.php

@@ -456,10 +456,10 @@ class RSA extends AsymmetricKey
      *
      * Returns true on success and false on failure (ie. an incorrect password was provided or the key was malformed)
      *
-     * @return boolean
+     * @return bool
      * @access public
      * @param string $key
-     * @param int|boolean $type optional
+     * @param int|bool $type optional
      */
     public function load($key, $type = false)
     {
@@ -654,8 +654,8 @@ class RSA extends AsymmetricKey
      *
      * @see self::getPublicKey()
      * @access public
-     * @param string|boolean $key optional
-     * @param int|boolean $type optional
+     * @param string|bool $key optional
+     * @param int|bool $type optional
      * @return bool
      */
     public function setPublicKey($key = false, $type = false)
@@ -698,8 +698,8 @@ class RSA extends AsymmetricKey
      *
      * @see self::getPublicKey()
      * @access public
-     * @param string|boolean $key optional
-     * @param int|boolean $type optional
+     * @param string|bool $key optional
+     * @param int|bool $type optional
      * @return bool
      */
     public function setPrivateKey($key = false, $type = false)
@@ -838,8 +838,7 @@ class RSA extends AsymmetricKey
      *    of the hash function Hash) and 0.
      *
      * @access public
-     * @param $sLen
-     * @internal param int $format
+     * @param int $sLen
      */
     public function setSaltLength($sLen)
     {
@@ -1348,7 +1347,7 @@ class RSA extends AsymmetricKey
      *
      * See {@link http://tools.ietf.org/html/rfc3447#section-9.1.1 RFC3447#section-9.1.1}.
      *
-     * @returns string
+     * @return string
      * @access private
      * @param string $m
      * @throws \RuntimeException on encoding error

phpseclib/Crypt/Rijndael.php

@@ -604,7 +604,7 @@ class Rijndael extends BlockCipher
     /**
      * Performs S-Box substitutions
      *
-     * @returns array
+     * @return array
      * @access private
      * @param int $word
      */

phpseclib/File/ANSI.php

@@ -203,7 +203,7 @@ class ANSI
     /**
      * Set the number of lines that should be logged past the terminal height
      *
-     * @param $history
+     * @param int $history
      * @access public
      */
     public function setHistory($history)
@@ -460,9 +460,9 @@ class ANSI
      * Returns the current coordinate without preformating
      *
      * @access private
-     * @param $last_attr
-     * @param $cur_attr
-     * @param $char
+     * @param \stdClass $last_attr
+     * @param \stdClass $cur_attr
+     * @param string $char
      * @return string
      */
     private function processCoordinate($last_attr, $cur_attr, $char)

phpseclib/File/ASN1.php

@@ -1387,7 +1387,7 @@ abstract class ASN1
      * getOID('zzz') == 'zzz'
      *
      * @access public
-     * @param $name
+     * @param string $name
      * @return string
      */
     static function getOID($name)

phpseclib/Math/BigInteger.php

@@ -122,7 +122,7 @@ class BigInteger implements \Serializable
      *
      * @param $x integer|BigInteger\Engines\Engine Base-10 number or base-$base number if $base set.
      * @param int $base
-     * @return \phpseclib\Math\BigInteger
+     * @return BigInteger
      */
     public function __construct($x = 0, $base = 10)
     {
@@ -241,8 +241,8 @@ class BigInteger implements \Serializable
     /**
      * Multiplies two BigIntegers
      *
-     * @param \phpseclib\Math\BigInteger $x
-     * @return \phpseclib\Math\BigInteger
+     * @param BigInteger $x
+     * @return BigInteger
      */
     public function multiply(BigInteger $x)
     {
@@ -271,8 +271,8 @@ class BigInteger implements \Serializable
      * ?>
      * </code>
      *
-     * @param \phpseclib\Math\BigInteger $y
-     * @return \phpseclib\Math\BigInteger[]
+     * @param BigInteger $y
+     * @return BigInteger[]
      */
     public function divide(BigInteger $y)
     {
@@ -288,7 +288,7 @@ class BigInteger implements \Serializable
      *
      * Say you have (30 mod 17 * x mod 17) mod 17 == 1.  x can be found using modular inverses.
      * @return BigInteger
-     * @param \phpseclib\Math\BigInteger $n
+     * @param BigInteger $n
      */
     public function modInverse(BigInteger $n)
     {
@@ -300,7 +300,7 @@ class BigInteger implements \Serializable
      *
      * Say you have (30 mod 17 * x mod 17) mod 17 == 1.  x can be found using modular inverses.
      * @return array
-     * @param \phpseclib\Math\BigInteger $n
+     * @param BigInteger $n
      */
     public function extendedGCD(BigInteger $n)
     {
@@ -328,7 +328,7 @@ class BigInteger implements \Serializable
     /**
      * Absolute value.
      *
-     * @return \phpseclib\Math\BigInteger
+     * @return BigInteger
      * @access public
      */
     public function abs()
@@ -438,7 +438,7 @@ class BigInteger implements \Serializable
      *
      * Note how the same comparison operator is used.  If you want to test for equality, use $x->equals($y).
      *
-     * @param \phpseclib\Math\BigInteger $y
+     * @param BigInteger $y
      * @return int < 0 if $this is less than $y; > 0 if $this is greater than $y, and 0 if they are equal.
      * @access public
      * @see self::equals()
@@ -465,7 +465,7 @@ class BigInteger implements \Serializable
     /**
      * Logical Not
      *
-     * @return \phpseclib\Math\BigInteger
+     * @return BigInteger
      */
     public function bitwise_not()
     {
@@ -511,7 +511,7 @@ class BigInteger implements \Serializable
      * Shifts BigInteger's by $shift bits, effectively dividing by 2**$shift.
      *
      * @param int $shift
-     * @return \phpseclib\Math\BigInteger
+     * @return BigInteger
      */
     public function bitwise_rightShift($shift)
     {
@@ -524,7 +524,7 @@ class BigInteger implements \Serializable
      * Shifts BigInteger's by $shift bits, effectively multiplying by 2**$shift.
      *
      * @param int $shift
-     * @return \phpseclib\Math\BigInteger
+     * @return BigInteger
      */
     public function bitwise_leftShift($shift)
     {
@@ -537,7 +537,7 @@ class BigInteger implements \Serializable
      * Instead of the top x bits being dropped they're appended to the shifted bit string.
      *
      * @param int $shift
-     * @return \phpseclib\Math\BigInteger
+     * @return BigInteger
      */
     public function bitwise_leftRotate($shift)
     {
@@ -550,7 +550,7 @@ class BigInteger implements \Serializable
      * Instead of the bottom x bits being dropped they're prepended to the shifted bit string.
      *
      * @param int $shift
-     * @return \phpseclib\Math\BigInteger
+     * @return BigInteger
      */
     public function bitwise_rightRotate($shift)
     {
@@ -599,7 +599,7 @@ class BigInteger implements \Serializable
      * Bit length is equal to $size
      *
      * @param int $size
-     * @return \phpseclib\Math\BigInteger
+     * @return BigInteger
      */
     public static function random($size)
     {
@@ -613,7 +613,7 @@ class BigInteger implements \Serializable
      * Bit length is equal to $size
      *
      * @param int $size
-     * @return \phpseclib\Math\BigInteger
+     * @return BigInteger
      */
     public static function randomPrime($size)
     {
@@ -662,7 +662,7 @@ class BigInteger implements \Serializable
      * $t parameter is distributability.  BigInteger::randomPrime() can be distributed across multiple pageloads
      * on a website instead of just one.
      *
-     * @param int|boolean $t
+     * @param int|bool $t
      * @return bool
      */
     public function isPrime($t = false)
@@ -676,7 +676,7 @@ class BigInteger implements \Serializable
      * Returns the nth root of a positive biginteger, where n defaults to 2
      *
      * @param int $n optional
-     * @return \phpseclib\Math\BigInteger
+     * @return BigInteger
      */
     public function root($n = 2)
     {

phpseclib/Math/BigInteger/Engines/BCMath.php

@@ -100,7 +100,7 @@ class BCMath extends Engine
     /**
      * Default constructor
      *
-     * @param $x integer Base-10 number or base-$base number if $base set.
+     * @param mixed $x integer Base-10 number or base-$base number if $base set.
      * @param int $base
      * @see parent::__construct()
      * @return \phpseclib\Math\BigInteger\Engines\BCMath
@@ -274,7 +274,7 @@ class BCMath extends Engine
      *
      * Say you have (30 mod 17 * x mod 17) mod 17 == 1.  x can be found using modular inverses.
      *
-     * @returns Engine|boolean
+     * @return false|BCMath
      * @param \phpseclib\Math\BigInteger\Engines\BCMath $n
      */
     public function modInverse(BCMath $n)
@@ -627,10 +627,10 @@ class BCMath extends Engine
      * ie. $s = gmp_scan1($n, 0) and $r = gmp_div_q($n, gmp_pow(gmp_init('2'), $s));
      *
      * @see self::isPrime()
-     * @param $r
+     * @param BCMath $r
      * @return int
      */
-    protected static function scan1divide($r)
+    protected static function scan1divide(BCMath $r)
     {
         $r_value = &$r->value;
         $s = 0;
@@ -694,7 +694,7 @@ class BCMath extends Engine
     /**
      * Set Bitmask
      *
-     * @returns Engine
+     * @return Engine
      * @param int $bits
      * @see self::setPrecision()
      */

phpseclib/Math/BigInteger/Engines/Engine.php

@@ -59,7 +59,7 @@ abstract class Engine implements \Serializable
     /**
      * Default constructor
      *
-     * @param $x integer Base-10 number or base-$base number if $base set.
+     * @param mixed $x integer Base-10 number or base-$base number if $base set.
      * @param int $base
      */
     public function __construct($x, $base)
@@ -381,7 +381,7 @@ abstract class Engine implements \Serializable
 
     /**
      * Set Bitmask
-     * @returns Engine
+     * @return Engine
      * @param int $bits
      * @see self::setPrecision()
      */
@@ -906,7 +906,7 @@ abstract class Engine implements \Serializable
      * $t parameter is distributability.  BigInteger::randomPrime() can be distributed across multiple pageloads
      * on a website instead of just one.
      *
-     * @param int|boolean $t
+     * @param int|bool $t
      * @return bool
      */
     public function isPrime($t = false)

phpseclib/Math/BigInteger/Engines/GMP.php

@@ -102,7 +102,7 @@ class GMP extends Engine
     /**
      * Default constructor
      *
-     * @param $x integer Base-10 number or base-$base number if $base set.
+     * @param mixed $x integer Base-10 number or base-$base number if $base set.
      * @param int $base
      * @see parent::__construct()
      * @return \phpseclib\Math\BigInteger\Engines\GMP

phpseclib/Math/BigInteger/Engines/PHP.php

@@ -74,7 +74,7 @@ abstract class PHP extends Engine
     /**
      * Default constructor
      *
-     * @param $x integer Base-10 number or base-$base number if $base set.
+     * @param mixed $x integer Base-10 number or base-$base number if $base set.
      * @param int $base
      * @see parent::__construct()
      * @return \phpseclib\Math\BigInteger\Engines\PHP
@@ -141,7 +141,7 @@ abstract class PHP extends Engine
     /**
      * Pads strings so that unpack may be used on them
      *
-     * @param $str
+     * @param string $str
      * @return string
      */
     protected function pad($str)
@@ -734,10 +734,10 @@ abstract class PHP extends Engine
      *
      * Removes leading zeros and truncates (if necessary) to maintain the appropriate precision
      *
-     * @param $result
+     * @param PHP $result
      * @return PHP
      */
-    protected function normalize($result)
+    protected function normalize(PHP $result)
     {
         $result->precision = $this->precision;
         $result->bitmask = $this->bitmask;
@@ -1301,10 +1301,10 @@ abstract class PHP extends Engine
      * ie. $s = gmp_scan1($n, 0) and $r = gmp_div_q($n, gmp_pow(gmp_init('2'), $s));
      *
      * @see self::isPrime()
-     * @param $r
+     * @param PHP $r
      * @return int
      */
-    protected static function scan1divide($r)
+    protected static function scan1divide(PHP $r)
     {
         $r_value = &$r->value;
         for ($i = 0, $r_length = count($r_value); $i < $r_length; ++$i) {

phpseclib/Math/BigInteger/Engines/PHP/Reductions/EvalBarrett.php

@@ -461,7 +461,7 @@ abstract class EvalBarrett extends Base
      * If you do echo floatval(pow(2, 52)) you'll get 4.6116860184274E+18. It /can/ be displayed without a loss of
      * precision but displayed in this way there will be precision loss, hence the need for this method.
      *
-     * @param $num
+     * @param int|float $num
      * @return string
      */
     private static function float2string($num)

phpseclib/Math/BigInteger/Engines/PHP32.php

@@ -163,7 +163,7 @@ class PHP32 extends PHP
      *
      * Say you have (30 mod 17 * x mod 17) mod 17 == 1.  x can be found using modular inverses.
      * @param PHP32 $n
-     * @return false|Engine
+     * @return false|PHP32
      */
     public function modInverse(PHP32 $n)
     {
@@ -175,7 +175,7 @@ class PHP32 extends PHP
      *
      * Say you have (30 mod 17 * x mod 17) mod 17 == 1.  x can be found using modular inverses.
      * @param PHP32 $n
-     * @return PHP[]
+     * @return PHP32[]
      */
     public function extendedGCD(PHP32 $n)
     {
@@ -327,7 +327,7 @@ class PHP32 extends PHP
      * Performs exponentiation.
      *
      * @param PHP32 $n
-     * @return PHP64
+     * @return PHP32
      */
     public function pow(PHP32 $n)
     {

phpseclib/Math/BigInteger/Engines/PHP64.php

@@ -163,7 +163,7 @@ class PHP64 extends PHP
      *
      * Say you have (30 mod 17 * x mod 17) mod 17 == 1.  x can be found using modular inverses.
      * @param PHP64 $n
-     * @return false|Engine
+     * @return false|PHP64
      */
     public function modInverse(PHP64 $n)
     {
@@ -175,7 +175,7 @@ class PHP64 extends PHP
      *
      * Say you have (30 mod 17 * x mod 17) mod 17 == 1.  x can be found using modular inverses.
      * @param PHP64 $n
-     * @return PHP[]
+     * @return PHP64[]
      */
     public function extendedGCD(PHP64 $n)
     {

phpseclib/Net/SCP.php

@@ -211,7 +211,7 @@ class SCP
      * operation
      *
      * @param string $remote_file
-     * @param string|boolean $local_file
+     * @param string|bool $local_file
      * @return mixed
      * @access public
      */

phpseclib/Net/SFTP.php

@@ -1180,7 +1180,7 @@ class SFTP extends SSH2
      *
      * Mainly used by file_exists
      *
-     * @param $path
+     * @param string $path
      * @return mixed
      * @access private
      */
@@ -1770,7 +1770,7 @@ class SFTP extends SSH2
      * Helper function for directory creation
      *
      * @param string $dir
-     * @param $attr
+     * @param string $attr
      * @return bool
      * @access private
      */
@@ -2117,7 +2117,7 @@ class SFTP extends SSH2
      * $offset and $length can be used to download files in chunks.
      *
      * @param string $remote_file
-     * @param string|boolean|resource $local_file
+     * @param string|bool|resource $local_file
      * @param int $offset
      * @param int $length
      * @throws \UnexpectedValueException on receipt of unexpected packets
@@ -2668,7 +2668,7 @@ class SFTP extends SSH2
      *
      * @param string $path
      * @param string $prop
-     * @param $type
+     * @param string $type
      * @return mixed
      * @access private
      */

phpseclib/Net/SSH1.php

@@ -1558,8 +1558,8 @@ class SSH1
      *
      * Makes sure that only the last 1MB worth of packets will be logged
      *
-     * @param $protocol_flags
-     * @param $message
+     * @param string $protocol_flags
+     * @param string $message
      * @access private
      */
     private function append_log($protocol_flags, $message)

phpseclib/Net/SSH2.php

@@ -1292,8 +1292,8 @@ class SSH2
 
     /**
      * Key Exchange
-     * @return boolean
-     * @param string|boolean $kexinit_payload_server optional
+     * @return bool
+     * @param string|bool $kexinit_payload_server optional
      * @throws \UnexpectedValueException on receipt of unexpected packets
      * @throws \RuntimeException on other errors
      * @throws \phpseclib\Exception\NoSupportedAlgorithmsException when none of the algorithms phpseclib has loaded are compatible
@@ -3314,8 +3314,8 @@ class SSH2
      * Because some binary packets need to be ignored...
      *
      * @see self::_get_binary_packet()
-     * @param $payload
-     * @param $filter_channel_packets
+     * @param string $payload
+     * @param bool $filter_channel_packets
      * @return string
      * @access private
      */
@@ -3552,8 +3552,8 @@ class SSH2
      *
      * Returns the data as a string if it's available and false if not.
      *
-     * @param $client_channel
-     * @param boolean $skip_extended
+     * @param int $client_channel
+     * @param bool $skip_extended
      * @return mixed
      * @throws \RuntimeException on connection error
      * @access private
@@ -3874,8 +3874,8 @@ class SSH2
      *
      * Makes sure that only the last 1MB worth of packets will be logged
      *
-     * @param $message_number
-     * @param $message
+     * @param string $message_number
+     * @param string $message
      * @access private
      */
     private function append_log($message_number, $message)