Bit of docs

modules/db/src/main/scala/gs/smolban/db/doobie/DoobieAuthDb.scala

@@ -78,7 +78,7 @@ final class DoobieAuthDb[F[_]: Sync](
     initialPermissions: PermissionSet,
     createdAt: CreatedAt
   ): F[ConnectionIO[Either[DbError, User]]] =
-    // Prepare Password
+    // Prepare Password -- exchange the encrypted version for a hashed version.
     exchangeEncryptedForHash(initialPassword.unwrap()).map { passwordHash =>
       // Insert the base user record.
       val accountId = AccountId.generate()
@@ -129,6 +129,19 @@ final class DoobieAuthDb[F[_]: Sync](
         }
     }
 
+  /** Exchange an encrypted set of bytes for a hashed set of bytes. This is used
+    * for credential updates. Performs a decrypt followed by a hash.
+    *
+    * This function is the _only time_ an incoming credential exists in clear
+    * text. Note that _generated credentials_ for service accounts are returned
+    * in clear text (once) so that the user can record them for integration into
+    * other applications.
+    *
+    * @param rsa
+    *   The RSA encrypted bytes.
+    * @return
+    *   The hashed version of the previously-encrypted data.
+    */
   private def exchangeEncryptedForHash(rsa: RsaEncryptedBytes): F[Argon2Hash] =
     rsaDecryption.decrypt(rsa).flatMap(argon2.calculateHash)