[ticket/14285] Add comments

PHPBB3-14285

phpBB/phpbb/storage/controller/attachment.php

@@ -27,6 +27,9 @@ use Symfony\Component\HttpFoundation\Request as symfony_request;
 use Symfony\Component\HttpFoundation\RedirectResponse;
 use Symfony\Component\HttpFoundation\ResponseHeaderBag;
 
+/**
+ * Controller for /download/attachment/{id} routes
+ */
 class attachment extends controller
 {
 	/** @var auth */
@@ -47,7 +50,21 @@ class attachment extends controller
 	/** @var user */
 	protected $user;
 
-	public function __construct(auth $auth, service $cache, config $config, $content_visibility, driver_interface $db, dispatcher $dispatcher, request $request, storage $storage, symfony_request $symfony_request, user $user)
+	/**
+	 * Constructor
+	 *
+	 * @param auth					$auth
+	 * @param service				$cache
+	 * @param config				$config
+	 * @param content_visibility	$content_visibility
+	 * @param driver_interface		$db
+	 * @param dispatcher_interface	$dispatcher
+	 * @param request				$request
+	 * @param storage				$storage
+	 * @param symfony_request		$symfony_request
+	 * @param user					$user
+	 */
+	public function __construct(auth $auth, service $cache, config $config, content_visibility $content_visibility, driver_interface $db, dispatcher $dispatcher, request $request, storage $storage, symfony_request $symfony_request, user $user)
 	{
 		parent::__construct($cache, $db, $storage, $symfony_request);
 
@@ -59,6 +76,9 @@ class attachment extends controller
 		$this->user = $user;
 	}
 
+	/**
+	 * {@inheritdoc}
+	 */
 	public function handle($id)
 	{
 		$attach_id = (int) $id;

phpBB/phpbb/storage/controller/avatar.php

@@ -20,13 +20,26 @@ use phpbb\storage\storage;
 use Symfony\Component\HttpFoundation\Request as symfony_request;
 use Symfony\Component\HttpFoundation\ResponseHeaderBag;
 
+/**
+ * Controller for /download/avatar/{file} routes
+ */
 class avatar extends controller
 {
 	/** @var config */
 	protected $config;
 
+	/** @var array */
 	protected $allowed_extensions = ['png', 'gif', 'jpg', 'jpeg'];
 
+	/**
+	 * Constructor
+	 *
+	 * @param service				$cache
+	 * @param config				$config
+	 * @param driver_interface		$db
+	 * @param storage				$storage
+	 * @param symfony_request		$symfony_request
+	 */
 	public function __construct(service $cache, config $config, driver_interface $db, storage $storage, symfony_request $symfony_request)
 	{
 		parent::__construct($cache, $db, $storage, $symfony_request);
@@ -34,6 +47,9 @@ class avatar extends controller
 		$this->config = $config;
 	}
 
+	/**
+	 * {@inheritdoc}
+	 */
 	public function handle($file)
 	{
 		$file = $this->decode_avatar_filename($file);
@@ -41,6 +57,9 @@ class avatar extends controller
 		return parent::handle($file);
 	}
 
+	/**
+	 * {@inheritdoc}
+	 */
 	protected function is_allowed($file)
 	{
 		$ext = substr(strrchr($file, '.'), 1);
@@ -49,6 +68,13 @@ class avatar extends controller
 		return strpos($file, '.') && in_array($ext, $this->allowed_extensions);
 	}
 
+	/**
+	 * Decode avatar filename
+	 *
+	 * @param string		$file		Filename
+	 *
+	 * @return string Filename in filesystem
+	 */
 	protected function decode_avatar_filename($file)
 	{
 		$avatar_group = false;
@@ -65,6 +91,9 @@ class avatar extends controller
 		return $this->config['avatar_salt'] . '_' . ($avatar_group ? 'g' : '') . $file . '.' . $ext;
 	}
 
+	/**
+	 * {@inheritdoc}
+	 */
 	protected function prepare($file)
 	{
 		$disposition = $this->response->headers->makeDisposition(

phpBB/phpbb/storage/controller/controller.php

@@ -20,6 +20,9 @@ use phpbb\storage\storage;
 use phpbb\storage\streamed_response;
 use Symfony\Component\HttpFoundation\Request as symfony_request;
 
+/**
+ * Generic controller for storage
+ */
 class controller
 {
 	/** @var service */
@@ -37,6 +40,14 @@ class controller
 	/** @var symfony_request */
 	protected $symfony_request;
 
+	/**
+	 * Constructor
+	 *
+	 * @param service				$cache
+	 * @param driver_interfacd		$db
+	 * @param storage				$storage
+	 * @param symfony_request		$symfony_request
+	 */
 	public function __construct(service $cache, driver_interface $db, storage $storage, symfony_request $symfony_request)
 	{
 		$this->cache = $cache;
@@ -46,6 +57,15 @@ class controller
 		$this->response = new streamed_response();
 	}
 
+	/**
+	 * Handler
+	 *
+	 * @param string		$file		File path
+	 *
+	 * @throws \phpbb\exception\http_exception when can't access $file
+	 *
+	 * @return \Symfony\Component\HttpFoundation\StreamedResponse a Symfony response object
+	 */
 	public function handle($file)
 	{
 		if (!$this->is_allowed($file))
@@ -68,16 +88,35 @@ class controller
 		return $this->response;
 	}
 
+	/**
+	 * If the user is allowed to download the file
+	 *
+	 * @param string		$file		File path
+	 *
+	 * @return bool
+	 */
 	protected function is_allowed($file)
 	{
 		return true;
 	}
 
+	/**
+	 * Check if file exists
+	 *
+	 * @param string		$file		File path
+	 *
+	 * @return bool
+	 */
 	protected function file_exists($file)
 	{
 		return $this->storage->exists($file);
 	}
 
+	/**
+	 * Prepare response
+	 *
+	 * @param string		$file		File path
+	 */
 	protected function prepare($file)
 	{
 		$this->response->setPublic();
@@ -132,9 +171,7 @@ class controller
 	/**
 	* Garbage Collection
 	*
-	* @param bool $exit		Whether to die or not.
-	*
-	* @return null
+	* @param bool $exit		Whether to die or not
 	*/
 	protected function file_gc()
 	{