[feature/avatars] Fix the docs and small naming fixes

PHPBB3-10018

phpBB/includes/avatar/driver/driver.php

@@ -81,7 +81,7 @@ abstract class phpbb_avatar_driver implements phpbb_avatar_driver_interface
 	public $custom_html = false;
 
 	/**
-	* Construct an driver object
+	* Construct a driver object
 	*
 	* @param $config The phpBB configuration
 	* @param $request The request object

phpBB/includes/avatar/driver/gravatar.php

@@ -19,11 +19,10 @@ if (!defined('IN_PHPBB'))
 * Handles avatars hosted at gravatar.com
 * @package avatars
 */
-// @todo: rename classes to phpbb_ext_foo_avatar_driver_foo and similar
 class phpbb_avatar_driver_gravatar extends phpbb_avatar_driver
 {
 	/**
-	* We'll need to create a different type of avatar for gravatar
+	* @inheritdoc
 	*/
 	public $custom_html = true;
 
@@ -32,7 +31,6 @@ class phpbb_avatar_driver_gravatar extends phpbb_avatar_driver
 	*/
 	public function get_data($row, $ignore_config = false)
 	{
-		// @todo: add allow_avatar_gravatar to database_update.php etc.
 		if ($ignore_config || $this->config['allow_avatar_gravatar'])
 		{
 			return array(

phpBB/includes/avatar/driver/interface.php

@@ -51,27 +51,51 @@ interface phpbb_avatar_driver_interface
 	public function get_custom_html($row, $ignore_config = false, $alt = '');
 
 	/**
-	* @TODO
+	* Prepare form for changing the settings of this avatar
+	*
+	* @param object	$template The template object
+	* @param array	$row The user data or group data that has been cleaned with 
+	*        phpbb_avatar_manager::clean_row
+	* @param array	&$error The reference to an error array
+	*
+	* @return bool Returns true if form has been successfully prepared
 	**/
 	public function prepare_form($template, $row, &$error);
 
 	/**
-	* @TODO
+	* Process form data
+	*
+	* @param object	$template The template object
+	* @param array	$row The user data or group data that has been cleaned with 
+	*        phpbb_avatar_manager::clean_row
+	* @param array	&$error The reference to an error array
+	*
+	* @return array An array containing the avatar data as follows:
+	*        ['avatar'], ['avatar_width'], ['avatar_height']
 	**/
 	public function process_form($template, $row, &$error);
 
 	/**
-	* @TODO
+	* Delete avatar
+	*
+	* @param array $row The user data or group data that has been cleaned with 
+	*        phpbb_avatar_manager::clean_row
+	*
+	* @return bool True if avatar has been deleted or there is no need to delete
 	**/
 	public function delete($row);
 
 	/**
-	* @TODO
+	* Check if avatar is enabled
+	*
+	* @return bool True if avatar is enabled, false if it's disabled
 	**/
 	public function is_enabled();
 
 	/**
-	* @TODO
+	* Get the avatars template name
+	*
+	* @return string The avatars template name
 	**/
 	public function get_template_name();
 }

phpBB/includes/avatar/driver/local.php

@@ -132,7 +132,9 @@ class phpbb_avatar_driver_local extends phpbb_avatar_driver
 	}
 
 	/**
-	* @TODO
+	* Get a list of avatars that are locally available
+	*
+	* @return array An array containing the locally available avatars
 	*/
 	private function get_avatar_list()
 	{

phpBB/includes/avatar/driver/upload.php

@@ -139,7 +139,9 @@ class phpbb_avatar_driver_upload extends phpbb_avatar_driver
 	}
 
 	/**
-	* @TODO
+	* Check if user is able to upload an avatar
+	*
+	* @return bool True if user can upload, false if not
 	*/
 	private function can_upload()
 	{

phpBB/includes/avatar/manager.php

@@ -26,25 +26,37 @@ class phpbb_avatar_manager
 	private $request;
 	private $cache;
 	private static $valid_drivers = false;
-	private $tasks;
+	private $avatar_drivers;
 	private $container;
 
 	/**
-	* @TODO
+	* Construct an avatar manager object
+	*
+	* @param $phpbb_root_path The path to the phpBB root
+	* @param $phpEx The php file extension
+	* @param $config The phpBB configuration
+	* @param $request The request object
+	* @param $cache A cache driver
+	* @param $avatar_drivers The avatars drivers passed via the service container
+	* @param $container The container object
 	**/
-	public function __construct($phpbb_root_path, $phpEx, phpbb_config $config, phpbb_request $request, phpbb_cache_driver_interface $cache, $tasks, $container)
+	public function __construct($phpbb_root_path, $phpEx, phpbb_config $config, phpbb_request $request, phpbb_cache_driver_interface $cache, $avatar_drivers, $container)
 	{
 		$this->phpbb_root_path = $phpbb_root_path;
 		$this->phpEx = $phpEx;
 		$this->config = $config;
 		$this->request = $request;
 		$this->cache = $cache;
-		$this->tasks = $tasks;
+		$this->avatar_drivers = $avatar_drivers;
 		$this->container = $container;
 	}
 
 	/**
-	* @TODO
+	* Get the driver object specified by the avatar type
+	*
+	* @param string The avatar type; by default an avatar's service container name
+	*
+	* @return object The avatar driver object
 	**/
 	public function get_driver($avatar_type)
 	{
@@ -87,14 +99,15 @@ class phpbb_avatar_manager
 	}
 
 	/**
-	* @TODO
+	* Load the list of valid drivers
+	* This is executed once and fills self::$valid_drivers
 	**/
 	private function load_valid_drivers()
 	{
-		if (!empty($this->tasks))
+		if (!empty($this->avatar_drivers))
 		{
 			self::$valid_drivers = array();
-			foreach ($this->tasks as $driver)
+			foreach ($this->avatar_drivers as $driver)
 			{
 				self::$valid_drivers[] = $driver->get_name();
 			}
@@ -102,7 +115,9 @@ class phpbb_avatar_manager
 	}
 
 	/**
-	* @TODO
+	* Get a list of valid avatar drivers
+	*
+	* @return array An array containing a list of the valid avatar drivers
 	**/
 	public function get_valid_drivers()
 	{
@@ -116,6 +131,11 @@ class phpbb_avatar_manager
 
 	/**
 	* Strip out user_ and group_ prefixes from keys
+	*
+	* @param array	$row The user data or group data
+	*
+	* @return array The user data or group data with keys that have been
+	*        stripped from the preceding "user_" or "group_"
 	**/
 	public static function clean_row($row)
 	{

phpBB/install/database_update.php

@@ -2740,6 +2740,11 @@ function change_database_data(&$no_updates, $version)
 					AND module_mode = \'avatar\'';
 			_sql($sql, $errored, $error_ary);
 
+			if (!isset($config['allow_avatar_gravatar']))
+			{
+				$config->set('allow_avatar_gravatar', '');
+			}
+
 			$no_updates = false;
 
 			if (!isset($config['assets_version']))