[ticket/16955] Add missing docblocks and fix unclear ones

PHPBB3-16955

build/psalm/stubs/apcu/apcu.php

@@ -1,4 +1,15 @@
 <?php
+/**
+ *
+ * This file is part of the phpBB Forum Software package.
+ *
+ * @copyright (c) phpBB Limited <https://www.phpbb.com>
+ * @license GNU General Public License, version 2 (GPL-2.0)
+ *
+ * For full copyright and license information, please see
+ * the docs/CREDITS.txt file.
+ *
+ */
 
 class APCUIterator implements Iterator
 {

build/psalm/stubs/redis/redis.php

@@ -15,7 +15,5 @@
 class Redis
 {
 	public const OPT_PREFIX = 2;
-
 	public const SERIALIZER_PHP = 1;
-
 }

phpBB/phpbb/auth/provider/oauth/oauth.php

@@ -827,8 +827,7 @@ class oauth extends base
 	 * Sets a redirect to the authorization uri.
 	 *
 	 * @param OAuth1Service|OAuth2Service $service		The external OAuth service
-	 * @return array									Array if an error occurred,
+	 * @return array|never								Array if an error occurred, won't return on success
-	 *													won't return on success
 	 */
 	protected function set_redirect($service)
 	{

phpBB/phpbb/db/migration/tool/permission.php

@@ -266,13 +266,13 @@ class permission implements \phpbb\db\migration\tool\tool_interface
 	* @param string $role_type The type (u_, m_, a_)
 	* @param string $role_description Description of the new role
 	*
-	* @return int|null Inserted SQL id or false if role already exists
+	* @return int|null Inserted SQL id or null if role already exists
 	*/
 	public function role_add($role_name, $role_type, $role_description = '')
 	{
 		if ($this->role_exists($role_name))
 		{
-			return;
+			return null;
 		}
 
 		$sql = 'SELECT MAX(role_order) AS max_role_order

phpBB/phpbb/files/factory.php

@@ -35,7 +35,7 @@ class factory
 	 *
 	 * @param string $name Service name
 	 *
-	 * @return object|bool Requested service or false if service could not be
+	 * @return object|false Requested service or false if service could not be
 	 *				found by the container
 	 */
 	public function get($name)

phpBB/phpbb/files/filespec.php

@@ -329,7 +329,7 @@ class filespec
 	 * Get mime type
 	 *
 	 * @param string $filename Filename that needs to be checked
-	 * @return string|false Mime type of supplied filename or false if mimetype could not be guessed
+	 * @return string Mime type of supplied filename or empty string if mimetype could not be guessed
 	 */
 	public function get_mimetype($filename)
 	{
@@ -343,7 +343,7 @@ class filespec
 			}
 		}
 
-		return $this->mimetype;
+		return $this->mimetype ?: '';
 	}
 
 	/**

phpBB/phpbb/files/filespec_storage.php

@@ -313,7 +313,7 @@ class filespec_storage
 	 * Get mime type
 	 *
 	 * @param string $filename Filename that needs to be checked
-	 * @return string|false Mime type of supplied filename or false if mimetype could not be guessed
+	 * @return string Mime type of supplied filename or empty string if mimetype could not be guessed
 	 */
 	public function get_mimetype($filename)
 	{
@@ -327,7 +327,7 @@ class filespec_storage
 			}
 		}
 
-		return $this->mimetype;
+		return $this->mimetype ?: '';
 	}
 
 	/**