[feature/auth-refactor] Finish and clean up documentation

PHPBB3-9734

phpBB/includes/auth/provider_apache.php

@@ -42,13 +42,6 @@ class phpbb_auth_provider_apache implements phpbb_auth_provider_interface
 		$this->php_ext = $php_ext;
 	}
 
-	/**
-	 * Checks whether the user is identified to apache
-	 * Only allow changing authentication to apache if the user is identified
-	 * Called in acp_board while setting authentication plugins
-	 *
-	 * @return boolean|string false if the user is identified and else an error message
-	 */
 	public function init()
 	{
 		if (!$this->request->is_set('PHP_AUTH_USER', phpbb_request_interface::SERVER) || $this->user->data['username'] !== htmlspecialchars_decode($this->request->server('PHP_AUTH_USER')))
@@ -58,9 +51,6 @@ class phpbb_auth_provider_apache implements phpbb_auth_provider_interface
 		return false;
 	}
 
-	/**
-	 * Login function
-	 */
 	public function login($username, $password)
 	{
 		// do not allow empty password
@@ -148,12 +138,6 @@ class phpbb_auth_provider_apache implements phpbb_auth_provider_interface
 		);
 	}
 
-	/**
-	 * Autologin function
-	 *
-	 * @return 	array 	containing the user row or empty if no auto login should
-	 * 					take place
-	 */
 	public function autologin()
 	{
 		if (!$this->request->is_set('PHP_AUTH_USER', phpbb_request_interface::SERVER))
@@ -209,8 +193,8 @@ class phpbb_auth_provider_apache implements phpbb_auth_provider_interface
 	 * This function generates an array which can be passed to the user_add
 	 * function in order to create a user
 	 *
-	 * @param 	str 	$username 	The username of the new user.
+	 * @param 	string	$username 	The username of the new user.
-	 * @param 	str 	$password 	The password of the new user.
+	 * @param 	string	$password 	The password of the new user.
 	 * @return 	array 				Contains data that can be passed directly to
 	 *								the user_add function.
 	 */
@@ -242,12 +226,6 @@ class phpbb_auth_provider_apache implements phpbb_auth_provider_interface
 		);
 	}
 
