[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
-	*		settings string
+	* @param string $hash The hash that contains the settings
+	*
+	* @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);