update how @internal phpdoc attributes are used

phpseclib/Crypt/Blowfish.php

@@ -274,14 +274,14 @@ class Blowfish extends BlockCipher
 
     /**
      * The Key Length (in bytes)
+     * {@internal The max value is 256 / 8 = 32, the min value is 128 / 8 = 16.  Exists in conjunction with $Nk
+     *    because the encryption / decryption / key schedule creation requires this number and not $key_length.  We could
+     *    derive this from $key_length or vice versa, but that'd mean we'd have to do multiple shift operations, so in lieu
+     *    of that, we'll just precompute it once.}
      *
      * @see \phpseclib3\Crypt\Common\SymmetricKey::setKeyLength()
      * @var int
      * @access private
-     * @internal The max value is 256 / 8 = 32, the min value is 128 / 8 = 16.  Exists in conjunction with $Nk
-     *    because the encryption / decryption / key schedule creation requires this number and not $key_length.  We could
-     *    derive this from $key_length or vice versa, but that'd mean we'd have to do multiple shift operations, so in lieu
-     *    of that, we'll just precompute it once.
      */
     protected $key_length = 16;
 

phpseclib/Crypt/Common/SymmetricKey.php

@@ -660,11 +660,12 @@ abstract class SymmetricKey
      *
      * setIV() is not required when ecb or gcm modes are being used.
      *
+     * {@internal Can be overwritten by a sub class, but does not have to be}
+     *
      * @access public
      * @param string $iv
      * @throws \LengthException if the IV length isn't equal to the block size
      * @throws \BadMethodCallException if an IV is provided when one shouldn't be
