[ticket/15287] Add PHPDoc

PHPBB3-15287

phpBB/phpbb/storage/adapter/local.php

@@ -29,10 +29,14 @@ class local implements adapter_interface
 	 */
 	protected $filesystem;
 
-	/** @var string path */
+	/**
+	 * @var string path
+	 */
 	protected $phpbb_root_path;
 
-	/** @var string path */
+	/**
+	 * @var string path
+	 */
 	protected $root_path;
 
 	/**

phpBB/phpbb/storage/adapter_factory.php

@@ -18,10 +18,28 @@ use phpbb\di\service_collection;
 
 class adapter_factory
 {
+	/**
+	 * @var \phpbb\config\config
+	 */
 	protected $config;
+
+	/**
+	 * @var \phpbb\di\service_collection
+	 */
 	protected $adapters;
+
+	/**
+	 * @var \phpbb\di\service_collection
+	 */
 	protected $providers;
 
+	/**
+	 * Constructor
+	 *
+	 * @param \phpbb\config\config				$config
+	 * @param \phpbb\di\service_collection		$adapters
+	 * @param \phpbb\di\service_collection		$providers
+	 */
 	public function __construct(config $config, service_collection $adapters, service_collection $providers)
 	{
 		$this->config = $config;
@@ -29,6 +47,13 @@ class adapter_factory
 		$this->providers = $providers;
 	}
 
+	/**
+	 * Obtains a configured adapters for a given storage
+	 *
+	 * @param string	$storage_name
+	 *
+	 * @return \phpbb\storage\adapter\adapter_interface
+	 */
 	public function get($storage_name)
 	{
 		$provider_class = $this->config['storage\\' . $storage_name . '\\adapter'];
@@ -40,6 +65,14 @@ class adapter_factory
 		return $adapter;
 	}
 
+	/**
+	 * Obtains configuration for a given storage
+	 *
+	 * @param string	$storage_name
+	 * @param array		$definitions
+	 *
+	 * @return array	Returns storage configuration values
+	 */
 	public function build_options($storage_name, array $definitions)
 	{
 		$options = [];

phpBB/phpbb/storage/provider/local.php

@@ -15,11 +15,17 @@ namespace phpbb\storage\provider;
 
 class local implements provider_interface
 {
+	/**
+	 * {@inheritdoc}
+	 */
 	public function get_class()
 	{
 		return \phpbb\storage\adapter\local::class;
 	}
 
+	/**
+	 * {@inheritdoc}
+	 */
 	public function get_options()
 	{
 		return ['path'];

phpBB/phpbb/storage/provider/provider_interface.php

@@ -15,6 +15,17 @@ namespace phpbb\storage\provider;
 
 interface provider_interface
 {
+	/**
+	 * Gets adapter class.
+	 *
+	 * @return \phpbb\storage\adapter\adapter_interface
+	 */
 	public function get_class();
+
+	/**
+	 * Gets adapter options.
+	 *
+	 * @return string	Configuration keys
+	 */
 	public function get_options();
 }

phpBB/phpbb/storage/storage.php

@@ -18,43 +18,110 @@ namespace phpbb\storage;
  */
 class storage
 {
+	/**
+	 * @var \phpbb\storage\adapter\adapter_interface
+	 */
 	protected $adapter;
 
-	public function __construct($factory, $storage_name)
+	/**
+	 * Constructor
+	 *
+	 * @param \phpbb\storage\adapter_factory	$factory
+	 * @param string							$storage_name
+	 */
+	public function __construct(adapter_factory $factory, $storage_name)
 	{
 		$this->adapter = $factory->get($storage_name);
 	}
 
+	/**
+	 * Dumps content into a file.
+	 *
+	 * @param string	path		The file to be written to.
+	 * @param string	content		The data to write into the file.
+	 *
+	 * @throws \phpbb\storage\exception\exception	When the file already exists
+	 * 												When the file cannot be written
+	 */
 	public function put_contents($path, $content)
 	{
 		$this->adapter->put_contents($path, $content);
 	}
 
+	/**
+	 * Read the contents of a file
+	 *
+	 * @param string	$path	The file to read
+	 *
+	 * @throws \phpbb\storage\exception\exception	When the file dont exists
+	 * 												When cannot read file contents
+	 * @return string	Returns file contents
+	 *
+	 */
 	public function get_contents($path)
 	{
 		return $this->adapter->get_contents($path);
 	}
 
+	/**
+	 * Checks the existence of files or directories.
+	 *
+	 * @param string	$path	file/directory to check
+	 *
+	 * @return bool	Returns true if all files/directories exist, false otherwise
+	 */
 	public function exists($path)
 	{
 		return $this->adapter->exists($path);
 	}
 
+	/**
+	 * Removes files or directories.
+	 *
+	 * @param string	$path	file/directory to remove
+	 *
+	 * @throws \phpbb\storage\exception\exception	When removal fails.
+	 */
 	public function delete($path)
 	{
 		$this->adapter->delete($path);
 	}
 
+	/**
+	 * Rename a file or a directory.
+	 *
+	 * @param string	$path_orig	The original file/direcotry
+	 * @param string	$path_dest	The target file/directory
+	 *
+	 * @throws \phpbb\storage\exception\exception	When target exists
+	 * 												When file/directory cannot be renamed
+	 */
 	public function rename($path_orig, $path_dest)
 	{
 		$this->adapter->rename($path_orig, $path_dest);
 	}
 
+	/**
+	 * Copies a file.
+	 *
+	 * @param string	$path_orig	The original filename
+	 * @param string	$path_dest	The target filename
+	 *
+	 * @throws \phpbb\storage\exception\exception	When target exists
+	 * 												When the file cannot be copied
+	 */
 	public function copy($path_orig, $path_dest)
 	{
 		$this->adapter->copy($path_orig, $path_dest);
 	}
 
+	/**
+	 * Creates a directory recursively.
+	 *
+	 * @param string	$path	The directory path
+	 *
+	 * @throws \phpbb\storage\exception\exception	On any directory creation failure
+	 */
 	public function create_dir($path)
 	{
 		$this->adapter->create_dir($path);