[feature/auth-refactor] Document the provider interface

Provides basic documentation of the auth_provideR_interface.
Changes the login method to login($username, $password) for
consistency with the providers.
acp() is not fully documented. It appears that it is meant to
return an array of some sort and take in a variable by reference.

PHPBB3-9734

phpBB/includes/auth/provider_interface.php

@@ -22,11 +22,41 @@ if (!defined('IN_PHPBB'))
  */
 class phpbb_auth_provider_interface
 {
+	/**
+	 * Checks whether the user is currently identified to the authentication
+	 * provider.
+	 * Called in acp_board while setting authentication plugins.
+	 *
+	 * @return 	boolean|string 	False if the user is identified, otherwise an
+	 *							error message.
+	 */
 	public function init();
 
-	public function login();
+	/**
+	 * Performs login.
+	 *
+	 * @param 	$username 	string 	The name of the user being authenticated.
+	 * @param 	$password 	string 	The password of the user.
+	 * @return 	array 		An associative array of the format:
+	 *							array(
+	 *								'status' => status constant
+	 *								'error_msg' => string
+	 *								'user_row' => array
+	 *							)
+	 */
+	public function login($username, $password);
 
+	/**
+	 * Autologin function
+	 *
+	 * @return 	array 	containing the user row or empty if no auto login should
+	 * 					take place
+	 */
 	public function autologin();
 
+	/**
+	 * 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();
 }