Improve documentation

libquassel-client/src/main/kotlin/de/justjanne/libquassel/client/io/StreamChannel.kt

@@ -22,6 +22,9 @@ import java.util.zip.InflaterInputStream
 import javax.net.ssl.SSLContext
 import javax.net.ssl.SSLSocket
 
+/**
+ * Channel wrapping a Socket with support for TLS and compression layers
+ */
 class StreamChannel constructor(
   private val socket: Socket,
   private val inputStream: InputStream = socket.getInputStream(),
@@ -30,11 +33,17 @@ class StreamChannel constructor(
   private val input = ReadableWrappedChannel(inputStream)
   private val output = WritableWrappedChannel(outputStream)
 
+  /**
+   * Return metadata about the current TLS session, if enabled
+   */
   fun tlsInfo(): TlsInfo? {
     val sslSocket = socket as? SSLSocket ?: return null
     return TlsInfo.ofSession(sslSocket.session)
   }
 
+  /**
+   * Return a copy of the current channel with DEFLATE compression
+   */
   fun withCompression(): StreamChannel {
     return StreamChannel(
       socket,
@@ -43,6 +52,9 @@ class StreamChannel constructor(
     )
   }
 
+  /**
+   * Return a copy of the current channel with TLS
+   */
   fun withTLS(
     context: SSLContext,
   ): StreamChannel {
@@ -57,20 +69,34 @@ class StreamChannel constructor(
     return StreamChannel(sslSocket)
   }
 
+  /**
+   * Close the underlying streams and channels
+   */
   override fun close() {
     input.close()
     output.close()
     socket.close()
   }
 
+  /**
+   * Returns whether the current channel is open, can be read from and written to
+   */
   override fun isOpen(): Boolean {
     return !socket.isClosed
   }
 
+  /**
+   * Reads from the channel into a given byte buffer and returns the amount of
+   * written bytes
+   */
   override fun read(dst: ByteBuffer): Int {
     return input.read(dst)
   }
 
+  /**
+   * Write a given byte buffer to the channel and return the amount of written
+   * bytes
+   */
   override fun write(src: ByteBuffer): Int {
     return output.write(src)
   }

libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/models/BackendInfo.kt

@@ -10,10 +10,29 @@
 
 package de.justjanne.libquassel.protocol.models
 
+/**
+ * Model for storage/authenticator backend configuration
+ */
 data class BackendInfo(
+  /**
+   * Configuration entries
+   */
   val entries: List<SetupEntry>,
+  /**
+   * Whether or not this backend is default. Newer quassel clients use the first
+   * entry in the list instead of checking this field
+   */
   val isDefault: Boolean,
+  /**
+   * User-visible name of the backend
+   */
   val displayName: String,
+  /**
+   * User-visible description of the backend
+   */
   val description: String,
+  /**
+   * ID
+   */
   val backendId: String,
 )

libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/models/BackendInfoSerializer.kt

@@ -18,7 +18,13 @@ import de.justjanne.libquassel.protocol.variant.QVariant_
 import de.justjanne.libquassel.protocol.variant.into
 import de.justjanne.libquassel.protocol.variant.qVariant
 
+/**
+ * Handshake Serializer for [BackendInfo]
+ */
 object BackendInfoSerializer {
+  /**
+   * Serialize backend info into a [QVariantMap] (for further serialization)
+   */
   fun serialize(data: BackendInfo): QVariantMap = mapOf(
     "SetupKeys" to qVariant<QStringList>(
       data.entries.map(SetupEntry::key),
@@ -63,6 +69,9 @@ object BackendInfoSerializer {
     SetupEntry(key.into(""), displayName.into(""), defaultValue)
   } ?: defaults.map { (key, value) -> SetupEntry(key, key, value) }
 
+  /**
+   * Deserialize backend info from a [QVariantMap]
+   */
   fun deserialize(data: QVariantMap) = BackendInfo(
     entries = parseSetupEntries(
       data["SetupData"].into<QVariantList>(),

libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/models/SetupEntry.kt

@@ -12,8 +12,20 @@ package de.justjanne.libquassel.protocol.models
 
 import de.justjanne.libquassel.protocol.variant.QVariant_
 
+/**
+ * Model of a backend configuration entry
+ */
 data class SetupEntry(
+  /**
+   * Key for the configuration field
+   */
   val key: String,
+  /**
+   * User-visible display name
+   */
   val displayName: String,
+  /**
+   * Default value. The type of this value also determines the UI widget used.
+   */
   val defaultValue: QVariant_,
 )

libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/util/pairs.kt

@@ -10,10 +10,17 @@
 
 package de.justjanne.libquassel.protocol.util
 
+/**
+ * Returns a partitioned list of pairs
+ */
 fun <T> Iterable<T>.pairs(): List<Pair<T, T>> {
+  zipWithNext()
   return pairs { a, b -> Pair(a, b) }
 }
 
+/**
+ * Returns a partitioned list of pairs transformed with the given transformer
+ */
 inline fun <T, R> Iterable<T>.pairs(transform: (a: T, b: T) -> R): List<R> {
   val iterator = iterator()
   val result = mutableListOf<R>()

libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/util/triples.kt

@@ -10,10 +10,16 @@
 
 package de.justjanne.libquassel.protocol.util
 
+/**
+ * Returns a partitioned list of triples
+ */
 fun <T> Iterable<T>.triples(): List<Triple<T, T, T>> {
   return triples { a, b, c -> Triple(a, b, c) }
 }
 
+/**
+ * Returns a partitioned list of triples transformed with the given transformer
+ */
 inline fun <T, R> Iterable<T>.triples(transform: (a: T, b: T, c: T) -> R): List<R> {
   val iterator = iterator()
   val result = mutableListOf<R>()