-	/**
-	 * The session validation function checks whether the user is still logged in
-	 *
-	 * @return 	boolean 	true if the given user is authenticated or false if
-	 * 						the session should be closed
-	 */
 	public function validate_session($user)
 	{
 		// Check if PHP_AUTH_USER is set and handle this case

phpBB/includes/auth/provider_db.php

@@ -28,12 +28,12 @@ class phpbb_auth_provider_db implements phpbb_auth_provider_interface
 	/**
 	 * Database Authentication Constructor
 	 *
-	 * @param 	phpbb_db_driver 	$db
+	 * @param	phpbb_db_driver	$db
-	 * @param 	phpbb_config 		$config
+	 * @param	phpbb_config 	$config
-	 * @param 	phpbb_request 		$request
+	 * @param	phpbb_request	$request
-	 * @param 	phpbb_user 			$user
+	 * @param	phpbb_user		$user
-	 * @param 	string 				$phpbb_root_path
+	 * @param	string			$phpbb_root_path
-	 * @param 	string 				$php_ext
+	 * @param	string			$php_ext
 	 */
 	public function __construct(phpbb_db_driver $db, phpbb_config $config, phpbb_request $request, phpbb_user $user, $phpbb_root_path, $php_ext)
 	{
@@ -50,18 +50,6 @@ class phpbb_auth_provider_db implements phpbb_auth_provider_interface
 		return;
 	}
 
-	/**
-	 * Login function
-	 *
-	 * @param string $username
-	 * @param string $password
-	 * @return array				A associative array of the format
-	 *							array(
-	 *								'status' => status constant
-	 *								'error_msg' => string
-	 *								'user_row' => array
-	 *							)
-	 */
 	public function login($username, $password)
 	{
 		// Auth plugins get the password untrimmed.

phpBB/includes/auth/provider_interface.php

@@ -26,31 +26,33 @@ interface phpbb_auth_provider_interface
 	 * Checks whether the user is currently identified to the authentication
 	 * provider.
 	 * Called in acp_board while setting authentication plugins.
+	 * Changing to an authentication provider will not be permitted in acp_board
+	 * if there is an error.
 	 *
 	 * @return 	boolean|string 	False if the user is identified, otherwise an
-	 *							error message.
+	 *							error message, or null if not implemented.
 	 */
 	public function init();
 
 	/**
 	 * Performs login.
 	 *
-	 * @param 	$username 	string 	The name of the user being authenticated.
+	 * @param	string	$username 	The name of the user being authenticated.
-	 * @param 	$password 	string 	The password of the user.
+	 * @param	string	$password	The password of the user.
-	 * @return 	array 		An associative array of the format:
+	 * @return	array	An associative array of the format:
-	 *							array(
+	 *						array(
-	 *								'status' => status constant
+	 *							'status' => status constant
-	 *								'error_msg' => string
+	 *							'error_msg' => string
-	 *								'user_row' => array
+	 *							'user_row' => array
-	 *							)
+	 *						)
 	 */
 	public function login($username, $password);
 
 	/**
 	 * Autologin function
 	 *
-	 * @return 	array 	containing the user row or empty if no auto login should
+	 * @return 	array|null	containing the user row, empty if no auto login
-	 * 					take place
+	 * 						should take place, or null if not impletmented.
 	 */
 	public function autologin();
 
@@ -58,22 +60,32 @@ interface phpbb_auth_provider_interface
 	 * This function is used to output any required fields in the authentication
 	 * admin panel. It also defines any required configuration table fields.
 	 *
-	 * @param 	type 	$new
+	 * @param 	array 	$new 	Contains the new configuration values that have
+	 * 							been set in acp_board.
+	 * @return	array|null	Returns null if not implemented or an array of the
+	 *						form:
+	 *							array(
+	 *								'tpl'		=> string
+	 *								'config' 	=> array
+	 *							)
 	 */
 	public function acp($new);
 
 	/**
-	 * Special logout function.
+	 * Performs additional actions during logout.
 	 *
-	 * @param 	type 	$data
+	 * @param 	array	$data			An array corresponding to
-	 * @param 	type 	$new_session
+	 *									phpbb_session::data
+	 * @param 	boolean	$new_session	True for a new session, false for no new
+	 *									session.
 	 */
 	public function logout($data, $new_session);
 
 	/**
-	 * The session validation function checks whether the user is still logged in.
+	 * The session validation function checks whether the user is still logged
+	 * into phpBB.
 	 *
-	 * @param 	type 	$user
+	 * @param 	array 	$user
 	 * @return 	boolean	true if the given user is authenticated, false if the 
 	 * 					session should be closed, or null if not implemented.
 	 */

phpBB/includes/auth/provider_ldap.php

@@ -27,9 +27,9 @@ class phpbb_auth_provider_ldap implements phpbb_auth_provider_interface
 	/**
 	 * LDAP Authentication Constructor
 	 *
-	 * @param 	phpbb_db_driver 	$db
+	 * @param 	phpbb_db_driver	$db
-	 * @param 	phpbb_config 		$config
+	 * @param 	phpbb_config	$config
-	 * @param 	phpbb_user 			$user
+	 * @param 	phpbb_user		$user
 	 */
 	public function __construct(phpbb_db_driver $db, phpbb_config $config, phpbb_user $user)
 	{
@@ -38,11 +38,6 @@ class phpbb_auth_provider_ldap implements phpbb_auth_provider_interface
 		$this->user = $user;
 	}
 
-	/**
-	 * Connect to ldap server
-	 * Only allow changing authentication to ldap if we can connect to the ldap server
-	 * Called in acp_board while setting authentication plugins
-	 */
 	public function init()
 	{
 		if (!@extension_loaded('ldap'))
@@ -111,9 +106,6 @@ class phpbb_auth_provider_ldap implements phpbb_auth_provider_interface
 		return false;
 	}
 
-	/**
-	 * Login function
-	 */
 	public function login($username, $password)
 	{
 		// do not allow empty password
@@ -290,10 +282,6 @@ class phpbb_auth_provider_ldap implements phpbb_auth_provider_interface
 		return;
 	}
 
-	/**
-	 * This function is used to output any required fields in the authentication
-	 * admin panel. It also defines any required configuration table fields.
-	 */
 	public function acp($new)
 	{
 		$tpl = '
@@ -359,6 +347,9 @@ class phpbb_auth_provider_ldap implements phpbb_auth_provider_interface
 
 	/**
 	 * Escapes an LDAP AttributeValue
+	 *
+	 * @param	string	$string	The string to be escaped
+	 * @return	string	The escaped string
 	 */
 	private function ldap_escape($string)
 	{