-     * @internal Can be overwritten by a sub class, but does not have to be
      */
     public function setIV($iv)
     {
@@ -855,9 +856,10 @@ abstract class SymmetricKey
      *
      * If the key is not explicitly set, it'll be assumed to be all null bytes.
      *
+     * {@internal Could, but not must, extend by the child Crypt_* class}
+     *
      * @access public
      * @param string $key
-     * @internal Could, but not must, extend by the child Crypt_* class
      */
     public function setKey($key)
     {
@@ -879,6 +881,8 @@ abstract class SymmetricKey
      *
      *         Where $hash (default = sha1) currently supports the following hashes: see: Crypt/Hash.php
      *
+     * {@internal Could, but not must, extend by the child Crypt_* class}
+     *
      * @see Crypt/Hash.php
      * @param string $password
      * @param string $method
@@ -886,7 +890,6 @@ abstract class SymmetricKey
      * @throws \LengthException if pbkdf1 is being used and the derived key length exceeds the hash length
      * @return bool
      * @access public
-     * @internal Could, but not must, extend by the child Crypt_* class
      */
     public function setPassword($password, $method = 'pbkdf2', ...$func_args)
     {
@@ -1086,11 +1089,12 @@ abstract class SymmetricKey
      * strlen($plaintext) will still need to be a multiple of the block size, however, arbitrary values can be added to make it that
      * length.
      *
+     * {@internal Could, but not must, extend by the child Crypt_* class}
+     *
      * @see self::decrypt()
      * @access public
      * @param string $plaintext
      * @return string $ciphertext
-     * @internal Could, but not must, extend by the child Crypt_* class
      */
     public function encrypt($plaintext)
     {
@@ -1429,12 +1433,13 @@ abstract class SymmetricKey
      * If strlen($ciphertext) is not a multiple of the block size, null bytes will be added to the end of the string until
      * it is.
      *
+     * {@internal Could, but not must, extend by the child Crypt_* class}
+     *
      * @see self::encrypt()
      * @access public
      * @param string $ciphertext
      * @return string $plaintext
      * @throws \LengthException if we're inside a block cipher and the ciphertext length is not a multiple of the block size
-     * @internal Could, but not must, extend by the child Crypt_* class
      */
     public function decrypt($ciphertext)
     {
@@ -2073,9 +2078,10 @@ abstract class SymmetricKey
      * continuous buffers not be used.  They do offer better security and are, in fact, sometimes required (SSH uses them),
      * however, they are also less intuitive and more likely to cause you problems.
      *
+     * {@internal Could, but not must, extend by the child Crypt_* class}
+     *
      * @see self::disableContinuousBuffer()
      * @access public
-     * @internal Could, but not must, extend by the child Crypt_* class
      */
     public function enableContinuousBuffer()
     {
@@ -2097,9 +2103,10 @@ abstract class SymmetricKey
      *
      * The default behavior.
      *
+     * {@internal Could, but not must, extend by the child Crypt_* class}
+     *
      * @see self::enableContinuousBuffer()
      * @access public
-     * @internal Could, but not must, extend by the child Crypt_* class
      */
     public function disableContinuousBuffer()
     {
@@ -2331,12 +2338,14 @@ abstract class SymmetricKey
      *
      * - First run of encrypt() / decrypt() with no init-settings
      *
+     * {@internal setup() is always called before en/decryption.}
+     *
+     * {@internal Could, but not must, extend by the child Crypt_* class}
+     *
      * @see self::setKey()
      * @see self::setIV()
      * @see self::disableContinuousBuffer()
      * @access private
-     * @internal setup() is always called before en/decryption.
-     * @internal Could, but not must, extend by the child Crypt_* class
      */
     protected function setup()
     {
@@ -2529,13 +2538,13 @@ abstract class SymmetricKey
      *         - $in (the content of $in has to en/decrypt by the generated code)
      *       - The callback function should not use the 'return' statement, but en/decrypt'ing the content of $in only
      *
+     * {@internal If a Crypt_* class providing inline crypting it must extend _setupInlineCrypt()}
      *
      * @see self::setup()
      * @see self::createInlineCryptFunction()
      * @see self::encrypt()
      * @see self::decrypt()
      * @access private
-     * @internal If a Crypt_* class providing inline crypting it must extend _setupInlineCrypt()
      */
     //protected function setupInlineCrypt();
 

phpseclib/Crypt/RC2.php

@@ -116,23 +116,26 @@ class RC2 extends BlockCipher
     /**
      * The key length in bits.
      *
+     * {@internal Should be in range [1..1024].}
+     *
+     * {@internal Changing this value after setting the key has no effect.}
+     *
      * @see self::setKeyLength()
      * @see self::setKey()
      * @var int
      * @access private
-     * @internal Should be in range [1..1024].
-     * @internal Changing this value after setting the key has no effect.
      */
     private $default_key_length = 1024;
 
     /**
      * The key length in bits.
      *
+     * {@internal Should be in range [1..1024].}
+     *
      * @see self::isValidEnine()
      * @see self::setKey()
      * @var int
      * @access private
-     * @internal Should be in range [1..1024].
      */
     private $current_key_length;
 

phpseclib/Crypt/Rijndael.php

@@ -107,26 +107,28 @@ class Rijndael extends BlockCipher
     /**
      * The Block Length divided by 32
      *
+     * {@internal The max value is 256 / 32 = 8, the min value is 128 / 32 = 4.  Exists in conjunction with $block_size
+     *    because the encryption / decryption / key schedule creation requires this number and not $block_size.  We could
+     *    derive this from $block_size or vice versa, but that'd mean we'd have to do multiple shift operations, so in lieu
+     *    of that, we'll just precompute it once.}
+     *
      * @see self::setBlockLength()
      * @var int
      * @access private
-     * @internal The max value is 256 / 32 = 8, the min value is 128 / 32 = 4.  Exists in conjunction with $block_size
-     *    because the encryption / decryption / key schedule creation requires this number and not $block_size.  We could
-     *    derive this from $block_size or vice versa, but that'd mean we'd have to do multiple shift operations, so in lieu
-     *    of that, we'll just precompute it once.
      */
     private $Nb = 4;
 
     /**
      * The Key Length (in bytes)
      *
+     * {@internal The max value is 256 / 8 = 32, the min value is 128 / 8 = 16.  Exists in conjunction with $Nk
+     *    because the encryption / decryption / key schedule creation requires this number and not $key_length.  We could
+     *    derive this from $key_length or vice versa, but that'd mean we'd have to do multiple shift operations, so in lieu
+     *    of that, we'll just precompute it once.}
+     *
      * @see self::setKeyLength()
      * @var int
      * @access private
-     * @internal The max value is 256 / 8 = 32, the min value is 128 / 8 = 16.  Exists in conjunction with $Nk
-     *    because the encryption / decryption / key schedule creation requires this number and not $key_length.  We could
-     *    derive this from $key_length or vice versa, but that'd mean we'd have to do multiple shift operations, so in lieu
-     *    of that, we'll just precompute it once.
      */
     protected $key_length = 16;
 
@@ -143,9 +145,10 @@ class Rijndael extends BlockCipher
     /**
      * The Number of Rounds
      *
+     * {@internal The max value is 14, the min value is 10.}
+     *
      * @var int
      * @access private
-     * @internal The max value is 14, the min value is 10.
      */
     private $Nr;
 

phpseclib/Math/BigInteger.php

@@ -462,11 +462,12 @@ class BigInteger implements \Serializable
      *
      * Note how the same comparison operator is used.  If you want to test for equality, use $x->equals($y).
      *
+     * {@internal Could return $this->subtract($x), but that's not as fast as what we do do.}
+     *
      * @param BigInteger $y
      * @return int in case < 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()
-     * @internal Could return $this->subtract($x), but that's not as fast as what we do do.
      */
     public function compare(BigInteger $y)
     {

phpseclib/Math/BigInteger/Engines/BCMath.php

@@ -437,10 +437,11 @@ class BCMath extends Engine
      *
      * Note how the same comparison operator is used.  If you want to test for equality, use $x->equals($y).
      *
+     * {@internal Could return $this->subtract($x), but that's not as fast as what we do do.}
+     *
      * @param BCMath $y
      * @return int in case < 0 if $this is less than $y; > 0 if $this is greater than $y, and 0 if they are equal.
      * @see self::equals()
-     * @internal Could return $this->subtract($x), but that's not as fast as what we do do.
      */
     public function compare(BCMath $y)
     {

phpseclib/Math/BigInteger/Engines/Engine.php

@@ -257,9 +257,10 @@ abstract class Engine implements \Serializable
      *
      * Say you have (30 mod 17 * x mod 17) mod 17 == 1.  x can be found using modular inverses.
      *
+     * {@internal See {@link http://www.cacr.math.uwaterloo.ca/hac/about/chap14.pdf#page=21 HAC 14.64} for more information.}
+     *
      * @param \phpseclib3\Math\BigInteger\Engines\Engine $n
      * @return \phpseclib3\Math\BigInteger\Engines\Engine|false
-     * @internal See {@link http://www.cacr.math.uwaterloo.ca/hac/about/chap14.pdf#page=21 HAC 14.64} for more information.
      */
     protected function modInverseHelper(Engine $n)
     {
@@ -952,9 +953,10 @@ abstract class Engine implements \Serializable
      *
      * Returns the nth root of a positive biginteger, where n defaults to 2
      *
+     * {@internal This function is based off of {@link http://mathforum.org/library/drmath/view/52605.html this page} and {@link http://stackoverflow.com/questions/11242920/calculating-nth-root-with-bcmath-in-php this stackoverflow question}.}
+     *
      * @param int $n
      * @return \phpseclib3\Math\BigInteger\Engines\Engine
-     * @internal This function is based off of {@link http://mathforum.org/library/drmath/view/52605.html this page} and {@link http://stackoverflow.com/questions/11242920/calculating-nth-root-with-bcmath-in-php this stackoverflow question}.
      */
     protected function rootInner($n)
     {

phpseclib/Math/BigInteger/Engines/GMP.php

@@ -288,11 +288,12 @@ class GMP extends Engine
      *
      * Note how the same comparison operator is used.  If you want to test for equality, use $x->equals($y).
      *
+     * {@internal Could return $this->subtract($x), but that's not as fast as what we do do.}
+     *
      * @param GMP $y
      * @return int in case < 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()
-     * @internal Could return $this->subtract($x), but that's not as fast as what we do do.
      */
     public function compare(GMP $y)
     {

phpseclib/Math/BigInteger/Engines/PHP32.php

@@ -290,11 +290,12 @@ class PHP32 extends PHP
      *
      * Note how the same comparison operator is used.  If you want to test for equality, use $x->equals($y).
      *
+     * {@internal Could return $this->subtract($x), but that's not as fast as what we do do.}
+     *
      * @param PHP32 $y
      * @return int in case < 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()
-     * @internal Could return $this->subtract($x), but that's not as fast as what we do do.
      */
     public function compare(PHP32 $y)
     {

phpseclib/Math/BigInteger/Engines/PHP64.php

@@ -294,11 +294,12 @@ class PHP64 extends PHP
      *
      * Note how the same comparison operator is used.  If you want to test for equality, use $x->equals($y).
      *
+     * {@internal Could return $this->subtract($x), but that's not as fast as what we do do.}
+     *
      * @param PHP64 $y
      * @return int in case < 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()
-     * @internal Could return $this->subtract($x), but that's not as fast as what we do do.
      */
     public function compare(PHP64 $y)
     {

phpseclib/Net/SFTP.php

@@ -1843,6 +1843,8 @@ class SFTP extends SSH2
      *
      * Setting $local_start to > 0 or $mode | self::RESUME_START doesn't do anything unless $mode | self::SOURCE_LOCAL_FILE.
      *
+     * {@internal ASCII mode for SFTPv4/5/6 can be supported by adding a new function - \phpseclib3\Net\SFTP::setMode().}
+     *
      * @param string $remote_file
      * @param string|resource $data
      * @param int $mode
@@ -1854,7 +1856,6 @@ class SFTP extends SSH2
      * @throws \phpseclib3\Exception\FileNotFoundException if you're uploading via a file and the file doesn't exist
      * @return bool
      * @access public
-     * @internal ASCII mode for SFTPv4/5/6 can be supported by adding a new function - \phpseclib3\Net\SFTP::setMode().
      */
     public function put($remote_file, $data, $mode = self::SOURCE_STRING, $start = -1, $local_start = -1, $progressCallback = null)
     {

phpseclib/Net/SSH2.php

@@ -2100,14 +2100,15 @@ class SSH2
     /**
      * Login Helper
      *
+     * {@internal It might be worthwhile, at some point, to protect against {@link http://tools.ietf.org/html/rfc4251#section-9.3.9 traffic analysis}
+     *           by sending dummy SSH_MSG_IGNORE messages.}
+     *
      * @param string $username
      * @param string $password
      * @return bool
      * @throws \UnexpectedValueException on receipt of unexpected packets
      * @throws \RuntimeException on other errors
      * @access private
-     * @internal It might be worthwhile, at some point, to protect against {@link http://tools.ietf.org/html/rfc4251#section-9.3.9 traffic analysis}
-     *           by sending dummy SSH_MSG_IGNORE messages.
      */
     private function login_helper($username, $password = null)
     {
@@ -2403,13 +2404,14 @@ class SSH2
     /**
      * Login with an RSA private key
      *
+     * {@internal It might be worthwhile, at some point, to protect against {@link http://tools.ietf.org/html/rfc4251#section-9.3.9 traffic analysis}
+     *           by sending dummy SSH_MSG_IGNORE messages.}
+     *
      * @param string $username
      * @param \phpseclib3\Crypt\Common\PrivateKey $privatekey
      * @return bool
      * @throws \RuntimeException on connection error
      * @access private
-     * @internal It might be worthwhile, at some point, to protect against {@link http://tools.ietf.org/html/rfc4251#section-9.3.9 traffic analysis}
-     *           by sending dummy SSH_MSG_IGNORE messages.
      */
     private function privatekey_login($username, PrivateKey $privatekey)
     {

phpseclib/System/SSH/Agent.php

@@ -3,6 +3,8 @@
 /**
  * Pure-PHP ssh-agent client.
  *
+ * {@internal See http://api.libssh.org/rfc/PROTOCOL.agent}
+ *
  * PHP version 5
  *
  * Here are some examples of how to use this library:
@@ -28,7 +30,6 @@
  * @copyright 2014 Jim Wigginton
  * @license   http://www.opensource.org/licenses/mit-license.html  MIT License
  * @link      http://phpseclib.sourceforge.net
- * @internal  See http://api.libssh.org/rfc/PROTOCOL.agent
  */
 
 namespace phpseclib3\System\SSH;

phpseclib/System/SSH/Agent/Identity.php

@@ -3,6 +3,8 @@
 /**
  * Pure-PHP ssh-agent client.
  *
+ * {@internal See http://api.libssh.org/rfc/PROTOCOL.agent}
+ *
  * PHP version 5
  *
  * @category  System
@@ -11,7 +13,6 @@
  * @copyright 2009 Jim Wigginton
  * @license   http://www.opensource.org/licenses/mit-license.html  MIT License
  * @link      http://phpseclib.sourceforge.net
- * @internal  See http://api.libssh.org/rfc/PROTOCOL.agent
  */
 
 namespace phpseclib3\System\SSH\Agent;