[feature/passwords] Add missing documentation to docblocks

Also contains some minor spacing changes.

PHPBB3-11610

phpBB/phpbb/passwords/driver/base.php

@@ -26,7 +26,8 @@ abstract class base implements driver_interface
 	/**
 	* Constructor of passwords driver object
 	*
-	* @return string	Hash prefix
+	* @param \phpbb\config\config $config phpBB config
+	* @param \phpbb\passwords\driver\helper $helper Password driver helper
 	*/
 	public function __construct(\phpbb\config\config $config, \phpbb\passwords\driver\helper $helper)
 	{

phpBB/phpbb/passwords/driver/driver_interface.php

@@ -20,6 +20,7 @@ interface driver_interface
 	* @return bool		True if supported, false if not
 	*/
 	public function is_supported();
+
 	/**
 	* Returns the hash prefix
 	*
@@ -30,7 +31,10 @@ interface driver_interface
 	/**
 	* Hash the password
 	*
-	* @return string	Password hash
+	* @param string $password The password that should be hashed
+	*
+	* @return bool|string	Password hash or false if something went wrong
+	*			during hashing
 	*/
 	public function hash($password);
 
@@ -39,6 +43,7 @@ interface driver_interface
 	*
 	* @param string		$password The password to check
 	* @param string		$hash The password hash to check against
+	*
 	* @return bool		True if password is correct, else false
 	*/
 	public function check($password, $hash);

phpBB/phpbb/passwords/driver/helper.php

@@ -86,7 +86,8 @@ class helper
 
 	/**
 	* Return unique id
-	* @param string $extra additional entropy
+	*
+	* @param string $extra Additional entropy
 	*
 	* @return string Unique id
 	*/
@@ -113,6 +114,8 @@ class helper
 	*
 	* @param int $length Salt length
 	* @param string $rand_seed Seed for random data (optional). For tests.
+	*
+	* @return string Random salt with specified length
 	*/
 	public function get_random_salt($length, $rand_seed = '/dev/urandom')
 	{

phpBB/phpbb/passwords/driver/salted_md5.php

@@ -122,8 +122,11 @@ class salted_md5 extends base
 	/**
 	* Get hash settings
 	*
-	* @return array Array containing the count_log2, salt, and full hash
+	* @param string $hash The hash that contains the settings
-	*		settings string
+	*
+	* @return bool|array Array containing the count_log2, salt, and full
+	*		hash settings string or false if supplied hash is empty
+	*		or contains incorrect settings
 	*/
 	public function get_hash_settings($hash)
 	{
@@ -131,6 +134,7 @@ class salted_md5 extends base
 		{
 			return false;
 		}
+
 		$count_log2 = strpos($this->helper->itoa64, $hash[3]);
 		$salt = substr($hash, 4, 8);
 

phpBB/phpbb/passwords/helper.php

@@ -22,7 +22,7 @@ class helper
 	/**
 	* Set the passwords manager instance
 	*
-	* @param phpbb\passwords\manager $manager Crypto manager object
+	* @param phpbb\passwords\manager $manager Passwords manager object
 	*/
 	public function set_manager(\phpbb\passwords\manager $manager)
 	{
@@ -35,8 +35,9 @@ class helper
 	* @param string $hash Password hash of combined hash
 	*
 	* @return array An array containing the hash settings for the hash
-	*		types in successive order as described by the comined
+	*		types in successive order as described by the combined
-	*		password hash
+	*		password hash or an empty array if hash does not
+	*		properly fit the combined hash format
 	*/
 	protected function get_combined_hash_settings($hash)
 	{
@@ -134,7 +135,7 @@ class helper
 	* @param string $type Data type of the supplied value
 	* @param string $value Value that should be put into the data array
 	*
-	* @return string|none Return complete combined hash if type is neither
+	* @return string|null Return complete combined hash if type is neither
 	*			'prefix' nor 'settings', nothing if it is
 	*/
 	protected function combine_hash_output(&$data, $type, $value)

phpBB/phpbb/passwords/manager.php

@@ -37,7 +37,7 @@ class manager
 	public $convert_flag = false;
 
 	/**
-	* Crypto helper
+	* Passwords helper
 	* @var phpbb\passwords\helper
 	*/
 	protected $helper;
@@ -125,7 +125,8 @@ class manager
 	*
 	* @param string $prefix Password hash prefix
 	*
-	* @return object The hash type object
+	* @return object|bool The hash type object or false if prefix is not
+	*			supported
 	*/
 	protected function get_algorithm($prefix)
 	{