deal with phpstan warnings related to base authentication modules

classes/auth/base.php

@@ -8,7 +8,6 @@ abstract class Auth_Base extends Plugin implements IAuthModule {
 		$this->pdo = Db::pdo();
 	}
 
-	// compatibility wrapper, because of how pluginhost works (hook name == method name)
 	function hook_auth_user(...$args) {
 		return $this->authenticate(...$args);
 	}

classes/iauthmodule.php

@@ -1,5 +1,16 @@
 <?php
 interface IAuthModule {
+	/**
+	 * @param string $login
+	 * @param string $password
+	 * optional third string $service
+	 * @return int|false user_id
+	 */
 	function authenticate($login, $password); // + optional third parameter: $service
-	function hook_auth_user(...$args); // compatibility wrapper due to how hooks work
+
+	/** this is a pluginhost compatibility wrapper that invokes $this->authenticate(...$args) (Auth_Base)
+	 * @param mixed $args = ($login, $password, $service)
+	 * @return int|false user_id
+	 */
+	function hook_auth_user(...$args);
 }

classes/plugin.php

@@ -141,8 +141,24 @@ abstract class Plugin {
 		user_error("Dummy method invoked.", E_USER_ERROR);
 	}
 
-	function hook_auth_user($login, $password, $service) {
+	/** this is a pluginhost compatibility wrapper that invokes $this->authenticate(...$args) (Auth_Base)
+	 * @param mixed $args = ($login, $password, $service)
+	 * @return int|false user_id
+	 */
+	function hook_auth_user(...$args) {
 		user_error("Dummy method invoked.", E_USER_ERROR);
+		return false;
+	}
+
+	/** IAuthModule only
+	 * @param string $login
+	 * @param string $password
+	 * optional third string $service
+	 * @return int|false user_id
+	 */
+	function authenticate($login, $password) {
+		user_error("Dummy method invoked.", E_USER_ERROR);
+		return false;
 	}
 
 	function hook_hotkey_map($hotkeys) {

plugins/auth_internal/init.php

@@ -12,6 +12,7 @@ class Auth_Internal extends Auth_Base {
 		$host->add_hook($host::HOOK_AUTH_USER, $this);
 	}
 
+	/** @param string $service */
 	function authenticate($login, $password, $service = '') {
 
 		$otp = (int) ($_REQUEST["otp"] ?? 0);