From 8cf57c9ac359a4811b2b0aa5ebbc9c97817e0da1 Mon Sep 17 00:00:00 2001
From: Edoardo La Greca
Date: Tue, 2 Sep 2025 21:23:48 +0200
Subject: add documentation and missing parameter to auth

---
 lib/src/main/kotlin/ProtocolTranslator.kt | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

(limited to 'lib/src/main/kotlin/ProtocolTranslator.kt')

diff --git a/lib/src/main/kotlin/ProtocolTranslator.kt b/lib/src/main/kotlin/ProtocolTranslator.kt
index 4b3b91a..86564a5 100644
--- a/lib/src/main/kotlin/ProtocolTranslator.kt
+++ b/lib/src/main/kotlin/ProtocolTranslator.kt
@@ -32,8 +32,20 @@ interface ProtocolTranslator {
 
     /**
      * Perform authentication.
+     *
+     * 9P itself neither defines a user authentication protocol in its specification, nor requires the usage of a
+     * specific existing one. However, it provides a way of running an authentication protocol of choice on top of
+     * itself, as long as both the client and the server agree on one. Right after the server's `R-auth` message, using
+     * 9P's `read` and `write` messages on the authentication FID, it is possible to exchange authentication messages.
+     * This [auth] method performs both the 9P `auth` transaction and the successive authentication protocol.
+     *
+     * @param afid A new FID for authentication.
+     * @param uname The user identifier.
+     * @param aname The file tree to access.
+     * @param auther The [Authenticator] instance that provides one or more authentication protocols. This parameter is
+     * NineKt-specific and does not appear in the protocol specification.
      */
-    fun auth(afid: UInt, uname: String, aname: String)
+    fun auth(afid: UInt, uname: String, aname: String, auther: Authenticator)
 
     /**
      * Abort a message.
-- 
cgit v1.2.3