diff --git a/classes/auth/base.php b/classes/auth/base.php
index 82ea06e1b..939a9d358 100644
--- a/classes/auth/base.php
+++ b/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);
 	}
diff --git a/classes/iauthmodule.php b/classes/iauthmodule.php
index e714cc6ca..39aae4cc2 100644
--- a/classes/iauthmodule.php
+++ b/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);
 }
diff --git a/classes/plugin.php b/classes/plugin.php
index 638cc2f50..bcd8c0de7 100644
--- a/classes/plugin.php
+++ b/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) {
diff --git a/plugins/auth_internal/init.php b/plugins/auth_internal/init.php
index 77f7596f0..b66f7719b 100644
--- a/plugins/auth_internal/init.php
+++ b/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);